nervur 0.16.0 → 0.17.0

package/dist/being/types.js

@@ -0,0 +1,58 @@
+// The ids the ward speaks under, and no being may mint. An asker id is hers:
+// she chooses the strings, and the ward has no business in her namespace. But
+// the ward must sometimes stand at her door itself — its describe asks every
+// being under OWNER — and an id it shares with one of her occupants is two
+// different parties wearing one name. She could not tell them apart, and the
+// ward would shape its describe through an occupant's gate.
+//
+// So the ward's words are shouted, and refused at the mint. A word can only
+// be reserved before anyone has used it: a partition already holding an
+// occupant of that name could never have it taken back. PUBLIC guards nothing
+// today — a public asker is {} and carries no id at all — and that is exactly
+// why it is claimed now, while claiming it is free.
+export const OWNER = 'OWNER';
+export const PUBLIC = 'PUBLIC';
+export const RESERVED_IDS = [OWNER, PUBLIC];
+// An invitation as one object of values, which is what it already is. A being
+// who hands one on sends it as args, and args are values; this is the one
+// place that is spelled, so nobody spells it with a cast. Absent stays absent:
+// an invitation to a public being carries no heir and no secret, and a key
+// present and undefined is not the same object once JSON has been through it.
+export const invitationArgs = (inv) => ({
+    ward: inv.ward,
+    ...(inv.heir !== undefined ? { heir: inv.heir } : {}),
+    ...(inv.secret !== undefined ? { secret: inv.secret } : {}),
+});
+// 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
+// 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,
+// and a heir comes with its secret or neither comes: an invitation to a
+// public being carries no heir, and a heir with no secret opens nothing.
+export const isInvitation = (v) => {
+    if (v === null || typeof v !== 'object' || Array.isArray(v))
+        return false;
+    const o = v;
+    if (typeof o.ward !== 'string' || !/^[0-9a-f]{128}$/.test(o.ward))
+        return false;
+    const heir = typeof o.heir === 'string', secret = typeof o.secret === 'string';
+    return (heir && secret) || (!heir && !secret && !('heir' in o) && !('secret' in o));
+};
+// Whether what came back from an empty ask is a blueprint. Every describe on
+// the far side of a door is somebody else's code, so nothing may be written
+// into a standing's record as a blueprint without being read as one first: a
+// side walks `asks` by name, and a list of anything else, or no list at all,
+// is a side that breaks on a far ward's answer. The asks are checked to the
+// depth a side reads them, a name and an input each, and no further: what a
+// far being puts beside those is hers.
+export const isBlueprint = (v) => {
+    if (v === null || typeof v !== 'object' || Array.isArray(v))
+        return false;
+    const { asks, notes } = v;
+    if (!Array.isArray(asks) || notes === undefined)
+        return false;
+    return asks.every((a) => a !== null && typeof a === 'object' && !Array.isArray(a) && typeof a.name === 'string' && a.input !== null && typeof a.input === 'object' && !Array.isArray(a.input));
+};
+export const WORD_KEY = Symbol.for('quo.word');

package/dist/conformance/assert.d.ts

@@ -0,0 +1,11 @@
+export declare class Failed extends Error {
+}
+export declare function same(a: unknown, b: unknown): boolean;
+export type Assert = {
+    ok(value: unknown, message?: string): asserts value;
+    equal(actual: unknown, expected: unknown, message?: string): void;
+    notEqual(actual: unknown, expected: unknown, message?: string): void;
+    deepEqual(actual: unknown, expected: unknown, message?: string): void;
+    match(actual: string, re: RegExp, message?: string): void;
+};
+export declare const assert: Assert;

package/dist/conformance/assert.js

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: Apache-2.0
+// The five assertions the conformance suite makes, and no more. Node has all
+// five in `node:assert/strict`, and naming that module would tie the suite to
+// one terrain -- the suite is the ward's truth, and the ward's truth has to be
+// checkable wherever a ward runs. So they are written here, in the language
+// alone, and `test/assert.test.ts` holds them to Node's own behaviour.
+export class Failed extends Error {
+}
+const show = (v) => {
+    if (typeof v === 'symbol')
+        return v.toString();
+    if (typeof v === 'bigint')
+        return `${v}n`;
+    if (v === undefined)
+        return 'undefined';
+    if (typeof v === 'function')
+        return `[function ${v.name}]`;
+    // A ward's word is a frozen object under one symbol key, and JSON shows it
+    // as `{}`. A red estate chapter saying `{} is not {}` names nothing, so a
+    // value whose own keys are all symbols is shown by its keys.
+    if (v !== null && typeof v === 'object') {
+        const keys = Object.keys(v);
+        const syms = Object.getOwnPropertySymbols(v).filter((s) => Object.getOwnPropertyDescriptor(v, s).enumerable);
+        if (keys.length === 0 && syms.length > 0)
+            return `{ ${syms.map((s) => `${s.toString()}: ${show(v[s])}`).join(', ')} }`;
+    }
+    try {
+        return JSON.stringify(v) ?? Object.prototype.toString.call(v);
+    }
+    catch {
+        return Object.prototype.toString.call(v); // a cycle, or a null prototype
+    }
+};
+const fail = (why, message) => {
+    throw new Failed(message ? `${message}: ${why}` : why);
+};
+// Structural, and strict about shape the way `node:assert/strict` is: a value
+// is not equal to one of another kind, and an array is not equal to an object
+// that happens to hold the same keys.
+// The four kinds this compares, and every other object is refused rather than
+// guessed at. A Date, a RegExp, a boxed primitive and a class instance each
+// carry state no key walk can see, so two of them with the same keys are
+// equal here and unequal in node, which is a wrong yes: the one answer a
+// suite must never give. A refusal is a red test that says so.
+const KNOWN = [Object.prototype, null, Array.prototype, Uint8Array.prototype];
+// What node compares: own enumerable keys, strings then enumerable symbols.
+// Not `Reflect.ownKeys`, which also lists what a definition hid.
+const keysOf = (v) => [...Object.keys(v), ...Object.getOwnPropertySymbols(v).filter((s) => Object.getOwnPropertyDescriptor(v, s).enumerable)];
+export function same(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    const proto = Object.getPrototypeOf(a);
+    if (proto !== Object.getPrototypeOf(b))
+        return false;
+    if (!KNOWN.includes(proto))
+        return false; // a Date, a RegExp, a boxed number, a class of hers
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (a instanceof Uint8Array && b instanceof Uint8Array)
+        return a.length === b.length && a.every((x, i) => x === b[i]);
+    // An array is its indices and whatever else was hung on it, and a hole is
+    // not a present undefined: `[, 1]` and `[undefined, 1]` differ in node and
+    // must differ here. `every` skips holes, so the loop is written out.
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i += 1) {
+            if (i in a !== i in b)
+                return false;
+            if (i in a && !same(a[i], b[i]))
+                return false;
+        }
+        const extra = (v) => keysOf(v).filter((k) => typeof k !== 'string' || !/^(?:0|[1-9]\d*)$/.test(k));
+        const xa = extra(a), xb = extra(b);
+        const at = (v, k) => v[k];
+        return xa.length === xb.length && xa.every((k) => xb.includes(k) && same(at(a, k), at(b, k)));
+    }
+    const ka = keysOf(a), kb = keysOf(b);
+    if (ka.length !== kb.length)
+        return false;
+    return ka.every((k) => kb.includes(k) && same(a[k], b[k]));
+}
+export const assert = {
+    ok(value, message) {
+        if (!value)
+            fail(`${show(value)} is not truthy`, message);
+    },
+    equal(actual, expected, message) {
+        if (!Object.is(actual, expected))
+            fail(`${show(actual)} !== ${show(expected)}`, message);
+    },
+    notEqual(actual, expected, message) {
+        if (Object.is(actual, expected))
+            fail(`${show(actual)} === ${show(expected)}`, message);
+    },
+    deepEqual(actual, expected, message) {
+        if (!same(actual, expected))
+            fail(`${show(actual)} is not ${show(expected)}`, message);
+    },
+    match(actual, re, message) {
+        if (typeof actual !== 'string' || !re.test(actual))
+            fail(`${show(actual)} does not match ${String(re)}`, message);
+    },
+};

package/dist/conformance/beings.d.ts

@@ -0,0 +1,198 @@
+import { Being } from '../being/being.ts';
+import type { Asker, Blueprint, Invitation, Json, JsonObject, OccupantRecord, Reply, Stance } from '../being/types.ts';
+export declare class Printer extends Being {
+    static cells: {
+        jobs: JsonObject[];
+        asks: JsonObject[];
+    };
+    static asks: {
+        print: {
+            input: {
+                type: string;
+            };
+        };
+    };
+    describe(): Blueprint;
+    print({ doc }: JsonObject, asker: Asker): {
+        printed: string | number | boolean | Json[] | {
+            [key: string]: Json;
+        } | null;
+    };
+}
+export declare class Shop extends Being {
+    static cells: {
+        printerId: string | null;
+        sales: JsonObject[];
+        minted: number;
+    };
+    static asks: {
+        hello: {
+            input: {
+                type: string;
+            };
+        };
+        buy: {
+            input: {
+                type: string;
+                properties: {
+                    item: {
+                        type: string;
+                    };
+                };
+            };
+        };
+        refund: {
+            input: {
+                type: string;
+            };
+            for: (rec: OccupantRecord | undefined) => boolean;
+        };
+    };
+    answer(asker: Asker, method?: string, args?: JsonObject): Promise<Reply>;
+    invite(tier?: string): Promise<Invitation>;
+    keepPrinter(invitation: Invitation): Promise<boolean>;
+    hello({ invitation }: JsonObject, asker: Asker): Promise<{
+        welcome: boolean;
+    }>;
+    buy({ item }: JsonObject, asker: Asker): Promise<{
+        error: string;
+        retry?: undefined;
+        ok?: undefined;
+        receipt?: undefined;
+    } | {
+        error: string;
+        retry: boolean;
+        ok?: undefined;
+        receipt?: undefined;
+    } | {
+        error?: undefined;
+        retry?: undefined;
+        ok: boolean;
+        receipt: Json;
+    }>;
+    refund(): {
+        ok: boolean;
+    };
+}
+export declare class Customer extends Being {
+    static cells: {
+        heard: JsonObject[];
+    };
+    static asks: {
+        hi: {
+            input: {
+                type: string;
+            };
+        };
+    };
+    join(invitation: Invitation): Promise<string | number | boolean | typeof import("../being/silence.ts").silence | Json[] | import("../being/types.ts").Word<import("../being/types.ts").WordName> | {
+        [key: string]: Json;
+    } | null>;
+    buy(item: string): Promise<import("../being/types.ts").Answer>;
+    learn(): Promise<import("../being/types.ts").Answer>;
+    hi(_args: JsonObject, asker: Asker): {
+        heard: string;
+    };
+}
+export declare class Echo {
+    s: Stance;
+    constructor(stance: Stance);
+    answer(asker: Asker, method?: string, args?: JsonObject): Reply;
+}
+export declare class Maker extends Being {
+    static cells: {
+        made: string[];
+    };
+    static asks: {
+        open: {
+            input: {
+                type: string;
+                properties: {
+                    class: {
+                        type: string;
+                    };
+                    key: {
+                        type: string;
+                    };
+                    id: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+        say: {
+            input: {
+                type: string;
+                properties: {
+                    id: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+        borrow: {
+            input: {
+                type: string;
+                properties: {
+                    name: {
+                        type: string;
+                    };
+                    id: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+    };
+    open({ class: className, key, id }: JsonObject): Promise<{
+        made: string | null;
+    }>;
+    say({ id }: JsonObject): Promise<{
+        said: Json;
+    }>;
+    borrow({ name, id }: JsonObject): Promise<{
+        lent: string | null;
+    }>;
+}
+export declare class Member extends Being {
+    static cells: {
+        heard: JsonObject[];
+    };
+    static asks: {
+        ping: {
+            input: {
+                type: string;
+            };
+        };
+        relay: {
+            input: {
+                type: string;
+                properties: {
+                    id: {
+                        type: string;
+                    };
+                    method: {
+                        type: string;
+                    };
+                    time: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+    };
+    ping(_args: JsonObject, asker: Asker): {
+        pong: string | null;
+    };
+    relay({ id, method, args, time }: JsonObject): Promise<{
+        said: string;
+        out: null;
+    } | {
+        said: null;
+        out: Json;
+    }>;
+}

package/dist/conformance/beings.js

@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: Apache-2.0
+// The fixture beings. Fixed, so that the ward is what varies. A printer, a
+// 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 { 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
+// blueprint lives in her cells so a test can change her shape.
+export class Printer extends Being {
+    static cells = { jobs: [], asks: [{ name: 'print', input: { type: 'object' } }] };
+    static asks = { print: { input: { type: 'object' } } };
+    describe() {
+        // Her own cells, which a test writes to change her shape. Cells are Json
+        // to the ward, so the asks are named for what she keeps in them.
+        return { asks: this.cells.asks, notes: { model: 'LX-2' } };
+    }
+    print({ doc }, asker) {
+        this.cells.jobs.push({ by: asker.id ?? null, doc: doc ?? null });
+        return { printed: doc ?? null };
+    }
+}
+// A shop. Invites customers in her own time. Keeps a printer as a standing.
+// Takes a gold customer back if the customer offers a way. Counts every ask
+// per occupant, by wrapping answer.
+export class Shop extends Being {
+    static cells = { printerId: null, sales: [], minted: 0 };
+    static asks = {
+        hello: { input: { type: 'object' } },
+        buy: { input: { type: 'object', properties: { item: { type: 'string' } } } },
+        refund: { input: { type: 'object' }, for: (rec) => rec?.notes.tier === 'gold' },
+    };
+    async answer(asker, method, args) {
+        const rec = this.occupant(asker);
+        if (rec && method !== undefined)
+            rec.notes.asks = (Number(rec.notes.asks) || 0) + 1;
+        return super.answer(asker, method, args);
+    }
+    // Outside any ask. She mints, her ward seals, she hands it out by mail.
+    async invite(tier = 'plain') {
+        const id = `cust${++this.cells.minted}`;
+        const inv = (await super.invite(id));
+        this.cells.occupants[id].notes.tier = tier;
+        return inv;
+    }
+    async keepPrinter(invitation) {
+        const bp = await this.knock(invitation);
+        if (!answered(bp))
+            return false;
+        this.cells.printerId = await this.take('prn', invitation);
+        return true;
+    }
+    async hello({ invitation }, asker) {
+        const rec = this.occupant(asker);
+        if (rec?.notes.tier === 'gold' && invitation) {
+            const back = await this.knock(invitation, 'hi');
+            if (answered(back))
+                await this.take(`vip-${asker.id}`, invitation);
+        }
+        return { welcome: true };
+    }
+    async buy({ item }, asker) {
+        if (typeof item !== 'string')
+            return { error: 'no such item' }; // args are hers to check
+        const id = this.cells.printerId;
+        const printer = id ? this.standings[id] : undefined;
+        if (!printer)
+            return { error: 'no printer' };
+        const out = await printer.ask('print', { doc: `receipt for ${item}` });
+        if (isUnreached(out))
+            return { error: 'printer unreachable', retry: true };
+        if (!answered(out))
+            return { error: 'printer refused' };
+        const st = this.cells.standings[id];
+        if (st.seen !== st.digest)
+            this.occupant(asker).notes.printerChanged = true;
+        this.cells.sales.push({ item: item ?? null, by: asker.id ?? null });
+        return { ok: true, receipt: out.printed };
+    }
+    refund() {
+        return { ok: true };
+    }
+}
+// A customer. Consumes an invitation, and only then decides to keep the
+// shop. Offers the shop a way back so the shop can reach her.
+export class Customer extends Being {
+    static cells = { heard: [] };
+    static asks = { hi: { input: { type: 'object' } } };
+    async join(invitation) {
+        // A way back for the shop, if she can mint one. She may not: two joins on
+        // one invitation race, and the second finds the id taken. Then she offers
+        // nothing and knocks all the same, which is what the shop is asked to
+        // survive. The old shape said `!` here and was wrong about it.
+        const mine = await this.invite('shop-back');
+        const out = await this.knock(invitation, 'hello', { invitation: mine === null ? null : invitationArgs(mine) });
+        if (!answered(out))
+            return out; // nothing was born
+        await this.take('shop', invitation); // now, and only now
+        return out;
+    }
+    buy(item) {
+        return this.standings.shop.ask('buy', { item });
+    }
+    learn() {
+        return this.standings.shop.ask();
+    }
+    hi(_args, asker) {
+        this.cells.heard.push({ from: asker.id ?? null, method: 'hi' });
+        return { heard: 'hi' };
+    }
+}
+// The raw shape. No base class, no import from the kit. A being all the same.
+export class Echo {
+    s;
+    constructor(stance) {
+        this.s = stance;
+    }
+    answer(asker, method, args = {}) {
+        if (method === undefined)
+            return { asks: [{ name: 'echo', input: {} }], notes: {} };
+        return { from: asker.id ?? null, ...args };
+    }
+}
+// A member of an estate. Nothing scripted: she invites whom she is told to,
+// knocks where she is told to, and answers `ping` with the asker's own name.
+// The estate chapter drives her, and what it drives is the graph, not her.
+// A being who makes beings. `boot` is on every stance, so it is the ward's
+// promise and not this kit's, and a second kit that never wired it hands its
+// beings a call that answers null for ever. She says what came of it: the key
+// back, or null for a key already taken, a class the harbor does not hold, or
+// a constructor that threw. With an id she also asks for a way back, and then
+// she holds a standing to what she made like any other.
+export class Maker extends Being {
+    static cells = { made: [] };
+    static asks = {
+        open: { input: { type: 'object', properties: { class: { type: 'string' }, key: { type: 'string' }, id: { type: 'string' } }, required: ['class', 'key'] } },
+        say: { input: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] } },
+        borrow: { input: { type: 'object', properties: { name: { type: 'string' }, id: { type: 'string' } }, required: ['name', 'id'] } },
+    };
+    async open({ class: className, key, id }) {
+        const made = await this.boot(className, key, id);
+        if (made !== null)
+            this.cells.made.push(made);
+        return { made };
+    }
+    async say({ id }) {
+        const standing = this.standings[id];
+        return { said: standing === undefined ? null : (await standing.ask('ping')) };
+    }
+    // Making's other half: a standing at something the box already has, by the
+    // name the box knows it under. She is handed the id and never the value.
+    async borrow({ name, id }) {
+        return { lent: await this.lend(name, id) };
+    }
+}
+export class Member extends Being {
+    static cells = { heard: [] };
+    static asks = {
+        ping: { input: { type: 'object' } },
+        relay: { input: { type: 'object', properties: { id: { type: 'string' }, method: { type: 'string' }, time: { type: 'number' } }, required: ['id'] } },
+    };
+    ping(_args, asker) {
+        this.cells.heard.push({ from: asker.id ?? null });
+        return { pong: asker.id ?? null };
+    }
+    // She asks on one of her standings from inside her own answer, and says
+    // what came back as a word rather than as the word itself, since a word is
+    // her ward's value and never a thing that crosses. `time` is what she is
+    // willing to wait, which is the whole of what the third argument is for.
+    // Two members holding each other and relaying make a cycle, and a cycle is
+    // how a suite that owns no clock can see a wait end.
+    async relay({ id, method, args, time }) {
+        const standing = this.standings[id];
+        if (standing === undefined)
+            return { said: 'no standing', out: null };
+        const out = await standing.ask(method, (args ?? {}), time === undefined ? undefined : { time: time });
+        if (isSilence(out))
+            return { said: 'silence', out: null };
+        if (isWord(out))
+            return { said: wordOf(out), out: null };
+        return { said: null, out: out };
+    }
+}

package/dist/conformance/estate.d.ts

@@ -0,0 +1,5 @@
+import type { Runner, World } from './index.ts';
+export declare function estate(label: string, make: () => Promise<World>, { canDown, test }: {
+    canDown: boolean;
+    test: Runner;
+}): void;