@nervur-org/dock 0.5.0 → 0.6.0

package/dist/beings/presence.js

@@ -1,5 +1,10 @@
 import { Avatar, PUSHER, USER } from './avatar.js';
-import { FACULTIES, join } from '../dock/index.js';
+import { LOCATION } from '../box/location.js';
+import { NOTIFICATIONS } from '../box/notifications.js';
+import { PUSH } from '../box/push.js';
+import { TIMER } from '../box/timer.js';
+import { join } from '../box/join.js';
+import { titleOf } from '../box/contract.js';
 export class Presence extends Avatar {
     // Her world's user being sees the box, and nobody else: the way back she
     // handed over at the join is the one occupant who may ask through her.
@@ -12,10 +17,14 @@ export class Presence extends Avatar {
     static skips(id) {
         return id === USER;
     }
-    // Which names the box lent her, by name, settled after birth.
+    // What a device can do that a world may want: the contracts she asks her
+    // box for, each held under the word the contract calls itself.
+    static needs = [LOCATION, NOTIFICATIONS, PUSH, TIMER];
+    // Which of them the box lent her, by that word, settled after birth.
     lent;
     constructor(stance) {
         super(stance);
-        this.lent = Promise.all(Object.keys(FACULTIES).map(async (name) => [name, await join(this, name)])).then((all) => Object.fromEntries(all));
+        const C = this.constructor;
+        this.lent = Promise.all(C.needs.map(async (c) => [titleOf(c), await join(this, c, titleOf(c))])).then((all) => Object.fromEntries(all));
     }
 }

package/dist/beings/setup.d.ts

@@ -1,3 +1,6 @@
 import type { Hosted } from 'nervur/harbor';
-export declare function setupHome(hosted: Hosted, user: string): Promise<void>;
-export declare function setup(hosted: Hosted, user: string, cls?: string): Promise<void>;
+export type Setup = {
+    front: string;
+    home: string;
+};
+export declare function setup(hosted: Hosted, user: string, classes?: Partial<Setup>): Promise<void>;

package/dist/beings/setup.js

@@ -1,11 +1,12 @@
 import { DESK, HOME } from './user.js';
+const SETUP = { front: 'beings/Desk', home: 'beings/User' };
 // The root boots and steps back: it invites an owner on the ward's own pk
-// and the user being knocks for it, so from then on placing a being,
+// and the home being knocks for it, so from then on placing a being,
 // minting a way in or removing one is an ask on her, shown by her gate to a
 // device that may mint, and the box is not logged into for it. The same
 // standing a user being of another ward takes to own this one; here it is
 // her own.
-export async function setupHome(hosted, user) {
+async function setupHome(hosted, user) {
     const inv = (await hosted.ask('invite', { being: hosted.pk, id: HOME }));
     if ('error' in inv)
         throw new Error(`home: ${inv.error}`);
@@ -13,27 +14,27 @@ export async function setupHome(hosted, user) {
     if (placed.taken !== HOME)
         throw new Error(`home: ${placed.error ?? 'she could not take her own door'}`);
 }
-// The ward's home being is a `User` unless the device says which class: an
-// organisation's ward has an org's home being, of the estate's own class,
-// and everything else of setup, the desk and the door, is placed on her the
-// same way.
-export async function setup(hosted, user, cls = 'User') {
-    if (!/^[\w.-]+$/.test(user) || user === 'desk')
-        throw new Error(`a user is a word, and not desk: ${user}`);
+// Everything setup places is placed the same way whatever the classes are:
+// a home key the front already holds is refused by the ward, as any key
+// taken is.
+export async function setup(hosted, user, classes = {}) {
+    const { front, home } = { ...SETUP, ...classes };
+    if (!/^[\w.-]+$/.test(user))
+        throw new Error(`a user is a word: ${user}`);
     const boot = async (args) => {
         const out = (await hosted.ask('boot', args));
         if (out.error)
             throw new Error(`init: ${out.error}`);
     };
-    await boot({ key: 'desk', class: 'Desk' });
-    const pub = (await hosted.ask('public', { key: 'desk' }));
+    await boot({ key: DESK, class: front });
+    const pub = (await hosted.ask('public', { key: DESK }));
     if (pub.error)
         throw new Error(`init: ${pub.error}`);
-    await boot({ key: user, class: cls });
+    await boot({ key: user, class: home });
     const inv = (await hosted.ask('invite', { being: user, id: DESK }));
-    // the desk's first hello names her, since a being does not know her own key
-    const placed = (await hosted.ask('knock', { being: 'desk', id: `user:${user}`, invitation: inv, method: 'hello', args: { name: user } }));
+    // the front's first hello names her, since a being does not know her own key
+    const placed = (await hosted.ask('knock', { being: DESK, id: `user:${user}`, invitation: inv, method: 'hello', args: { name: user } }));
     if (placed.taken !== `user:${user}`)
-        throw new Error('init: the desk could not reach the user being');
+        throw new Error('init: the front could not reach the home being');
     await setupHome(hosted, user);
 }

package/dist/beings/user.d.ts

@@ -1,5 +1,5 @@
-import type { Asker, Blueprint, Invitation, JsonObject, OccupantRecord, Stance } from 'nervur';
-import { Carrier } from './carry.ts';
+import { Being } from 'nervur';
+import type { Asker, Blueprint, Invitation, JsonObject, OccupantRecord, Reply, Stance } from 'nervur';
 export declare const DESK = "desk";
 export declare const BELL = "bell";
 export declare const HOME = "home";
@@ -8,11 +8,12 @@ declare const rootMinted: (occ: OccupantRecord | undefined) => boolean;
 declare const mayWake: (occ: OccupantRecord | undefined) => boolean;
 declare const mayMint: (occ: OccupantRecord | undefined) => boolean;
 declare const mayRevoke: (occ: OccupantRecord | undefined) => boolean;
-export declare class User extends Carrier {
+export declare class User extends Being {
     #private;
     static carries(occ: OccupantRecord | undefined): boolean;
     static hidden(id: string): boolean;
     static shows(id: string, occ: OccupantRecord | undefined): boolean;
+    answer(asker: Asker, method?: string, args?: JsonObject): Promise<Reply>;
     static cells: {
         name: string;
         reports: JsonObject[];

package/dist/beings/user.js

@@ -7,9 +7,13 @@
 // client identity the desk established. A device she let mint brings the
 // next one in, so a human adds a device from a device already in and only
 // the first one has to come from the root, on the box.
-import { isInvitation, isSilence, isWord, wordOf } from 'nervur';
-import { Carrier } from './carry.js';
-import { PUSH, banner, isToken, join, sealBanner } from '../dock/index.js';
+import { Being, isInvitation, isSilence, isWord, wordOf } from 'nervur';
+import { CARRIES, carry } from './carry.js';
+import { banner, isToken, sealBanner } from '../box/index.js';
+import { PUSH as PUSHING } from '../box/push.js';
+import { join } from '../box/join.js';
+// Her standing at the box's push faculty, under an id of her own.
+const PUSH = 'push';
 export const DESK = 'desk';
 // The prefix her doorbell standings are filed under, one per device: the
 // way she rings that device, and never a way anything else may ask on.
@@ -61,12 +65,12 @@ const mayMint = (occ) => isDesk(occ) || (isDevice(occ) && held(occ).mint);
 // it has the act out of reach and the root's own removals instead, and that
 // is a choice an org makes rather than one the dock makes for it.
 const mayRevoke = (occ) => isDesk(occ) || (isDevice(occ) && held(occ).revoke);
-// She carries her standings, acme, the calendar, the house, for a device the
-// human allowed to reach them at the exchange: the note says so. A device
-// without the note sees her own asks alone, and a model sees acme only
+// She carries her standings, her org, the calendar, the house, for a device
+// the human allowed to reach them at the exchange: the note says so. A device
+// without the note sees her own asks alone, and a model sees the org only
 // because the human said it may. A device the root minted reaches: the root
 // is the owner of everything she holds and chose to mint it.
-export class User extends Carrier {
+export class User extends Being {
     static carries(occ) {
         return isDevice(occ) && held(occ).reach;
     }
@@ -75,20 +79,23 @@ export class User extends Carrier {
     // not bound yet, a phone in a tunnel. Nothing delivered spends nothing,
     // so the invitation is tried again at the next push.
     // The bell standing is plumbing and carries nothing: a device that may
-    // reach what she holds sees acme and the house, and never the envoy that
+    // reach what she holds sees the org and the house, and never the envoy that
     // wakes it. Her ways back are plumbing too, and a way back to a presence
     // being carries that device's faculties, `to:phone-location-where`, which
     // is how a model at home learns where the human is.
     static hidden(id) {
-        return super.hidden(id) || id === PUSH || id.startsWith(`${BELL}:`);
+        return CARRIES.hidden(id) || id === PUSH || id.startsWith(`${BELL}:`);
     }
     // Her own door is carried to a device that may mint, and to nobody else:
     // `mint` is the word for a device trusted to change who is in her world,
     // and owning the world from that device is that trust said in full. A
-    // device that reaches sees acme and the house, and no `home-boot`.
+    // device that reaches sees the org and the house, and no `home-boot`.
     static shows(id, occ) {
         return id !== HOME || held(occ).mint;
     }
+    answer(asker, method, args = {}) {
+        return carry(this, asker, method, args, (a, m, g) => super.answer(a, m, g));
+    }
     static cells = { name: '', reports: [], ways: {}, outbox: {} };
     // Her standing at the box's push faculty, taken again at every birth: a
     // standing points at a being and not at a box, and a ward that moved is
@@ -103,7 +110,7 @@ export class User extends Carrier {
     #push;
     constructor(stance) {
         super(stance);
-        this.#push = join(this, PUSH);
+        this.#push = join(this, PUSHING, PUSH);
     }
     // A world whose own being she is, is a home: a device reaching her holds
     // a standing at home and not a membership, and she says so in her notes,

package/dist/{dock → box}/agents.d.ts

@@ -1,6 +1,6 @@
-import type { Asker, JsonObject, OccupantRecord } from 'nervur';
+import type { Asker, JsonObject, OccupantRecord, Stance } from 'nervur';
+import type { Harborage } from './box.ts';
 import { Faculty } from './faculty.ts';
-export declare const AGENTS = "agents";
 export type Process = {
     command: string;
     args: string[];
@@ -25,6 +25,7 @@ export type Side = {
 };
 export type Runner = (row: Row) => Promise<Side>;
 declare const root: (_occ: OccupantRecord | undefined, asker: Asker) => boolean;
+export declare const AGENTS: import("nervur").Blueprint;
 export declare class Agents extends Faculty {
     #private;
     static cells: JsonObject;
@@ -90,10 +91,12 @@ export declare class Agents extends Faculty {
             for: typeof root;
         };
     };
-    runner: Runner | undefined;
+    static fulfils: import("nervur").Blueprint[];
+    static stands(): boolean;
+    readonly runner: Runner | undefined;
     readonly running: Map<string, Side>;
+    constructor(stance: Stance, box?: Harborage, runner?: Runner);
     private get rows();
-    start(runner: Runner): Promise<void>;
     keep(args: JsonObject): Promise<JsonObject>;
     drop(args: JsonObject): Promise<JsonObject>;
     list(): JsonObject;

package/dist/{dock → box}/agents.js

@@ -1,58 +1,51 @@
 // SPDX-License-Identifier: Apache-2.0
-// The box's agents: `agents`, one faculty of the dock ward, standing for the
-// one thing a box does on an event as the timer does on a moment: run a
-// process. What she holds is the table of agents, in her cells and in no
-// file, placed by the root with `keep` the way a schedule is placed on the
-// clock, so a box has one place its state is and the daemon reads no recipe.
+// The box's agents: on an event, run something for an identity, as the timer
+// does on a moment. What she holds is the table of agents in her cells,
+// placed by the root with `keep`. A row names a client identity, the ward
+// she is admitted into, and what runs for her: a process, a command with its
+// args in its folder, or a model at a url.
 //
-// A row names a client identity, the ward she is admitted into, and what
-// runs for her, one of two: a process, a command with its args in its
-// folder, or a model that speaks function calling, a base URL and a model
-// name, OpenRouter, LM Studio, anything with a tools array. At her birth
-// on a daemon she admits each identity into its ward as an avatar, through
-// the box's own way in, and stands the side her row says over that avatar.
-// A push from the user being is the event either way: the agent side runs
-// the command with it and reports what it printed; the runner side turns it
-// into a turn of the model's conversation with her describe as tools. The
-// queue is in the avatar's cells, so it survives a restart; the row is in
-// hers, so the agent comes back with the box.
-//
-// The daemon hands her how to run a row, as it hands the grants faculty how
-// to persist: running an agent is admitting through a socket only a daemon
-// has, and this file is not in the dock's index, since a tab has no process
-// to spawn. A box with no runner keeps the table and runs nobody.
+// How a row runs is the terrain's, since admitting through a socket and
+// spawning a process are things only a daemon has, so it is handed to her
+// at birth in the class body the terrain brings; this body runs nobody and
+// stands nowhere. Every row runs once the box is up.
 import { OWNER } from 'nervur';
+import { contract } from './contract.js';
 import { Faculty } from './faculty.js';
-// The name the dock ward holds her under.
-export const AGENTS = 'agents';
 export const isProcess = (r) => 'command' in r;
-// The root and nobody else, as the clock gates `keep`: an ask gated this way
-// is the device's own and cannot be reached through a door.
 const root = (_occ, asker) => asker.id === OWNER;
 const ROW = {
     type: 'object',
     properties: { id: { type: 'string' }, ward: { type: 'string' }, command: { type: 'string' }, args: { type: 'array', items: { type: 'string' } }, dir: { type: 'string' }, url: { type: 'string' }, model: { type: 'string' }, key: { type: 'string' }, turns: { type: 'number' } },
     required: ['id', 'ward'],
 };
+const ASKS = {
+    keep: { description: 'add an agent, or replace the one of that id: an identity, her ward, and what runs for her, a command with args in a folder, or a model at a url', input: ROW, for: root },
+    drop: { description: 'stop an agent and forget her row; the avatar in her ward stays until the root removes her', input: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] }, for: root },
+    list: { description: 'every agent she holds', input: { type: 'object' }, for: root },
+};
+// What the box's own code needs from the faculty that runs its agents.
+export const AGENTS = contract('agents', ASKS);
 export class Agents extends Faculty {
     static cells = { watched: {}, minted: 0, agents: {} };
-    static asks = {
-        keep: { description: 'add an agent, or replace the one of that id: an identity, her ward, and what runs for her, a command with args in a folder, or a model at a url', input: ROW, for: root },
-        drop: { description: 'stop an agent and forget her row; the avatar in her ward stays until the root removes her', input: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] }, for: root },
-        list: { description: 'every agent she holds', input: { type: 'object' }, for: root },
-    };
+    static asks = ASKS;
+    static fulfils = [AGENTS];
+    static stands() {
+        return false;
+    }
     runner;
     running = new Map();
+    constructor(stance, box, runner) {
+        super(stance, box);
+        this.runner = runner;
+        this.box.up(async () => {
+            for (const row of Object.values(this.rows))
+                await this.#run(row);
+        });
+    }
     get rows() {
         return this.cells.agents;
     }
-    // Every row up, once the daemon has handed the runner. Called after the
-    // wards are hosted, since an avatar is admitted into one of them.
-    async start(runner) {
-        this.runner = runner;
-        for (const row of Object.values(this.rows))
-            await this.#run(row);
-    }
     async #run(row) {
         if (!this.runner)
             return;

package/dist/{dock → box}/apns.d.ts

@@ -1,4 +1,4 @@
-import type { Ring, Token } from './push.ts';
+import type { Ring, Token } from './ring.ts';
 export declare function pkcs8(pem: string): Uint8Array;
 export type Apns = {
     key: string;

package/dist/{dock → box}/apns.js

@@ -45,10 +45,10 @@ export async function provider(a, made) {
 // The device a token names, or nothing a ring may send. It is checked
 // where a human can read why rather than by Apple two hops later.
 export function device(token) {
-    const device = token.device;
-    if (typeof device !== 'string' || !/^[0-9a-fA-F]{8,200}$/.test(device))
+    const named = token.device;
+    if (typeof named !== 'string' || !/^[0-9a-fA-F]{8,200}$/.test(named))
         throw new Error('an apns token is a device token');
-    return device;
+    return named;
 }
 // One ring, as Apple reads it: the path, the headers and the body. A ring
 // with a banner is an alert Apple must show, and `mutable-content` is what

package/dist/box/box.d.ts

@@ -0,0 +1,9 @@
+export type Harborage = {
+    save(): Promise<void>;
+    now(): number;
+    up(work: () => Promise<void>): void;
+};
+export declare const ALONE: Harborage;
+export declare function harborageOver(save: () => Promise<void>, now?: () => number): Harborage & {
+    raise(): Promise<void>;
+};

package/dist/box/box.js

@@ -0,0 +1,18 @@
+// The harborage a faculty holds when none was handed: a suite's ward, which
+// keeps nothing, reads the runtime's clock, and does its work at once.
+export const ALONE = { save: () => Promise.resolve(), now: () => Date.now(), up: (work) => void work().catch(() => { }) };
+// A harborage over a ward's save, raised by the terrain once the box is up.
+export function harborageOver(save, now = () => Date.now()) {
+    let waiting = [];
+    const run = (work) => work().catch(() => { });
+    return {
+        save,
+        now,
+        up: (work) => (waiting ? void waiting.push(work) : void run(work)),
+        raise: async () => {
+            const held = waiting ?? [];
+            waiting = null;
+            await Promise.all(held.map(run));
+        },
+    };
+}

package/dist/box/contract.d.ts

@@ -0,0 +1,6 @@
+import type { AskSpec, Blueprint } from 'nervur';
+export type Contract = Blueprint;
+export declare function contract(title: string, asks: Record<string, AskSpec>): Contract;
+export declare const nameOf: (c: Contract) => Promise<string>;
+export declare const titleOf: (c: Contract) => string;
+export declare function covers(held: Blueprint, c: Contract): boolean;

package/dist/box/contract.js

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: Apache-2.0
+// A contract: what a caller needs from a faculty, said as a blueprint and
+// nothing else, so it is written, read and hashed exactly as a describe is.
+// It is known by its digest, and that digest is the name a box lends under.
+// Nothing enforces it, as Quo enforces no blueprint: the caller reads the
+// describe she was handed and decides with `covers`.
+import { canonical, digest } from 'nervur';
+// A contract out of the asks a class declares. Descriptions stay behind,
+// since they are words for a reader and a reworded sentence must not move a
+// name. The title is the contract's own word for itself.
+export function contract(title, asks) {
+    return {
+        asks: Object.entries(asks).map(([name, spec]) => ({ name, input: spec.input ?? { type: 'object' }, ...(spec.output !== undefined ? { output: spec.output } : {}) })),
+        notes: { title },
+    };
+}
+// The name a contract is lent under.
+export const nameOf = (c) => digest(c);
+// The word a contract calls itself.
+export const titleOf = (c) => {
+    const t = c.notes?.title;
+    return typeof t === 'string' ? t : '';
+};
+// Whether a blueprint covers a contract, ask by ask: every ask the contract
+// names stands in it with the same input, and the same output where the
+// contract says one, in the canonical form. It may carry asks of its own.
+export function covers(held, c) {
+    const byName = new Map(held.asks.map((a) => [a.name, a]));
+    return c.asks.every((want) => {
+        const got = byName.get(want.name);
+        if (!got || canonical(got.input) !== canonical(want.input))
+            return false;
+        return want.output === undefined || (got.output !== undefined && canonical(got.output) === canonical(want.output));
+    });
+}

package/dist/{dock → box}/dialers.d.ts

@@ -1,11 +1,12 @@
-import type { Asker, JsonObject, OccupantRecord } from 'nervur';
+import type { Asker, JsonObject, OccupantRecord, Stance } from 'nervur';
 import { type Dialer, type Harbor } from 'nervur/harbor';
+import type { Harborage } from './box.ts';
 import { Faculty } from './faculty.ts';
-export declare const DIALERS = "dialers";
 export type Row = {
     url: string;
 };
 declare const root: (_occ: OccupantRecord | undefined, asker: Asker) => boolean;
+export declare const DIALERS: import("nervur").Blueprint;
 export declare class Dialers extends Faculty {
     #private;
     static cells: JsonObject;
@@ -44,10 +45,12 @@ export declare class Dialers extends Faculty {
             for: typeof root;
         };
     };
-    harbor: Harbor | undefined;
+    static fulfils: import("nervur").Blueprint[];
+    static stands(): boolean;
+    readonly harbor: Harbor | undefined;
     readonly open: Map<string, Dialer>;
+    constructor(stance: Stance, box?: Harborage, harbor?: Harbor);
     private get rows();
-    start(harbor: Harbor): void;
     keep(args: JsonObject): JsonObject;
     drop(args: JsonObject): JsonObject;
     list(): JsonObject;

package/dist/box/dialers.js

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: Apache-2.0
+// The box's lines: a socket held to another box's quo. route, one per row,
+// announcing this harbor's wards on open and reconnecting when a line drops.
+// The rows are her cells, placed by the root with `keep`. The harbor she
+// dials for is the terrain's, handed at birth in the class body it brings;
+// this body dials nothing and stands nowhere. Every row is dialed once the
+// box is up, and a row kept after that is dialed at once.
+import { OWNER } from 'nervur';
+import { dial } from 'nervur/harbor';
+import { contract } from './contract.js';
+import { Faculty } from './faculty.js';
+const root = (_occ, asker) => asker.id === OWNER;
+const URL_ = { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] };
+const ASKS = {
+    keep: { description: 'hold a socket to that quo. route, from now and from every boot, until it is dropped', input: URL_, for: root },
+    drop: { description: 'close the socket to that route and forget it', input: URL_, for: root },
+    list: { description: 'every route she dials, and whether the line is open now', input: { type: 'object' }, for: root },
+};
+// What the box's own code needs from the faculty that holds its lines.
+export const DIALERS = contract('dialers', ASKS);
+export class Dialers extends Faculty {
+    static cells = { watched: {}, minted: 0, dialers: {} };
+    static asks = ASKS;
+    static fulfils = [DIALERS];
+    static stands() {
+        return false;
+    }
+    harbor;
+    open = new Map();
+    #up = false;
+    constructor(stance, box, harbor) {
+        super(stance, box);
+        this.harbor = harbor;
+        this.box.up(() => {
+            this.#up = true;
+            for (const row of Object.values(this.rows))
+                this.#dial(row.url);
+            return Promise.resolve();
+        });
+    }
+    get rows() {
+        return this.cells.dialers;
+    }
+    #dial(url) {
+        if (!this.harbor || !this.#up || this.open.has(url))
+            return;
+        this.open.set(url, dial(this.harbor, url));
+    }
+    keep(args) {
+        const url = args.url;
+        if (typeof url !== 'string' || !/^https?:\/\/\S+$/.test(url))
+            return { error: 'url is the quo. route of the harbor dialed, over http or https' };
+        const clean = url.replace(/\/$/, '');
+        this.rows[clean] = { url: clean };
+        this.#dial(clean);
+        return { kept: clean };
+    }
+    drop(args) {
+        const url = typeof args.url === 'string' ? args.url.replace(/\/$/, '') : '';
+        if (!this.rows[url])
+            return { error: 'no such route' };
+        this.open.get(url)?.close();
+        this.open.delete(url);
+        delete this.rows[url];
+        return { dropped: url };
+    }
+    list() {
+        return { dialers: Object.keys(this.rows).map((url) => ({ url, open: this.open.get(url)?.socket !== null && this.open.has(url) })) };
+    }
+    // The device puts the box down: every line closes, the rows stay.
+    close() {
+        for (const d of this.open.values())
+            d.close();
+        this.open.clear();
+    }
+}