nervur 0.23.0 → 0.24.0

package/dist/bench/bench.js

@@ -1,368 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The bench: two houses on one BenchGround, reached as any owner reaches
-// hers. The author's house holds her classes and the fakes she hands it,
-// as faculties granted to it alone. The bench's own house holds a caller,
-// who asks her through a standing or as a stranger, so every ask crosses a
-// door as it would in production. Nothing here reaches inside a house: a
-// role is played by whoever an owner could have play it.
-import { tableOf } from '../being/index.js';
-import { BenchGround, Machine } from './bench-ground.js';
-import { FakeNetwork } from './fake-network.js';
-import { BenchCaller, BenchSteward } from './stewards.js';
-const STEWARD = 'steward';
-const PUBLIC = 'public';
-const AUTHOR = 'author';
-const TESTER = 'bench';
-const HOST = 'bench';
-/** The being of the author's house that plays a being introduced to her. */
-const NEIGHBOUR = 'bench-neighbour';
-/** Who an asker the house makes is to her roles. */
-const ROOT = Object.freeze({ id: 'root', notes: {}, steward: {} });
-const STRANGER = Object.freeze({ id: 'stranger', notes: {}, steward: {} });
-/** A being the bench placed, asked and described as any role the bench can play. */
-export class Placed {
-    id;
-    position;
-    #bench;
-    #table;
-    constructor(bench, id, position, table) {
-        this.#bench = bench;
-        this.id = id;
-        this.position = position;
-        this.#table = table;
-    }
-    /** The role an ask's entry names first; `root` where it names every occupant. */
-    roleFor(method) {
-        return this.#table.asks[method]?.for?.[0] ?? 'root';
-    }
-    /**
-     * One ask, as whoever plays `role`. An effect's answer is the reply it
-     * brings once it lands, and `null` is silence.
-     */
-    ask(method, args = {}, { role = this.roleFor(method) } = {}) {
-        return this.#bench.asked(this, this.#table, role, method, args);
-    }
-    /** Her describe as `role` sees it: her state and the asks it shows. */
-    describe({ role = 'root' } = {}) {
-        return this.#bench.described(this, this.#table, role);
-    }
-    /** Her cells as last landed, read through the hand, as her owner reads them. */
-    cells() {
-        return this.#bench.cellsOf(this);
-    }
-}
-export class Bench {
-    #network;
-    #ground;
-    /** The author's house's ward, which a stranger's card names. */
-    #ward;
-    /** The author's house is kept by the bench's own steward. */
-    #own;
-    #steward;
-    #public;
-    /** The caller's standing on each being, by the role it plays. */
-    #doors = new Map();
-    /** The beings the neighbour stands on. */
-    #introduced = new Set();
-    #count = 0;
-    constructor(network, ground, ward, placed) {
-        this.#network = network;
-        this.#ground = ground;
-        this.#ward = ward;
-        this.#own = placed.steward === undefined;
-        this.#steward = placed.steward;
-        this.#public = placed.public;
-    }
-    static async open({ classes, offers = [], seed = 'bench', steward, public: open }) {
-        const network = new FakeNetwork({ seed });
-        // Her fakes, each a faculty of the ground granted to her house alone.
-        const faculties = Object.fromEntries(offers.map((offer, index) => [`offer-${index}`, offer]));
-        const ground = await BenchGround.open({
-            network,
-            host: HOST,
-            names: [HOST],
-            machine: new Machine(seed),
-            faculties,
-            modules: {
-                [AUTHOR]: { steward: steward ?? BenchSteward, ...(open === undefined ? {} : { public: open }), beings: [...classes, BenchCaller] },
-                [TESTER]: { steward: BenchCaller },
-            },
-        });
-        const author = await ground.add(AUTHOR, AUTHOR, { faculties: Object.keys(faculties) });
-        const tester = await ground.add(TESTER, TESTER);
-        for (const standing of [author, tester])
-            if (standing.ward === undefined)
-                throw new Error(`the bench's house did not open: ${standing.why}`);
-        return new Bench(network, ground, author.ward, { steward, public: open });
-    }
-    /**
-     * Her class here: the steward or the public being where the bench opened
-     * with her there, and otherwise borne by the bench's own steward, from
-     * her `born`.
-     */
-    async place(Class, { id, born } = {}) {
-        const table = tableOf(Class);
-        if (Class === this.#steward)
-            return new Placed(this, STEWARD, 'steward', table);
-        if (Class === this.#public)
-            return new Placed(this, PUBLIC, 'public', table);
-        if (!this.#own)
-            throw new Error('the bench bears a being beside its own steward alone');
-        const name = id ?? `placed-${++this.#count}`;
-        await this.#rooted(AUTHOR, STEWARD, 'bear', { kind: table.kind, id: name, ...(born === undefined ? {} : { args: born }) });
-        await this.settle();
-        return new Placed(this, name, 'normal', table);
-    }
-    /** Lets every ask, effect and reply the houses started run to its end. */
-    settle() {
-        return this.#network.settle();
-    }
-    /** The clock moved on, and what came due run. */
-    advance(ms) {
-        return this.#network.advance(ms);
-    }
-    /** A placed being's cells, read through the hand. */
-    async cellsOf(placed) {
-        const read = await this.#ground.ask({ house: AUTHOR, id: placed.id, cells: true });
-        if (!('result' in read))
-            throw new Error(`the bench could not read the cells of ${placed.id}: ${JSON.stringify(read)}`);
-        return read.result;
-    }
-    // Who plays a role on her, judged on her cells as they stand. `root` and
-    // a role root holds are the hand's, on any being. On the public being,
-    // `stranger` and a role a stranger holds are a stranger's. The rest need
-    // the bench's own steward: hers for `steward`, a neighbour it introduces
-    // for `being`, and an occupant it invites, the role true in its steward
-    // notes, for any other her table names and that occupant holds.
-    async #player(placed, table, role) {
-        const me = { id: placed.id, position: placed.position, cells: await this.cellsOf(placed) };
-        const holds = (asker) => {
-            const test = table.roles[role];
-            try {
-                return test?.(asker, me) === true;
-            }
-            catch {
-                return false;
-            }
-        };
-        if (role === 'root' || holds(ROOT))
-            return 'hand';
-        if (placed.position === 'public' && (role === 'stranger' || holds(STRANGER)))
-            return 'stranger';
-        if (role === 'handle')
-            return { unplayed: 'a handle is minted by her own ask' };
-        if (!this.#own)
-            return { unplayed: `the bench plays ${role} beside its own steward alone` };
-        if (role === STEWARD)
-            return placed.position === 'steward' ? { unplayed: 'the steward has no steward' } : 'steward';
-        if (role === 'being')
-            return 'neighbour';
-        if (role in table.roles && !holds({ id: `bench-${role}`, notes: {}, steward: { [role]: true } }))
-            return { unplayed: `no one it makes holds ${role} here` };
-        return { notes: role };
-    }
-    /** One ask of a placed being, as whoever plays the role. */
-    async asked(placed, table, role, method, args) {
-        const player = await this.#player(placed, table, role);
-        if (typeof player === 'object' && 'unplayed' in player)
-            throw new Error(`the bench cannot play ${role} on ${placed.id}: ${player.unplayed}`);
-        if (player === 'hand') {
-            const answered = await this.#ground.ask({ house: AUTHOR, id: placed.id, method, args });
-            await this.settle();
-            return 'describe' in answered ? null : answered;
-        }
-        if (player === 'stranger')
-            return this.#outcome(TESTER, STEWARD, 'visit', { ward: this.#ward, at: [`bench://${HOST}`], method, args });
-        if (player === 'steward')
-            return this.#outcome(AUTHOR, STEWARD, 'ask', { id: placed.id, method, args });
-        if (player === 'neighbour')
-            return this.#outcome(AUTHOR, NEIGHBOUR, 'ask', { standing: await this.#neighbour(placed.id), method, args });
-        return this.#outcome(TESTER, STEWARD, 'ask', { standing: await this.#door(placed.id, player.notes), method, args });
-    }
-    /** What a placed being shows whoever plays the role. */
-    async described(placed, table, role) {
-        const player = await this.#player(placed, table, role);
-        if (typeof player === 'object' && 'unplayed' in player)
-            throw new Error(`the bench cannot play ${role} on ${placed.id}: ${player.unplayed}`);
-        let read;
-        if (player === 'hand') {
-            const answered = await this.#ground.ask({ house: AUTHOR, id: placed.id });
-            if (!('describe' in answered))
-                return null;
-            read = answered.describe;
-        }
-        else if (player === 'stranger')
-            read = await this.#rooted(TESTER, STEWARD, 'looks', { ward: this.#ward, at: [`bench://${HOST}`] });
-        else if (player === 'steward')
-            read = await this.#rooted(AUTHOR, STEWARD, 'shows', { id: placed.id });
-        else if (player === 'neighbour')
-            read = await this.#rooted(AUTHOR, NEIGHBOUR, 'describe', { standing: await this.#neighbour(placed.id) });
-        else
-            read = await this.#rooted(TESTER, STEWARD, 'describe', { standing: await this.#door(placed.id, player.notes) });
-        const described = read;
-        return typeof described?.state === 'string' && Array.isArray(described.asks) ? described : null;
-    }
-    // One of the bench's own beings asked through the hand, which fails the test where she answers an error.
-    async #rooted(house, id, method, args) {
-        const answered = await this.#ground.ask({ house, id, method, args });
-        await this.settle();
-        if (!('result' in answered))
-            throw new Error(`the bench's ${id} could not ${method}: ${JSON.stringify(answered)}`);
-        return answered.result;
-    }
-    // One ask through one of the bench's beings: its answer, or the reply its effect brought once it landed, or silence.
-    async #outcome(house, id, method, args) {
-        const replies = async () => (await this.#rooted(house, id, 'replies', {}));
-        const before = (await replies()).length;
-        const read = (await this.#rooted(house, id, method, args));
-        if (read.answer !== undefined)
-            return read.answer;
-        return (await replies())[before] ?? null;
-    }
-    // The caller's standing on her as an occupant whose steward notes hold the role.
-    async #door(being, role) {
-        const key = `${being}\n${role}`;
-        const held = this.#doors.get(key);
-        if (held !== undefined)
-            return held;
-        const { door } = (await this.#rooted(AUTHOR, STEWARD, 'door', { id: being, occupant: `bench-${role}`, role }));
-        const standing = (await this.#rooted(TESTER, STEWARD, 'adopt', { invitation: door }));
-        this.#doors.set(key, standing);
-        return standing;
-    }
-    // The neighbour, borne once and introduced to her; its standing on her is named for her.
-    async #neighbour(being) {
-        if (this.#introduced.size === 0)
-            await this.#rooted(AUTHOR, STEWARD, 'bear', { kind: 'org.nervur.bench.caller', id: NEIGHBOUR });
-        if (being !== STEWARD && !this.#introduced.has(being))
-            await this.#rooted(AUTHOR, STEWARD, 'introduce', { from: NEIGHBOUR, to: being });
-        this.#introduced.add(being);
-        return being;
-    }
-    /** Every example of her class run, twice, on two fresh benches. */
-    static async examples(Class, options = {}) {
-        const table = tableOf(Class);
-        const where = { ...options, seed: options.seed ?? 'examples' };
-        const findings = [];
-        for (const entry of Object.values(table.asks)) {
-            for (const [index, raw] of entry.examples.entries()) {
-                const example = raw;
-                const what = `${entry.method}, example ${index + 1}${example.description === undefined ? '' : `: ${example.description}`}`;
-                try {
-                    const first = await Bench.#run(Class, table, entry, example, where);
-                    const second = await Bench.#run(Class, table, entry, example, where);
-                    if (example.gives !== undefined && canonical(first.answer) !== canonical(example.gives)) {
-                        findings.push({ ok: false, what, why: `it gives ${JSON.stringify(first.answer)}, and the example says ${JSON.stringify(example.gives)}` });
-                    }
-                    else if (canonical(first.answer) !== canonical(second.answer)) {
-                        findings.push({ ok: false, what, why: 'a re-run of the same history answered differently' });
-                    }
-                    else if (canonical(first.cells) !== canonical(second.cells)) {
-                        findings.push({ ok: false, what, why: 'a re-run of the same history left her cells differently' });
-                    }
-                    else
-                        findings.push({ ok: true, what });
-                }
-                catch (error) {
-                    findings.push({ ok: false, what, why: error instanceof Error ? error.message : String(error) });
-                }
-            }
-        }
-        return findings;
-    }
-    // A fresh bench with her in the position the check names, and the steward beside her where one is given.
-    static #opening(Class, table, example, { classes = [], seed, position = 'normal', steward }) {
-        return Bench.open({
-            classes: position === 'normal' ? [Class, ...classes] : classes,
-            offers: fakes(table, example),
-            ...(seed === undefined ? {} : { seed }),
-            ...(position === 'steward' ? { steward: Class } : steward === undefined ? {} : { steward }),
-            ...(position === 'public' ? { public: Class } : {}),
-        });
-    }
-    // Her history asked in its order: each ask of it must answer, or the example names where it stopped.
-    static async #replay(placed, given) {
-        for (const [index, step] of given.entries()) {
-            const answered = await placed.ask(step.ask, step.args ?? {}, step.role === undefined ? {} : { role: step.role });
-            if (answered === null || 'error' in answered)
-                throw new Error(`given ${index + 1}, ${step.ask}, answered ${JSON.stringify(answered)}`);
-        }
-    }
-    static async #run(Class, table, entry, example, options) {
-        const bench = await Bench.#opening(Class, table, example, options);
-        const placed = await bench.place(Class);
-        await Bench.#replay(placed, example.given ?? []);
-        const answer = await placed.ask(entry.method, example.args ?? {}, example.role === undefined ? {} : { role: example.role });
-        return { answer: answer ?? { nothing: true }, cells: await placed.cells() };
-    }
-    /**
-     * Every state her `born` and her examples' histories reach, described to
-     * every role the bench can play: what each is shown is what her table owes.
-     */
-    static async walk(Class, options = {}) {
-        const table = tableOf(Class);
-        const where = { ...options, seed: options.seed ?? 'walk' };
-        const position = options.position ?? 'normal';
-        const findings = [];
-        const histories = [[], ...Object.values(table.asks).flatMap((entry) => entry.examples.map((example) => example.given ?? []))];
-        const seen = new Set();
-        // Each role her position lets someone hold: the steward has no steward, and only the public being has strangers.
-        const roles = [...new Set([STEWARD, ...Object.keys(table.roles), ...Object.values(table.asks).flatMap((entry) => entry.for ?? [])])].filter((role) => role !== 'handle' && (role !== 'stranger' || position === 'public') && (role !== STEWARD || position !== 'steward'));
-        for (const given of histories) {
-            const bench = await Bench.#opening(Class, table, {}, where);
-            const placed = await bench.place(Class);
-            try {
-                await Bench.#replay(placed, given);
-            }
-            catch {
-                // A history that stops is its example's finding, and reaches no state here.
-                continue;
-            }
-            // One visit a state, from the first history that reaches it.
-            const state = (await placed.describe())?.state;
-            if (state === undefined || seen.has(state))
-                continue;
-            seen.add(state);
-            for (const role of roles) {
-                const player = await bench.#player(placed, table, role);
-                if (typeof player === 'object' && 'unplayed' in player)
-                    continue;
-                const what = `${state}, as ${role}`;
-                const described = await placed.describe({ role });
-                const shown = (described?.asks ?? []).map((entry) => entry.method).sort();
-                // A stranger is never shown an effect.
-                const owed = Object.values(table.asks)
-                    .filter((entry) => !(entry.effect && player === 'stranger'))
-                    .filter((entry) => (entry.for === null ? true : entry.for.includes(role)))
-                    .map((entry) => entry.method)
-                    .sort();
-                if (described === null)
-                    findings.push({ ok: false, what, why: 'she answered nothing' });
-                else if (described.state !== state)
-                    findings.push({ ok: false, what, why: `she says ${described.state}` });
-                else if (shown.join() !== owed.join())
-                    findings.push({ ok: false, what, why: `she shows ${shown.join(', ') || 'nothing'}, and her table owes ${owed.join(', ') || 'nothing'}` });
-                else
-                    findings.push({ ok: true, what });
-            }
-        }
-        return findings;
-    }
-    /** Her examples and her walk, and an error naming every finding that failed. */
-    static async check(Class, options = {}) {
-        const findings = [...(await Bench.examples(Class, options)), ...(await Bench.walk(Class, options))];
-        const failed = findings.filter((finding) => !finding.ok);
-        if (failed.length > 0)
-            throw new Error(`the bench found ${failed.length}:\n${failed.map((finding) => `- ${finding.what}: ${finding.why}`).join('\n')}`);
-        return findings;
-    }
-}
-// One JSON value as text with its keys in order, so two answers compare by what they hold.
-const canonical = (value) => JSON.stringify(value, (_key, held) => typeof held === 'object' && held !== null && !Array.isArray(held) ? Object.fromEntries(Object.entries(held).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) : held);
-// A fake of each faculty her needs name, answering what an example says,
-// and `{ result: null }` where it says nothing.
-const fakes = (table, example) => Object.entries(table.needs).map(([member, blueprint]) => {
-    const said = example.fakes?.[member] ?? {};
-    const object = Object.fromEntries(Object.keys(blueprint.methods).map((method) => [method, async () => said[method] ?? { result: null }]));
-    return { blueprint, object, kinds: [table.kind] };
-});

package/dist/bench/fake-clock.d.ts

@@ -1,17 +0,0 @@
-import type { Clock } from '../index.ts';
-export declare class FakeClock implements Clock {
-    #private;
-    constructor(start?: number);
-    now(): number;
-    wait({ id, ms }: {
-        id: string;
-        ms: number;
-    }): Promise<boolean>;
-    cancel({ id }: {
-        id: string;
-    }): void;
-    /** The time moved on, and every wait it passes fired, earliest first. */
-    advance(ms: number): void;
-    /** The time of the earliest wait, or `null`. */
-    next(): number | null;
-}

package/dist/bench/fake-clock.js

@@ -1,34 +0,0 @@
-export class FakeClock {
-    #now;
-    #waits = new Map();
-    constructor(start = Date.UTC(2026, 0, 1)) {
-        this.#now = start;
-    }
-    now() {
-        return this.#now;
-    }
-    wait({ id, ms }) {
-        this.#waits.get(id)?.resolve(false);
-        return new Promise((resolve) => {
-            this.#waits.set(id, { at: this.#now + Math.max(0, ms), resolve });
-        });
-    }
-    cancel({ id }) {
-        this.#waits.get(id)?.resolve(false);
-        this.#waits.delete(id);
-    }
-    /** The time moved on, and every wait it passes fired, earliest first. */
-    advance(ms) {
-        this.#now += ms;
-        const due = [...this.#waits].filter(([, waiting]) => waiting.at <= this.#now).sort(([, a], [, b]) => a.at - b.at);
-        for (const [id, waiting] of due) {
-            this.#waits.delete(id);
-            waiting.resolve(true);
-        }
-    }
-    /** The time of the earliest wait, or `null`. */
-    next() {
-        const times = [...this.#waits.values()].map((waiting) => waiting.at);
-        return times.length === 0 ? null : Math.min(...times);
-    }
-}

package/dist/bench/fake-memory.d.ts

@@ -1,16 +0,0 @@
-import type { Memory } from '../index.ts';
-type PlaceRead = Awaited<ReturnType<Memory['read']>>;
-export declare class FakeMemory implements Memory {
-    #private;
-    /** The next `count` writes are refused, as a memory another writer moved. */
-    refuseNext(count?: number): void;
-    read({ place }: {
-        place: string;
-    }): Promise<PlaceRead>;
-    list(): Promise<readonly string[]>;
-    write({ writes, expect, }: {
-        writes: Readonly<Record<string, Readonly<Record<string, Uint8Array | null>>>>;
-        expect: Readonly<Record<string, string | null>>;
-    }): Promise<Readonly<Record<string, string | null>> | null>;
-}
-export {};

package/dist/bench/fake-memory.js

@@ -1,46 +0,0 @@
-export class FakeMemory {
-    #places = new Map();
-    #refuse = 0;
-    /** The next `count` writes are refused, as a memory another writer moved. */
-    refuseNext(count = 1) {
-        this.#refuse += count;
-    }
-    async read({ place }) {
-        const held = this.#places.get(place);
-        if (held === undefined)
-            return { entries: {}, version: null };
-        return { entries: Object.fromEntries([...held.entries].map(([name, bytes]) => [name, bytes.slice()])), version: String(held.version) };
-    }
-    async list() {
-        return [...this.#places.keys()];
-    }
-    async write({ writes, expect, }) {
-        if (this.#refuse > 0) {
-            this.#refuse--;
-            return null;
-        }
-        for (const place of new Set([...Object.keys(writes), ...Object.keys(expect)])) {
-            const held = this.#places.get(place);
-            const version = held === undefined ? null : String(held.version);
-            if (!(place in expect) || expect[place] !== version)
-                return null;
-        }
-        const versions = {};
-        for (const [place, entries] of Object.entries(writes)) {
-            const held = this.#places.get(place) ?? { entries: new Map(), version: 0 };
-            for (const [name, bytes] of Object.entries(entries)) {
-                if (bytes === null)
-                    held.entries.delete(name);
-                else
-                    held.entries.set(name, bytes.slice());
-            }
-            held.version++;
-            if (held.entries.size === 0)
-                this.#places.delete(place);
-            else
-                this.#places.set(place, held);
-            versions[place] = held.entries.size === 0 ? null : String(held.version);
-        }
-        return versions;
-    }
-}

package/dist/bench/fake-network.d.ts

@@ -1,66 +0,0 @@
-import { type Hooked } from '../index.ts';
-import { FakeClock } from './fake-clock.ts';
-/** How one link behaves, each way: its latency in milliseconds, and the share of boxes dropped, of replies lost, and of boxes delivered twice. */
-export interface Link {
-    readonly latency?: number;
-    readonly drop?: number;
-    readonly lose?: number;
-    readonly duplicate?: number;
-}
-/** What became of one box: dropped before its door, delivered, its reply lost, or delivered twice. */
-export interface Crossing {
-    readonly from: string;
-    readonly to: string;
-    readonly ward: string;
-    readonly outcome: 'dropped' | 'answered' | 'silent' | 'lost' | 'twice' | 'late';
-}
-/** The clock of a network, as a BenchGround reads it. */
-export declare const clockOf: (network: FakeNetwork) => FakeClock;
-export declare class FakeNetwork {
-    #private;
-    /** Every box that crossed between two hosts, in order. A box by pointer inside a host crosses nothing. */
-    readonly crossings: Crossing[];
-    /** `seed` draws every chance; `start` is the time its clock starts at. */
-    constructor({ seed, start }?: {
-        seed?: string;
-        start?: number;
-    });
-    /** The time on its clock, which every ground on it reads. */
-    now(): number;
-    /** Every ask, effect and reply the grounds started, run to where it waits on the clock or ends. */
-    settle(): Promise<void>;
-    /** The clock moved on by `ms` at once, every wait it passes fired, and what came due run. */
-    advance(ms: number): Promise<void>;
-    /** A host's carry. One that listens is dialled at its names; one that does not only dials, as a device. */
-    join(host: string, { names, listens, serve }?: {
-        names?: readonly string[];
-        listens?: boolean;
-        serve?: (request: Request) => Promise<Response>;
-    }): Hooked;
-    /** A name pointed at a host, as a DNS record moved. */
-    point(name: string, host: string): void;
-    /** How the link between two hosts behaves, both ways, until it is set again. */
-    link(a: string, b: string, link: Link): void;
-    /** No box crosses from `from` to `to` until `heal`; the other way stands. */
-    cut(from: string, to: string): void;
-    /** No box crosses between the two hosts, either way, until `heal`. */
-    partition(a: string, b: string): void;
-    /** Every cut mended. Links keep how they behave. */
-    heal(): void;
-    /** The host answers nothing, its doors forgotten, until `up`. */
-    down(host: string): void;
-    up(host: string): void;
-    /** The next `count` boxes between hosts are dropped before their door. */
-    dropNext(count?: number): void;
-    /** The next `count` replies are lost after the far door answered. */
-    loseNext(count?: number): void;
-    /** The next `count` boxes are delivered twice, and the first reply returns. */
-    duplicateNext(count?: number): void;
-    /**
-     * The clock moved on by `ms` in steps of `step`, the bench settling after
-     * each, so latencies end, retries leave and replies land as time passes.
-     */
-    elapse(ms: number, { step }?: {
-        step?: number;
-    }): Promise<void>;
-}