@nervur-org/dock 0.3.0

package/dist/beings/avatar.js

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: Apache-2.0
+// The avatar. Someone outside Quo's voice: a human at a screen, a model at
+// an MCP client, a model in an API loop. One class for every side. She holds
+// exactly one standing, `user`, and everything her side asks goes through
+// it; the user being reaches her only to push, and she hands the push to
+// every side she has. A side is in-process with her, holds the object, and
+// calls the four methods below: one of the two ways in, `enter` behind a
+// route's proof or `join` with an invitation, then `tools` and `call`.
+// Nothing of a side is in her cells.
+import { isSilence, isWord, wordOf } from '@nervur-org/nervur';
+import { Carrier } from './carry.js';
+// Her one standing, and the id under which the user being pushes to her.
+// Two ids for one far being, because standings and occupants share one
+// namespace and a record holds one or the other.
+export const USER = 'user';
+export const PUSHER = 'user:push';
+// A carrier who carries for nobody, until a subclass says who: the presence
+// being carries the box's faculties to her user being, and a bare avatar
+// holds one standing and shows nothing of it.
+export class Avatar extends Carrier {
+    static cells = { inbox: [] };
+    static asks = {
+        notify: { description: 'a push from the user being', input: { type: 'object' }, for: (occ) => occ?.id === PUSHER },
+    };
+    // Her sides' ears. One identity is one avatar for life, and two sessions
+    // of that identity are two sides on her at once, so a push goes to every
+    // ear present; each side adds its own on open and removes it on close.
+    // Dropped if there is none.
+    ears = new Set();
+    // ---- what the user being may ask her
+    notify(args) {
+        this.cells.inbox.push(args);
+        for (const ear of this.ears)
+            ear(args);
+        return { notified: true };
+    }
+    // ---- what her side calls. Not asks: nobody reaches these through a door.
+    // The credential exchange's last step. `desk` is the desk's public
+    // invitation, `proof` is what the route produced. She knocks the desk as a
+    // stranger, gets an invitation the user being minted, and joins with it. A
+    // knock on a public invitation births nothing, so she holds no standing at
+    // the desk afterwards. If she already holds `user`, this is a reconnect and
+    // nothing is minted.
+    async enter(desk, proof) {
+        if (this.standings[USER])
+            return this.tools();
+        const inv = await this.knock(desk, 'device', { proof });
+        if (isSilence(inv))
+            return { error: 'silence' };
+        if (isWord(inv))
+            return { error: wordOf(inv) };
+        if (!inv || typeof inv !== 'object' || Array.isArray(inv) || 'error' in inv)
+            return inv ?? { error: 'no invitation' };
+        return this.join(inv);
+    }
+    // Knock with an invitation, hand the far being one back so she can push,
+    // and take her as `user`. The only moment a standing is born here. A being
+    // who answers the hello with an error object is a being who answered: she
+    // is taken all the same, and the way back she did not take is dropped, so
+    // any world's public being may admit a guest, hello or not.
+    async join(invitation) {
+        if (this.standings[USER]) {
+            // A standing the far being removed is not one: she drops it and joins
+            // afresh, so an identity forgotten at the user being can be let in again.
+            const had = await this.tools();
+            if (!('error' in had) || had.error !== 'removed')
+                return had;
+            this.standings.remove(USER);
+            this.occupants.remove(PUSHER);
+        }
+        const mine = await this.invite(PUSHER);
+        if (mine === null)
+            return { error: 'user is taken' };
+        const out = await this.knock(invitation, 'hello', { invitation: mine });
+        if (isSilence(out) || isWord(out)) {
+            this.occupants.remove(PUSHER);
+            return { error: isSilence(out) ? 'silence' : wordOf(out) };
+        }
+        if (out !== null && typeof out === 'object' && !Array.isArray(out) && 'error' in out)
+            this.occupants.remove(PUSHER);
+        await this.take(USER, invitation);
+        return this.tools();
+    }
+    // Her describe, as the user being shows it to her. This is the tool list.
+    async tools() {
+        const st = this.standings[USER];
+        if (!st)
+            return { error: 'not joined' };
+        const bp = await st.ask();
+        if (isSilence(bp) || isWord(bp))
+            return { error: isSilence(bp) ? 'silence' : wordOf(bp) };
+        return bp;
+    }
+    // One call from the side, one ask on the standing. The three words pass
+    // through untouched; the side renders them.
+    call(name, args = {}, wanted) {
+        const st = this.standings[USER];
+        return st ? st.ask(name, args, wanted) : Promise.resolve({ error: 'not joined' });
+    }
+}

package/dist/beings/carry.d.ts

@@ -0,0 +1,12 @@
+import { Being } from '@nervur-org/nervur';
+import type { Asker, Blueprint, JsonObject, OccupantRecord, Reply } from '@nervur-org/nervur';
+export declare class Carrier extends Being {
+    static carries(_occupant: OccupantRecord | undefined, _asker: Asker): boolean;
+    static hidden(id: string): boolean;
+    static skips(_id: string): boolean;
+    static shows(_id: string, _occupant: OccupantRecord | undefined, _asker: Asker): boolean;
+    private get carried();
+    private get looks();
+    blueprint(asker: Asker): Promise<Blueprint>;
+    answer(asker: Asker, method?: string, args?: JsonObject): Promise<Reply>;
+}

package/dist/beings/carry.js

@@ -0,0 +1,174 @@
+// SPDX-License-Identifier: Apache-2.0
+// A carrier: a being who shows the asks of the standings she holds as asks
+// of her own, and forwards. Whoever she carries for sees, in one describe,
+// what she can be asked and what every being she holds can be asked, each
+// under that standing's name; asking one is an ask on that standing, in her
+// name, so the far being sees her and never who is behind her. A user being
+// carries acme for the human's devices; a house being could carry its
+// rooms; nothing here knows what she is.
+//
+// A carried ask is `<id>-<name>`, and the mapping back is kept in her cells
+// and never parsed from the name, so an id with a dash in it is no trouble.
+// The notes say which asks are whose, `standings: { id: { asks, look? } }`,
+// so a screen draws one section per standing and a model side keeps the
+// flat list it needs. Her own asks come first and are never shadowed: a
+// carried name that collides with one of hers is dropped.
+//
+// She asks a standing's describe again when its digest moved, and its
+// `look` once per digest, and keeps both in her cells. So a describe of
+// hers may cost one ask per stale standing, which is the price of a page
+// that is never more than one ask behind.
+import { Being, isSilence, isWord, wordOf } from '@nervur-org/nervur';
+import { sanitise } from './look.js';
+// The names a far being carries, read off her notes: every ask her
+// `standings` groups name, and each group's page. Empty when she carries
+// nothing, which a bare avatar does not.
+function carriedBy(bp) {
+    const out = new Set();
+    const notes = bp.notes;
+    const groups = notes !== null && typeof notes === 'object' && !Array.isArray(notes) ? notes.standings : undefined;
+    if (!groups || typeof groups !== 'object' || Array.isArray(groups))
+        return out;
+    for (const g of Object.values(groups)) {
+        if (Array.isArray(g?.asks))
+            for (const n of g.asks)
+                if (typeof n === 'string')
+                    out.add(n);
+        if (typeof g?.page === 'string')
+            out.add(g.page);
+    }
+    return out;
+}
+export class Carrier extends Being {
+    // Who sees what she carries. Nobody, until a subclass says who.
+    static carries(_occupant, _asker) {
+        return false;
+    }
+    // Standings that are plumbing: their own asks are never carried, and
+    // what they carry is. A way back to a device is one, by the dock's own
+    // convention, so a bare avatar's inbox never shows on her and a presence
+    // being's faculties do, under `to:<id>-<name>`, which is how home carries
+    // her phone. A subclass may name more.
+    static hidden(id) {
+        return id.startsWith('to:');
+    }
+    // Standings she never reads for carrying at all: a presence being's
+    // standing at her own user being is one, since carrying it would carry
+    // the user being's carrying of her, and round. None, until a subclass
+    // says which.
+    static skips(_id) {
+        return false;
+    }
+    // Which of the standings she carries this asker may see. Every one,
+    // until a subclass keeps some for fewer: a user being shows her own door
+    // to a device that may mint and to nobody else.
+    static shows(_id, _occupant, _asker) {
+        return true;
+    }
+    get carried() {
+        return (this.cells.carried ??= {});
+    }
+    get looks() {
+        return (this.cells.looks ??= {});
+    }
+    // Her describe with her standings carried into it, for an asker who may
+    // see them. Every other asker gets her describe alone.
+    async blueprint(asker) {
+        const C = this.constructor;
+        const bp = this.describe(asker);
+        if (!C.carries(this.occupant(asker), asker))
+            return bp;
+        const own = new Set(bp.asks.map((a) => a.name));
+        const carried = {};
+        const groups = {};
+        const occ = this.occupant(asker);
+        // By id, and never in the order she happened to take them. Her cells keep
+        // standings in the order they were taken, which is the order a lend
+        // answered, a device came back or a relation was dropped and taken again:
+        // history, and no fact about her. Carried into her blueprint in that
+        // order, her shape would come out differently on two runs that made her
+        // the same way, and her digest with it. The digest is how everyone
+        // holding a standing on her learns she changed, so a shape that follows
+        // history says she changed when nothing about her did, and a watcher
+        // refreshes or walks away over the order two lends came back in.
+        for (const [id, rec] of [...Object.entries(this.cells.standings)].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+            if (C.skips(id))
+                continue;
+            const st = this.standings[id];
+            if (!st)
+                continue;
+            if (!rec.blueprint || rec.seen !== rec.digest)
+                await st.ask(); // her ward writes the record
+            if (!rec.blueprint)
+                continue;
+            // plumbing carries what it carries and nothing of its own: the names
+            // the far being's notes group under her standings, or none
+            const through = C.hidden(id) ? carriedBy(rec.blueprint) : null;
+            if (through && through.size === 0)
+                continue;
+            // The mapping is written for every standing she carries, whoever is
+            // asking: it is one map in her cells, and the last describe must not
+            // decide what the next asker may call. Who sees a standing is decided
+            // here and again at answer, by `shows`.
+            const shown = C.shows(id, occ, asker);
+            // her look is kept here once per digest and never carried as an ask;
+            // her page follows every call, so it is carried as one and named in
+            // the notes, where every side finds it and none takes it for a form
+            const names = [];
+            const group = { asks: names };
+            for (const a of rec.blueprint.asks) {
+                if (a.name === 'look')
+                    continue;
+                if (through && !through.has(a.name))
+                    continue;
+                const name = `${id}-${a.name}`;
+                if (own.has(name))
+                    continue;
+                carried[name] = { id, ask: a.name };
+                if (!shown)
+                    continue;
+                bp.asks.push({ ...a, name });
+                if (a.name === 'page')
+                    group.page = name;
+                else
+                    names.push(name);
+            }
+            if (!shown)
+                continue;
+            if (rec.blueprint.asks.some((a) => a.name === 'look')) {
+                const kept = this.looks[id];
+                if (!kept || kept.digest !== rec.digest) {
+                    const l = await st.ask('look');
+                    this.looks[id] = { digest: rec.digest, look: isSilence(l) || isWord(l) ? {} : sanitise(l) };
+                }
+                group.look = this.looks[id].look;
+            }
+            groups[id] = group;
+        }
+        for (const id of Object.keys(this.looks))
+            if (!(id in groups))
+                delete this.looks[id];
+        this.cells.carried = carried;
+        const notes = bp.notes !== null && typeof bp.notes === 'object' && !Array.isArray(bp.notes) ? bp.notes : {};
+        return { asks: bp.asks, notes: { ...notes, standings: groups } };
+    }
+    async answer(asker, method, args = {}) {
+        if (method === undefined)
+            return this.blueprint(asker);
+        const C = this.constructor;
+        const to = Object.hasOwn(this.carried, method) ? this.carried[method] : undefined;
+        const occ = this.occupant(asker);
+        if (to && C.carries(occ, asker) && C.shows(to.id, occ, asker)) {
+            const st = this.standings[to.id];
+            if (!st)
+                return { error: 'unknown ask' };
+            const out = await st.ask(to.ask, args);
+            if (isSilence(out))
+                return out;
+            if (isWord(out))
+                return { error: wordOf(out) };
+            return out;
+        }
+        return super.answer(asker, method, args);
+    }
+}

package/dist/beings/clock.d.ts

@@ -0,0 +1,161 @@
+import { Being } from '@nervur-org/nervur';
+import type { Asker, Json, JsonObject, OccupantRecord, Stance } from '@nervur-org/nervur';
+declare const root: (_occ: OccupantRecord | undefined, asker: Asker) => boolean;
+declare const timer: (_occ: OccupantRecord | undefined, asker: Asker) => boolean;
+declare const watching: (occ: OccupantRecord | undefined, asker: Asker) => boolean;
+export type Schedule = {
+    id: string;
+    ask: string;
+    args?: JsonObject;
+    note?: Json;
+    cron?: string;
+    at?: string;
+    tz?: string;
+    time?: number;
+    catchUp?: boolean;
+};
+export type Fire = {
+    at: number;
+    word: string;
+    tries: number;
+};
+export type Cron = {
+    minutes: number[];
+    hours: number[];
+    days: number[];
+    months: number[];
+    weekdays: number[];
+    anyDay: boolean;
+    anyWeekday: boolean;
+};
+export declare function parseCron(spec: string): Cron;
+export type Civil = {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+};
+export declare function civil(ms: number, tz: string): Civil;
+export declare function fromCivil(tz: string, year: number, month: number, day: number, hour: number, minute: number): number;
+export declare function nextFire(c: Cron, tz: string, after: number): number | null;
+export declare function readSchedule(v: unknown): Schedule | string;
+export declare class Clock extends Being {
+    #private;
+    static cells: {
+        kept: Record<string, Schedule>;
+        fires: Record<string, Fire>;
+    };
+    readonly joined: Promise<string | null>;
+    constructor(stance: Stance);
+    static asks: {
+        tick: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    now: {
+                        type: string;
+                        format: string;
+                        description: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof timer;
+        };
+        list: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    now: {
+                        type: string;
+                        format: string;
+                        description: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof watching;
+        };
+        next: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    now: {
+                        type: string;
+                        format: string;
+                        description: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof watching;
+        };
+        keep: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    id: {
+                        type: string;
+                    };
+                    ask: {
+                        type: string;
+                        description: string;
+                    };
+                    args: {
+                        type: string;
+                    };
+                    note: {};
+                    cron: {
+                        type: string;
+                    };
+                    at: {
+                        type: string;
+                    };
+                    tz: {
+                        type: string;
+                    };
+                    time: {
+                        type: string;
+                    };
+                    catchUp: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof root;
+        };
+        drop: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    id: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof root;
+        };
+    };
+    keep(args: JsonObject, _asker?: Asker): Promise<JsonObject>;
+    drop(args: JsonObject, _asker?: Asker): Promise<JsonObject>;
+    protected told(): Promise<void>;
+    schedules(): Schedule[];
+    tick(args: JsonObject): Promise<JsonObject>;
+    list(args: JsonObject): JsonObject;
+    next(args: JsonObject): JsonObject;
+}
+type Owner = {
+    ask(method: string, args: JsonObject): Promise<unknown>;
+};
+export declare const CLOCK = "clock";
+export declare function setupClock(hosted: Owner, wakes?: string[]): Promise<void>;
+export declare function placeClock(hosted: Owner, being: string): Promise<void>;
+export {};