nervur 0.22.0 → 0.22.2-3

package/dist/being/schema.js

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: Apache-2.0
+// The schema builder. Each call writes JSON Schema 2020-12 in the closed
+// subset the house checks, and carries the TypeScript type beside it.
+export const HANDLE_MEDIA = 'application/vnd.nervur.handle';
+export const INVITATION_MEDIA = 'application/vnd.nervur.invitation';
+/** The keywords the house checks, and no other. */
+export const KEYWORDS = new Set([
+    'type',
+    'properties',
+    'required',
+    'additionalProperties',
+    'enum',
+    'const',
+    'items',
+    'minLength',
+    'maxLength',
+    'minimum',
+    'maximum',
+    'pattern',
+    'anyOf',
+    'contentEncoding',
+    'contentMediaType',
+]);
+const TYPES = new Set(['object', 'array', 'string', 'number', 'integer', 'boolean', 'null']);
+const OPTIONAL = Symbol('optional');
+const frozen = (schema) => Object.freeze(schema);
+const bounded = (schema, bounds = {}) => {
+    for (const [key, value] of Object.entries(bounds))
+        if (value !== undefined)
+            Object.assign(schema, { [key]: value });
+    return schema;
+};
+export const s = Object.freeze({
+    object: (properties) => {
+        const required = Object.keys(properties).filter((key) => !(OPTIONAL in properties[key]));
+        const plain = Object.fromEntries(Object.entries(properties).map(([key, value]) => [key, strip(value)]));
+        return frozen({ type: 'object', properties: Object.freeze(plain), required: Object.freeze(required), additionalProperties: false });
+    },
+    string: (lengths) => frozen(bounded({ type: 'string' }, lengths)),
+    number: (bounds) => frozen(bounded({ type: 'number' }, bounds)),
+    integer: (bounds) => frozen(bounded({ type: 'integer' }, bounds)),
+    boolean: () => frozen({ type: 'boolean' }),
+    array: (items) => frozen({ type: 'array', items: strip(items) }),
+    enum: (values) => frozen({ enum: Object.freeze([...values]) }),
+    const: (value) => frozen({ const: value }),
+    // Lengths count bytes, and the schema counts their hex, two digits a byte.
+    bytes: (lengths) => frozen(bounded({ type: 'string', contentEncoding: 'base16' }, { minLength: lengths?.minLength === undefined ? undefined : lengths.minLength * 2, maxLength: lengths?.maxLength === undefined ? undefined : lengths.maxLength * 2 })),
+    optional: (schema) => Object.freeze({ ...schema, [OPTIONAL]: true }),
+    handle: () => frozen({ type: 'string', contentEncoding: 'base16', contentMediaType: HANDLE_MEDIA }),
+    invitation: () => frozen({ type: 'string', contentEncoding: 'base16', contentMediaType: INVITATION_MEDIA }),
+    reply: (method) => frozen({
+        anyOf: Object.freeze([
+            s.object({ result: method.result ?? s.const(null) }),
+            s.object({ error: s.object({ message: s.string() }) }),
+        ]),
+    }),
+});
+const strip = (schema) => {
+    if (!(OPTIONAL in schema))
+        return schema;
+    const { [OPTIONAL]: _mark, ...plain } = schema;
+    return frozen(plain);
+};
+/**
+ * Every way a schema leaves the subset, each as a sentence naming where.
+ * The empty list is a schema the house checks.
+ */
+export const outside = (schema, at = 'the schema') => {
+    if (typeof schema !== 'object' || schema === null || Array.isArray(schema))
+        return [`${at} is not a schema object`];
+    const found = [];
+    const node = schema;
+    for (const key of Object.keys(node))
+        if (!KEYWORDS.has(key))
+            found.push(`${at} names ${key}, outside the subset`);
+    const type = node.type;
+    if (type !== undefined && !(typeof type === 'string' && TYPES.has(type)))
+        found.push(`${at} has a type the subset does not name`);
+    if (node.contentEncoding !== undefined && node.contentEncoding !== 'base16')
+        found.push(`${at} has a contentEncoding other than base16`);
+    const media = node.contentMediaType;
+    if (media !== undefined && media !== HANDLE_MEDIA && media !== INVITATION_MEDIA)
+        found.push(`${at} has a contentMediaType that is not a mark`);
+    if (media !== undefined && node.contentEncoding !== 'base16')
+        found.push(`${at} marks a relation that is not base16`);
+    for (const key of ['minLength', 'maxLength']) {
+        const value = node[key];
+        if (value !== undefined && !(Number.isInteger(value) && value >= 0))
+            found.push(`${at} has a ${key} that is not a count`);
+    }
+    for (const key of ['minimum', 'maximum']) {
+        if (node[key] !== undefined && !Number.isFinite(node[key]))
+            found.push(`${at} has a ${key} that is not a number`);
+    }
+    if (node.pattern !== undefined)
+        found.push(...pattern(node.pattern, at));
+    if (node.properties !== undefined) {
+        if (typeof node.properties !== 'object' || node.properties === null || Array.isArray(node.properties))
+            found.push(`${at} has properties that are not an object`);
+        else
+            for (const [key, value] of Object.entries(node.properties))
+                found.push(...outside(value, `${at}.${key}`));
+    }
+    if (node.required !== undefined && !(Array.isArray(node.required) && node.required.every((key) => typeof key === 'string')))
+        found.push(`${at} has required that is not a list of names`);
+    if (node.additionalProperties !== undefined && typeof node.additionalProperties !== 'boolean')
+        found.push(`${at} has additionalProperties that is not true or false`);
+    if (node.enum !== undefined && !(Array.isArray(node.enum) && node.enum.every(scalar)))
+        found.push(`${at} has an enum that is not a list of scalars`);
+    if ('const' in node && !scalar(node.const))
+        found.push(`${at} has a const that is not a scalar`);
+    if (node.items !== undefined)
+        found.push(...outside(node.items, `${at}[]`));
+    if (node.anyOf !== undefined) {
+        if (!Array.isArray(node.anyOf) || node.anyOf.length === 0)
+            found.push(`${at} has an anyOf that is not a list of schemas`);
+        else
+            node.anyOf.forEach((branch, index) => found.push(...outside(branch, `${at}|${index}`)));
+    }
+    return found;
+};
+const scalar = (value) => value === null || ['string', 'number', 'boolean'].includes(typeof value);
+const pattern = (value, at) => {
+    if (typeof value !== 'string')
+        return [`${at} has a pattern that is not a string`];
+    try {
+        return RegExp(value, 'u').unicode ? [] : [`${at} has a pattern that is not unicode`];
+    }
+    catch {
+        return [`${at} has a pattern that does not compile`];
+    }
+};

package/dist/being/table.d.ts

@@ -0,0 +1,42 @@
+import { type Json, type Me } from './being.ts';
+import { type Blueprint, type BlueprintMethod } from './need.ts';
+/** The roles the house names. */
+export declare const HOUSE_ROLES: ReadonlySet<string>;
+/** The state of a class that names none. */
+export declare const READY = "ready";
+/** An ask's entry, settled. `null` is the entry's omission. */
+export interface TableEntry extends BlueprintMethod {
+    readonly method: string;
+    /** Where the ask exists; `null`, every state. */
+    readonly in: readonly string[] | null;
+    /** Who may call it; `null`, every occupant but handles. */
+    readonly for: readonly string[] | null;
+    /** Where it may land; `null`, the state it began in. */
+    readonly to: readonly string[] | null;
+    /** Its author wrote `idempotent: false`, which a public being's default needs to know. */
+    readonly effect: boolean;
+    readonly examples: readonly Json[];
+}
+/** A class as the house reads her. */
+export interface Table {
+    readonly kind: string;
+    readonly description?: string;
+    readonly view?: string;
+    readonly cells: Readonly<Record<string, Json>>;
+    readonly needs: Readonly<Record<string, Blueprint>>;
+    readonly roles: Readonly<Record<string, (asker: never, me: never) => boolean>>;
+    readonly state: (me: Me<Record<string, Json>>) => string;
+    /** The state of her default cells. */
+    readonly first: string;
+    readonly states: readonly string[];
+    readonly asks: Readonly<Record<string, TableEntry>>;
+}
+/** A class the house will not resolve, and every reason why. */
+export declare class Refused extends Error {
+    readonly reasons: readonly string[];
+    constructor(what: string, reasons: readonly string[]);
+}
+/** Whether a value is JSON, as cells and notes hold. */
+export declare const isJson: (value: unknown) => value is Json;
+/** Her class checked and settled, or refused with every reason. */
+export declare const resolve: (Class: unknown) => Table;

package/dist/being/table.js

@@ -0,0 +1,288 @@
+// SPDX-License-Identifier: Apache-2.0
+// A class resolved: her declaration checked and settled into the table the
+// house reads. Every way a class fails is gathered, and the refusal names
+// each one.
+import { DECLARATION, MEMBERS } from './being.js';
+import { blueprintOf, method, WAIT_BOUND } from './need.js';
+import { outside } from './schema.js';
+/** The roles the house names. */
+export const HOUSE_ROLES = new Set(['handle', 'stranger', 'steward', 'being', 'root']);
+/** The state of a class that names none. */
+export const READY = 'ready';
+/** A class the house will not resolve, and every reason why. */
+export class Refused extends Error {
+    reasons;
+    constructor(what, reasons) {
+        super(`${what} is refused: ${reasons.join('; ')}`);
+        this.name = 'Refused';
+        this.reasons = reasons;
+    }
+}
+const KIND = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*){2,}$/;
+const VIEW_BYTES = 65_536;
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const BLUEPRINT_NAME = /^[a-z][a-z0-9._-]*$/;
+const ENTRY_FIELDS = new Set(['in', 'for', 'to', 'args', 'result', 'hints', 'examples', 'description', 'wait']);
+const METHOD_FIELDS = new Set(['args', 'result', 'hints', 'description', 'wait']);
+const HINTS = new Set(['readOnly', 'idempotent', 'destructive']);
+const EXAMPLE_FIELDS = new Set(['description', 'cells', 'role', 'args', 'fakes', 'gives']);
+const EVERY_OBJECT = new Set(Object.getOwnPropertyNames(Object.prototype));
+const plain = (value) => {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+};
+/** Whether a value is JSON, as cells and notes hold. */
+export const isJson = (value) => {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJson);
+    return plain(value) && Object.values(value).every(isJson);
+};
+const names = (value, where, reasons) => {
+    if (value === undefined)
+        return null;
+    const list = typeof value === 'string' ? [value] : value;
+    if (!Array.isArray(list) || list.length === 0 || !list.every((name) => typeof name === 'string' && name.length > 0)) {
+        reasons.push(`${where} is not a name or a list of names`);
+        return [];
+    }
+    return Object.freeze([...new Set(list)]);
+};
+// Args are always an object: one, or a choice of several, as a reply is.
+const objectSchema = (schema) => schema.type === 'object' || (Array.isArray(schema.anyOf) && schema.anyOf.length > 0 && schema.anyOf.every((branch) => plain(branch) && objectSchema(branch)));
+const methodChecked = (spec, fields, where, reasons) => {
+    if (!plain(spec)) {
+        reasons.push(`${where} is not an object`);
+        return undefined;
+    }
+    for (const key of Object.keys(spec))
+        if (!fields.has(key))
+            reasons.push(`${where} names ${key}, which is no field`);
+    const { args, result, hints, description, wait } = spec;
+    if (wait !== undefined && !(Number.isInteger(wait) && wait > 0 && wait <= WAIT_BOUND))
+        reasons.push(`${where}.wait is not a count of milliseconds within five minutes`);
+    if (args !== undefined) {
+        reasons.push(...outside(args, `${where}.args`));
+        if (plain(args) && !objectSchema(args))
+            reasons.push(`${where}.args is not an object schema`);
+    }
+    if (result !== undefined)
+        reasons.push(...outside(result, `${where}.result`));
+    if (description !== undefined && typeof description !== 'string')
+        reasons.push(`${where}.description is not a string`);
+    if (hints !== undefined) {
+        if (!plain(hints))
+            reasons.push(`${where}.hints is not an object`);
+        else {
+            for (const [key, value] of Object.entries(hints)) {
+                if (!HINTS.has(key))
+                    reasons.push(`${where}.hints names ${key}, which is no hint`);
+                else if (typeof value !== 'boolean')
+                    reasons.push(`${where}.hints.${key} is not true or false`);
+            }
+            if (hints.readOnly === true && hints.idempotent === false)
+                reasons.push(`${where} is readOnly and not idempotent`);
+        }
+    }
+    return method(spec);
+};
+const blueprintChecked = (blueprint, where, reasons) => {
+    if (typeof blueprint.name !== 'string' || !BLUEPRINT_NAME.test(blueprint.name))
+        reasons.push(`${where} has a name that is no blueprint name`);
+    for (const [name, spec] of Object.entries(blueprint.methods)) {
+        if (!NAME.test(name))
+            reasons.push(`${where}.${name} is no method name`);
+        methodChecked(spec, METHOD_FIELDS, `${where}.${name}`, reasons);
+    }
+    return blueprint;
+};
+const examplesChecked = (examples, where, reasons) => {
+    if (examples === undefined)
+        return [];
+    if (!Array.isArray(examples)) {
+        reasons.push(`${where}.examples is not a list`);
+        return [];
+    }
+    examples.forEach((example, index) => {
+        if (!plain(example) || !isJson(example)) {
+            reasons.push(`${where}.examples[${index}] is not a JSON object`);
+            return;
+        }
+        for (const key of Object.keys(example))
+            if (!EXAMPLE_FIELDS.has(key))
+                reasons.push(`${where}.examples[${index}] names ${key}, which is no field`);
+    });
+    return Object.freeze([...examples]);
+};
+/** Her class checked and settled, or refused with every reason. */
+export const resolve = (Class) => {
+    const declaration = typeof Class === 'function' ? Class[DECLARATION] : undefined;
+    if (declaration === undefined)
+        throw new Refused('the class', ['it is not a class of Being.of']);
+    const reasons = [];
+    const kind = declaration.kind;
+    if (typeof kind !== 'string' || !KIND.test(kind))
+        reasons.push('its kind is not a reversed domain and a name');
+    const what = typeof kind === 'string' ? kind : 'the class';
+    if (declaration.description !== undefined && typeof declaration.description !== 'string')
+        reasons.push('its description is not a string');
+    // A view is data a screen renders, never more than a screen holds.
+    if (declaration.view !== undefined && (typeof declaration.view !== 'string' || new TextEncoder().encode(declaration.view).length > VIEW_BYTES))
+        reasons.push('its view is not text of at most 64 KiB');
+    const cells = declaration.cells ?? {};
+    if (!plain(cells) || !isJson(cells))
+        reasons.push('its cells are not a JSON object');
+    // Needs, each a blueprint under her own member name.
+    const needs = {};
+    const declaredNeeds = declaration.needs ?? {};
+    if (!plain(declaredNeeds))
+        reasons.push('its needs are not an object');
+    else {
+        for (const [member, value] of Object.entries(declaredNeeds)) {
+            const blueprint = blueprintOf(value);
+            if (blueprint === undefined)
+                reasons.push(`its need ${member} is not a need`);
+            else
+                needs[member] = blueprintChecked(blueprint, `its need ${member}`, reasons);
+        }
+    }
+    // Roles, the author's tests over the asker and her cells.
+    const roles = declaration.roles ?? {};
+    if (!plain(roles))
+        reasons.push('its roles are not an object');
+    for (const [name, test] of Object.entries(plain(roles) ? roles : {})) {
+        if (HOUSE_ROLES.has(name))
+            reasons.push(`its role ${name} is the house's`);
+        if (typeof test !== 'function')
+            reasons.push(`its role ${name} is not a function`);
+    }
+    // Asks, each an entry and a method.
+    const asks = {};
+    const declaredAsks = declaration.asks;
+    if (!plain(declaredAsks))
+        reasons.push('its asks are not an object');
+    const prototype = Class.prototype;
+    for (const [name, entry] of Object.entries(plain(declaredAsks) ? declaredAsks : {})) {
+        const where = `its ask ${name}`;
+        if (!NAME.test(name))
+            reasons.push(`${where} is no method name`);
+        const settled = methodChecked(entry, ENTRY_FIELDS, where, reasons);
+        if (settled === undefined)
+            continue;
+        const raw = entry;
+        if (typeof prototype[name] !== 'function')
+            reasons.push(`${where} has no method`);
+        asks[name] = Object.freeze({
+            ...settled,
+            method: name,
+            in: names(raw.in, `${where}.in`, reasons),
+            for: names(raw.for, `${where}.for`, reasons),
+            to: names(raw.to, `${where}.to`, reasons),
+            effect: raw.hints?.idempotent === false,
+            examples: examplesChecked(raw.examples, where, reasons),
+        });
+    }
+    // Member names: a need, an ask, a member of Being and her own methods.
+    const own = new Set();
+    for (let proto = prototype; proto !== null && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {
+        for (const key of Object.getOwnPropertyNames(proto))
+            if (key !== 'constructor')
+                own.add(key);
+    }
+    for (const member of Object.keys(needs)) {
+        if (member in asks)
+            reasons.push(`its need ${member} and its ask ${member} share a name`);
+        if (MEMBERS.has(member))
+            reasons.push(`its need ${member} and Being's ${member} share a name`);
+        if (own.has(member))
+            reasons.push(`its need ${member} and its method ${member} share a name`);
+        if (EVERY_OBJECT.has(member))
+            reasons.push(`its need ${member} is a member of every object`);
+    }
+    for (const name of Object.keys(asks)) {
+        if (MEMBERS.has(name))
+            reasons.push(`its ask ${name} and Being's ${name} share a name`);
+        if (EVERY_OBJECT.has(name))
+            reasons.push(`its ask ${name} is a member of every object`);
+    }
+    // The state, and the state of her default cells.
+    const state = declaration.state ?? (() => READY);
+    let first = READY;
+    if (declaration.state !== undefined) {
+        if (typeof declaration.state !== 'function')
+            reasons.push('its state is not a function');
+        else {
+            try {
+                first = declaration.state({ id: '', position: 'normal', cells: cells });
+            }
+            catch {
+                reasons.push('its state throws on its default cells');
+            }
+            if (typeof first !== 'string' || first.length === 0)
+                reasons.push('its state names no state on its default cells');
+        }
+    }
+    const states = table(asks, roles, first, declaration.state !== undefined, reasons);
+    if (reasons.length > 0)
+        throw new Refused(what, reasons);
+    return Object.freeze({
+        kind,
+        ...(declaration.description === undefined ? {} : { description: declaration.description }),
+        ...(declaration.view === undefined ? {} : { view: declaration.view }),
+        cells: cells,
+        needs: Object.freeze(needs),
+        roles: Object.freeze({ ...roles }),
+        state: state,
+        first,
+        states,
+        asks: Object.freeze(asks),
+    });
+};
+// The table: every state reached from the first, every ask reached by a
+// role, and every role named by an ask. A terminal state is allowed.
+const table = (asks, roles, first, stated, reasons) => {
+    const named = new Set([first]);
+    for (const entry of Object.values(asks))
+        for (const name of [...(entry.in ?? []), ...(entry.to ?? [])])
+            named.add(name);
+    if (!stated)
+        for (const name of named)
+            if (name !== READY)
+                reasons.push(`it names the state ${name} and has no state of its own`);
+    const reached = new Set([first]);
+    const queue = [first];
+    while (queue.length > 0) {
+        const at = queue.shift();
+        for (const entry of Object.values(asks)) {
+            if (entry.in !== null && !entry.in.includes(at))
+                continue;
+            for (const next of entry.to ?? [at]) {
+                if (reached.has(next))
+                    continue;
+                reached.add(next);
+                queue.push(next);
+            }
+        }
+    }
+    for (const name of named)
+        if (!reached.has(name))
+            reasons.push(`no ask reaches the state ${name}`);
+    const declared = new Set(Object.keys(roles));
+    const used = new Set();
+    for (const entry of Object.values(asks)) {
+        for (const role of entry.for ?? []) {
+            used.add(role);
+            if (!declared.has(role) && !HOUSE_ROLES.has(role))
+                reasons.push(`its ask ${entry.method} is for ${role}, which is no role`);
+        }
+    }
+    for (const role of declared)
+        if (!used.has(role))
+            reasons.push(`its role ${role} is named by no ask`);
+    return Object.freeze([...named]);
+};

package/dist/bench/bench-ground.d.ts

@@ -0,0 +1,55 @@
+import type { BeingClass, Memory } from '../foundation.ts';
+import { Ground, type Bodies, type Faculty, type HandAsk, type Standing, type Entry } from '../ground/ground.ts';
+import type { FakeClock } from './fake-clock.ts';
+import { FakeCustody } from './fake-custody.ts';
+import { FakeMemory } from './fake-memory.ts';
+import type { FakeNetwork } from './fake-network.ts';
+/** A house module: what a folder's index exports. */
+export interface HouseModule {
+    readonly steward: BeingClass;
+    readonly public?: BeingClass;
+    readonly beings?: readonly BeingClass[];
+}
+/** What a ground keeps across its lives: its seeds, its record, and each house's memory. */
+export declare class Machine {
+    readonly custody: FakeCustody;
+    readonly memory: FakeMemory;
+    readonly houses: Map<string, FakeMemory>;
+    constructor(seed: string);
+    memoryOf(house: string): Memory;
+}
+export interface BenchGroundOptions {
+    readonly network: FakeNetwork;
+    /** Its host on the network. */
+    readonly host: string;
+    /** The names that point at it; a ground with none is a device, and is never dialled. */
+    readonly names?: readonly string[];
+    readonly clock: FakeClock;
+    /** The house modules its entries name, by name. */
+    readonly modules?: Readonly<Record<string, HouseModule>>;
+    readonly faculties?: Readonly<Record<string, Faculty>>;
+    /** Custom bodies beside the bench's own `fake` memory and `module` classes, as a recipe adds them. */
+    readonly bodies?: Partial<Bodies>;
+    /** The machine it opens on; a fresh one, seeded by its host, where none is named. */
+    readonly machine?: Machine;
+}
+export declare class BenchGround {
+    #private;
+    readonly host: string;
+    readonly machine: Machine;
+    private constructor();
+    static open(options: BenchGroundOptions): Promise<BenchGround>;
+    /** The ground on its machine again, joined to the network, every house of its record open. */
+    up(): Promise<void>;
+    /** The ground off: its houses closed, its host answering nothing. Its machine keeps everything. */
+    down(): Promise<void>;
+    /** A house of a module by that module's name, on fake memory. */
+    /**
+     * A house: of a module by that module's name, on fake memory, or on the
+     * whole entry the test gives, custom bodies and all.
+     */
+    add(name: string, from?: string | Entry, rest?: Omit<Entry, 'memory' | 'classes'>): Promise<Standing>;
+    remove(name: string): Promise<void>;
+    list(): readonly Standing[];
+    ask(request: HandAsk): ReturnType<Ground['ask']>;
+}

package/dist/bench/bench-ground.js

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0
+// A ground in memory. It joins a FakeNetwork under its host, keeps its
+// seeds, its record and each house's memory in a machine that outlives it,
+// and opens house modules by name. So a test turns it off, opens it again
+// on the same machine, or moves the machine to another host.
+import { ClassList } from '../bodies/class-list.js';
+import { Ground } from '../ground/ground.js';
+import { FakeCustody } from './fake-custody.js';
+import { FakeMemory } from './fake-memory.js';
+/** What a ground keeps across its lives: its seeds, its record, and each house's memory. */
+export class Machine {
+    custody;
+    memory = new FakeMemory();
+    houses = new Map();
+    constructor(seed) {
+        this.custody = new FakeCustody(seed);
+    }
+    memoryOf(house) {
+        return this.houses.get(house) ?? this.houses.set(house, new FakeMemory()).get(house);
+    }
+}
+export class BenchGround {
+    host;
+    machine;
+    #options;
+    #ground;
+    constructor(options, machine) {
+        this.host = options.host;
+        this.machine = machine;
+        this.#options = options;
+    }
+    static async open(options) {
+        const bench = new BenchGround(options, options.machine ?? new Machine(options.host));
+        await bench.up();
+        return bench;
+    }
+    #live() {
+        if (this.#ground === undefined)
+            throw new Error(`the ground ${this.host} is down`);
+        return this.#ground;
+    }
+    /** The ground on its machine again, joined to the network, every house of its record open. */
+    async up() {
+        if (this.#ground !== undefined)
+            return;
+        const { network, host, names = [], clock, modules = {}, faculties = {}, bodies = {} } = this.#options;
+        network.up(host);
+        const carry = network.join(host, { names, listens: names.length > 0 });
+        // The bench's own bodies, and the test's beside them, never in their place.
+        const joined = (own, added = {}) => {
+            for (const name of Object.keys(added))
+                if (name in own)
+                    throw new TypeError(`the body ${name} is the bench's own`);
+            return { ...own, ...added };
+        };
+        this.#ground = await Ground.open({
+            custody: this.machine.custody,
+            memory: this.machine.memory,
+            carry,
+            clock,
+            faculties,
+            bodies: {
+                memory: joined({ fake: ({ house }) => this.machine.memoryOf(house) }, bodies.memory),
+                classes: joined({
+                    module: ({ args }) => {
+                        const module = modules[args.name];
+                        if (module === undefined)
+                            throw new Error(`no house module ${String(args.name)}`);
+                        return new ClassList({ steward: module.steward, ...(module.public === undefined ? {} : { public: module.public }), beings: module.beings ?? [] });
+                    },
+                }, bodies.classes),
+            },
+        });
+    }
+    /** The ground off: its houses closed, its host answering nothing. Its machine keeps everything. */
+    async down() {
+        const ground = this.#ground;
+        if (ground === undefined)
+            return;
+        this.#ground = undefined;
+        await ground.close();
+        this.#options.network.down(this.host);
+    }
+    /** A house of a module by that module's name, on fake memory. */
+    /**
+     * A house: of a module by that module's name, on fake memory, or on the
+     * whole entry the test gives, custom bodies and all.
+     */
+    add(name, from = name, rest = {}) {
+        return this.#live().add(name, typeof from === 'string' ? { memory: { body: 'fake' }, classes: { body: 'module', name: from }, ...rest } : from);
+    }
+    remove(name) {
+        return this.#live().remove(name);
+    }
+    list() {
+        return this.#live().list();
+    }
+    ask(request) {
+        return this.#live().ask(request);
+    }
+}