nervur 0.18.0 → 0.19.1

package/README.md

@@ -1,7 +1,7 @@
 # Nervur
 
 Nervur is the first open source kit of Quo, the library itself: harbor, ward
-and being, with the spec and the vectors inside, and no dependencies.
+and being, with no dependencies.
 
 Quo is a protocol that lets an object ask another object and get an answer,
 without knowing whether that other object is in the same process, on the same
@@ -38,8 +38,9 @@ source it was emitted from, because Node strips types nowhere under
 ```
 src/being/        the Being side: what a being author imports, if anything
 src/ward/         the ward: the Ground contract, door, seal, arithmetic, heirs, stance, allowance
-src/harbor/       MemoryHarbor, and the harbor core with its store, reach and dialer
+src/harbor/       MemoryHarbor, the box's being, and the harbor core with its store, reach and dialer
 src/conformance/  behaviours any ward must show, written against the truth
+src/vector/       vector mode, and the world the door's cases are taken in
 ```
 
 The suites live beside the source in the tree this is developed in and are
@@ -107,11 +108,10 @@ is no migration to write because there is nothing yet to migrate from. This
 package carries the version of its own work and is bound to no other's, so a
 number equal to `@nervur-org/dock`'s or `@nervur-org/ui`'s is a coincidence.
 
-What ships is the emitted `dist/`, the source it came from, the protocol
-shelf with the spec and the vectors inside it, this file, the licence and
-the notice. No tests and no configs. The spec ships because it is the truth
-the source and the vectors are read against, and a package a stranger reads
-with no truth beside it is a pile of names.
+What ships is the emitted `dist/`, the source it came from, this file, the
+licence and the notice. No tests and no configs. The spec and the vectors
+are not in the tarball: they are Quo's and not this package's to carry, and
+they stand at <https://quo.systems>, which is where this file points.
 
 ## License
 

package/dist/being/index.d.ts

@@ -1,4 +1,5 @@
 export { Being, type AskSpec } from './being.ts';
+export { Lent, BOX, LENT_ASKS } from './lent.ts';
 export { silence, isSilence, answered, unreached, isUnreached, word, isWord, wordOf, told, DOOR_WORDS, isDoorWord } from './silence.ts';
 export { digest, canonical } from './digest.ts';
 export { OWNER, PUBLIC, RESERVED_IDS, isBlueprint, invitationArgs, isInvitation } from './types.ts';

package/dist/being/index.js

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // nervur — the Being side. What a being author imports, if anything.
 export { Being } from './being.js';
+export { Lent, BOX, LENT_ASKS } from './lent.js';
 export { silence, isSilence, answered, unreached, isUnreached, word, isWord, wordOf, told, DOOR_WORDS, isDoorWord } from './silence.js';
 export { digest, canonical } from './digest.js';
 export { OWNER, PUBLIC, RESERVED_IDS, isBlueprint, invitationArgs, isInvitation } from './types.js';

package/dist/being/lent.d.ts

@@ -0,0 +1,32 @@
+import { Being } from './being.ts';
+import type { Asker, Blueprint, JsonObject, Reply } from './types.ts';
+export declare const BOX = "box";
+export declare const LENT_ASKS: {
+    offer: {
+        name: string;
+        description: string;
+        input: {
+            type: string;
+        };
+    };
+    retract: {
+        name: string;
+        description: string;
+        input: {
+            type: string;
+            properties: {
+                heir: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+    };
+};
+export declare class Lent extends Being {
+    #private;
+    offer(): Promise<JsonObject>;
+    retract(args: JsonObject): JsonObject;
+    describe(asker: Asker): Blueprint;
+    answer(asker: Asker, method?: string, args?: JsonObject): Promise<Reply>;
+}

package/dist/being/lent.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+// A lent being: a being of the box's own ward, standing for one thing the
+// device can do. What makes her one is two asks the box's being alone may
+// make, whom she knows as the occupant `box`. `offer`: she mints an
+// invitation on herself and answers it, so that a ward the box vouches for
+// may knock and take a standing at her. `retract`: an offer that was not
+// taken, named by its heir, is removed, so a refused lend leaves nothing.
+//
+// The two are the base's and never a subclass's to declare: a class says
+// her own asks and nothing of the seam she is lent through, so they are
+// answered here before her asks are read, and shown to the box alone. No
+// root mints for her, and nothing else about her is decided here.
+//
+// A convenience, not a contract: a being that answers the two the same way
+// to `box` is lendable, whatever she extends.
+import { Being } from './being.js';
+// The one word for the box's being: her key in the box's ward, the id every
+// lent being knows her by, and the standing every hosted ward takes at
+// birth.
+export const BOX = 'box';
+export const LENT_ASKS = {
+    offer: { name: 'offer', description: 'an invitation on me, for a ward the box vouches for', input: { type: 'object' } },
+    retract: { name: 'retract', description: 'an offer that was not taken, by its heir', input: { type: 'object', properties: { heir: { type: 'string' } }, required: ['heir'] } },
+};
+export class Lent extends Being {
+    // The offers she has open, heir to the id she minted under.
+    #open() {
+        return (this.cells.open ??= {});
+    }
+    async offer() {
+        const n = (this.cells.lent ?? 0) + 1;
+        this.cells.lent = n;
+        const id = `lent:${n}`;
+        const inv = await this.invite(id);
+        if (inv === null)
+            return { error: 'could not mint' };
+        this.#open()[inv.heir] = id;
+        return inv;
+    }
+    retract(args) {
+        const open = this.#open();
+        const heir = typeof args.heir === 'string' ? args.heir : '';
+        const id = Object.hasOwn(open, heir) ? open[heir] : undefined;
+        if (id === undefined)
+            return { retracted: null };
+        this.occupants.remove(id);
+        delete open[heir];
+        return { retracted: id };
+    }
+    describe(asker) {
+        const bp = super.describe(asker);
+        if (asker.id !== BOX)
+            return bp;
+        return { ...bp, asks: [...bp.asks, LENT_ASKS.offer, LENT_ASKS.retract] };
+    }
+    async answer(asker, method, args = {}) {
+        if (asker.id === BOX && method === 'offer')
+            return this.offer();
+        if (asker.id === BOX && method === 'retract')
+            return this.retract(args);
+        return super.answer(asker, method, args);
+    }
+}

package/dist/being/types.js

@@ -25,7 +25,7 @@ export const invitationArgs = (inv) => ({
 });
 // Whether a value that arrived is an invitation. The shape is the spec's, so
 // the reading of it is too, and it is one reading: a form that
-// asks a guest for one, a faculty handed one to wake her maker by, and a
+// asks a guest for one, a lent being handed one to wake her maker by, and a
 // shell that finds one in a link all ask the same question, and a kinder
 // answer in one of them is a value that fails at a door instead of at the
 // edge it came in by. A ward pk is a hundred and twenty-eight lowercase hex,

package/dist/conformance/beings.d.ts

@@ -1,4 +1,5 @@
 import { Being } from '../being/being.ts';
+import { Lent } from '../being/lent.ts';
 import type { Asker, Blueprint, Invitation, Json, JsonObject, OccupantRecord, Reply, Stance } from '../being/types.ts';
 export declare class Printer extends Being {
     static cells: {
@@ -157,7 +158,7 @@ export declare class Maker extends Being {
         lent: string | null;
     }>;
 }
-export declare class Member extends Being {
+export declare class Member extends Lent {
     static cells: {
         heard: JsonObject[];
     };

package/dist/conformance/beings.js

@@ -3,6 +3,7 @@
 // shop, a customer on the base class, a maker, a member, and one raw being
 // with no base at all.
 import { Being } from '../being/being.js';
+import { Lent } from '../being/lent.js';
 import { answered, isSilence, isUnreached, isWord, wordOf } from '../being/silence.js';
 import { invitationArgs } from '../being/types.js';
 // A printer. Invites whom she is told to, prints for her occupants. Her
@@ -153,9 +154,13 @@ export class Maker extends Being {
         return { lent: await this.lend(name, id) };
     }
 }
-export class Member extends Being {
-    static cells = { heard: [] };
+// A member is also lendable: lent by a box that stands her in its own ward,
+// she offers an invitation on herself when the box's being asks, and is an
+// ordinary being to everyone else.
+export class Member extends Lent {
+    static cells = { ...Lent.cells, heard: [] };
     static asks = {
+        ...Lent.asks,
         ping: { input: { type: 'object' } },
         relay: { input: { type: 'object', properties: { id: { type: 'string' }, method: { type: 'string' }, time: { type: 'number' } }, required: ['id'] } },
     };

package/dist/conformance/index.d.ts

@@ -63,7 +63,6 @@ export type Refusing = {
 };
 export { Printer, Shop, Customer, Echo, Maker, Member };
 export declare const HEX64: RegExp;
-export declare const HEX128: RegExp;
 export type Runner = (name: string, opts: {
     skip?: string | false;
 }, fn: () => Promise<void> | void) => void;

package/dist/conformance/index.js

@@ -33,7 +33,7 @@ export { Printer, Shop, Customer, Echo, Maker, Member };
 // expects instead of importing ours, and nothing under `src/conformance`
 // reaches into `src/ward` for anything.
 export const HEX64 = /^[0-9a-f]{64}$/; // one key, one secret, one digest
-export const HEX128 = /^[0-9a-f]{128}$/; // a ward pk: the signing pk then the padlock
+const HEX128 = /^[0-9a-f]{128}$/; // a ward pk: the signing pk then the padlock
 // Her ward's word, as she receives it.
 const said = (x, w) => told(x) === w;
 // A world whose harness stands a ward up again. The two members are optional
@@ -412,10 +412,12 @@ export function conform(label, make, { canDown = true, canLend = true, canRestar
         assert.equal(after.said, null, 'and she asks again on the same standing');
     });
     // Lend is boot's other half: what the device already has, reached the one
-    // way anything is reached. The being lent stands in a ward the harbor
-    // roots, so nothing here can look at her from the outside; what the ward
-    // owes is what is asserted. She is handed an id, the standing is an
-    // ordinary one, and the invitation is nowhere she can read.
+    // way anything is reached. The device is one standing the ward holds at
+    // the box's being, and a lend is an ask on it; the being lent stands in
+    // a ward the harbor roots, so nothing here can look at her from the
+    // outside, and what the ward owes is what is asserted. She is handed an
+    // id, the standing is an ordinary one, and the invitation is nowhere she
+    // can read.
     lends('what the device lends is a being: she is handed an id, asks on an ordinary standing, and never sees the invitation', async () => {
         const w = await make({ lends: { pen: 'Member' } });
         const maker = await w.boot('MK', Maker);
@@ -574,6 +576,7 @@ export function conform(label, make, { canDown = true, canLend = true, canRestar
         const names = (x) => bp(x).asks.map((a) => a.name);
         assert.deepEqual(names(await alice.being.learn()), ['hello', 'buy', 'refund']);
         assert.deepEqual(names(await bob.being.learn()), ['hello', 'buy']);
+        assert.deepEqual(await alice.being.standings.shop.ask('refund'), { ok: true }, 'and what she is shown she can ask');
     });
     t('the digest is per relation: two occupants, two digests of one being, both true', async () => {
         const { shop, alice, bob } = await world();

package/dist/harbor/box.d.ts

@@ -0,0 +1,121 @@
+import { Being } from '../being/index.ts';
+import type { Asker, BeingClass, Invitation, JsonObject, OccupantRecord } from '../being/index.ts';
+import { type WardPointers } from '../ward/ground.ts';
+export type Root = Pick<WardPointers, 'ask'>;
+export { BOX } from '../being/lent.ts';
+export declare const BOX_SEED = "box";
+declare const ward: (occ: OccupantRecord | undefined) => boolean;
+declare const root: (_occ: OccupantRecord | undefined, asker: Asker) => boolean;
+export declare const BOX_ASKS: {
+    offer: {
+        description: string;
+        input: {
+            type: string;
+            properties: {
+                name: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+        for: typeof ward;
+    };
+    retract: {
+        description: string;
+        input: {
+            type: string;
+            properties: {
+                name: {
+                    type: string;
+                };
+                heir: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+        for: typeof ward;
+    };
+    host: {
+        description: string;
+        input: {
+            type: string;
+            properties: {
+                seed: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+        for: typeof root;
+    };
+    roll: {
+        description: string;
+        input: {
+            type: string;
+        };
+        for: typeof root;
+    };
+};
+export declare class Box extends Being {
+    static cells: JsonObject;
+    static asks: {
+        offer: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    name: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof ward;
+        };
+        retract: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    name: {
+                        type: string;
+                    };
+                    heir: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof ward;
+        };
+        host: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    seed: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof root;
+        };
+        roll: {
+            description: string;
+            input: {
+                type: string;
+            };
+            for: typeof root;
+        };
+    };
+    offer(args: JsonObject): Promise<JsonObject>;
+    retract(args: JsonObject): Promise<JsonObject>;
+    host(args: JsonObject): Promise<JsonObject>;
+    roll(): JsonObject;
+}
+export declare function stand(box: Root, lent: Record<string, BeingClass>, own?: string): Promise<void>;
+export declare function hold(box: Root, key: string): Promise<boolean>;
+export declare function offerTo(box: Root, seed: string): Promise<Invitation | undefined>;
+export declare function roll(box: Root): Promise<string[]>;

package/dist/harbor/box.js

@@ -0,0 +1,121 @@
+// SPDX-License-Identifier: Apache-2.0
+// The box as one being. A harbor boots a ward of its own and one being in
+// it, the box's own, who holds a standing at every lent being the box
+// offers, under the name each is lent as, and keeps the roll of the wards
+// the box hosts. Every hosted ward is handed one invitation on her at boot
+// and takes it as its own standing; from then on the device is one
+// standing, what it offers is her describe, and a lend is the ask `offer`
+// on her.
+//
+// The harbor works in acts and holds no memory of its own. Act one boots the
+// box's ward on the plain ground, no box, because it is the box; her lent
+// beings come up, and the root places her standings and nothing else. Act
+// two asks her who is hosted and boots each with one invitation. Everything
+// the device is lives in her ward as a lent being's cells, placed through
+// asks and read from no file.
+//
+// A runtime that needs her to be more, a resolver of names or a carrier of
+// her lent beings' asks for a screen, extends her and overrides the asks.
+import { Being, isInvitation, OWNER } from '../being/index.js';
+import { BOX } from '../being/lent.js';
+import { OFFER, RETRACT } from '../ward/ground.js';
+export { BOX } from '../being/lent.js';
+// The name of the box's own ward, one per harbor: the seed a memory harbor
+// boots it under, and the name a store keeps it by.
+export const BOX_SEED = 'box';
+// A ward the box vouches for: invited by the root at act two, with the one
+// note that says so. A screen or a model the root lets in has no such note
+// and is shown nothing of the lend seam.
+const ward = (occ) => occ?.notes.ward === true;
+const root = (_occ, asker) => asker.id === OWNER;
+export const BOX_ASKS = {
+    [OFFER]: { description: 'an invitation on the being lent under this name', input: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }, for: ward },
+    [RETRACT]: { description: 'an offer under this name that was not taken, by its heir', input: { type: 'object', properties: { name: { type: 'string' }, heir: { type: 'string' } }, required: ['name', 'heir'] }, for: ward },
+    host: { description: 'a ward this box hosts from now', input: { type: 'object', properties: { seed: { type: 'string' } }, required: ['seed'] }, for: root },
+    roll: { description: 'the wards this box hosts', input: { type: 'object' }, for: root },
+};
+export class Box extends Being {
+    static cells = { hosted: [], offers: {} };
+    static asks = BOX_ASKS;
+    // Offer: the being under the name, asked to offer, answers her own
+    // invitation. A subclass that lends under more names than it holds
+    // standings, a contract's digest for one, resolves the name first and
+    // calls this with the standing's own.
+    async offer(args) {
+        const at = this.standings[args.name];
+        if (!at)
+            return { error: 'lends none' };
+        const out = await at.ask(OFFER);
+        return isInvitation(out) ? out : { error: 'not offered' };
+    }
+    async retract(args) {
+        const at = this.standings[args.name];
+        if (!at)
+            return { error: 'lends none' };
+        const out = await at.ask(RETRACT, { heir: args.heir });
+        return out !== null && typeof out === 'object' && !Array.isArray(out) ? out : { retracted: null };
+    }
+    // A ward on the roll, and its one invitation on her. She mints it the first
+    // time and keeps it, and hands the same one at every later boot until it
+    // is spent: a ward that could not take the box at birth, the box down or
+    // the knock lost, takes it at the next, as the spec promises. A ward that
+    // holds the standing already ignores it, and a spent heir opens no door,
+    // so handing it again costs nothing. The value never leaves her ward: it
+    // is read by the root alone and rides in the ground and nowhere else.
+    async host(args) {
+        const hosted = (this.cells.hosted ??= []);
+        const offers = (this.cells.offers ??= {});
+        if (typeof args.seed !== 'string')
+            return { error: 'a seed is a word' };
+        if (!hosted.includes(args.seed))
+            hosted.push(args.seed);
+        if (!Object.hasOwn(offers, args.seed)) {
+            const inv = await this.invite(args.seed, { ward: true });
+            if (inv !== null)
+                offers[args.seed] = inv;
+        }
+        return { hosted: [...hosted], invitation: offers[args.seed] ?? null };
+    }
+    roll() {
+        return { hosted: [...(this.cells.hosted ?? [])] };
+    }
+}
+// Act one's second half, on a box ward already booted: the box's being and
+// each lent being booted by key, and her standing placed at each under its
+// key by the root. A ward woken from its memory already holds all of it,
+// and a key already booted is refused and costs nothing, so this is run at
+// every boot and does the right thing at each.
+export async function stand(box, lent, own = 'Box') {
+    const up = async (key, cls) => {
+        const out = (await box.ask('boot', { key, class: cls }));
+        return out.booted === key;
+    };
+    await up(BOX, own);
+    for (const name of Object.keys(lent)) {
+        const fresh = await up(name, lent[name].name);
+        if (!fresh)
+            continue;
+        await hold(box, name);
+    }
+}
+// The box's standing at one lent being of her ward, under that being's key,
+// placed by the root: the lent being invites the box's being as `box`, and
+// she knocks. Refused where either already holds the relation.
+export async function hold(box, key) {
+    const inv = await box.ask('invite', { being: key, id: BOX });
+    if (!isInvitation(inv))
+        return false;
+    const out = (await box.ask('knock', { being: BOX, id: key, invitation: inv }));
+    return out?.taken === key;
+}
+// One invitation on the box's being for the ward named, and the ward on the
+// roll: the same one at every boot, minted once by her and kept by her.
+export async function offerTo(box, seed) {
+    const out = (await box.ask('ask', { being: BOX, method: 'host', args: { seed } }));
+    return isInvitation(out?.invitation) ? out.invitation : undefined;
+}
+// Who the box hosts, asked of the box's being.
+export async function roll(box) {
+    const out = (await box.ask('ask', { being: BOX, method: 'roll' }));
+    return out.hosted ?? [];
+}

package/dist/harbor/core.d.ts

@@ -1,5 +1,5 @@
-import { type WardPointers, type Lend } from '../ward/ground.ts';
-import type { BeingClass, BeingLike } from '../being/types.ts';
+import { type WardPointers } from '../ward/ground.ts';
+import type { BeingClass, BeingLike, Invitation } from '../being/types.ts';
 import { type Reach } from './reach.ts';
 import type { Kept, Store, WardRecord } from './store.ts';
 export type Hosted = WardPointers & {
@@ -34,9 +34,9 @@ export declare class Harbor {
     readonly classes: Record<string, BeingClass>;
     readonly fallbacks: Reach[];
     readonly announcers: Set<() => void>;
-    lend: Lend | undefined;
-    constructor(store: Store, loader?: Loader, lend?: Lend);
-    protected lendFor(_name: string, _record: WardRecord): Lend | undefined;
+    offering: ((name: string) => Promise<Invitation | undefined>) | undefined;
+    constructor(store: Store, loader?: Loader);
+    protected boxFor(name: string, _record: WardRecord): Promise<Invitation | undefined>;
     boot(): Promise<void>;
     partitionOf(name: string): Record<string, unknown> | undefined;
     carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | undefined>;