nervur 0.23.0 → 0.24.0

package/dist/ground/views.d.ts

@@ -1,76 +0,0 @@
-import type { Carry, Clock, Crypto, Memory, PlaceRead, Sent, Tools } from '../foundation.ts';
-export declare class HouseClock implements Clock {
-    #private;
-    constructor(clock: Clock, house: string);
-    now(): number;
-    wait({ id, ms }: {
-        id: string;
-        ms: number;
-    }): Promise<boolean>;
-    cancel({ id }: {
-        id: string;
-    }): void;
-    close(): void;
-}
-export declare class HouseCarry implements Carry {
-    #private;
-    constructor(carry: Carry);
-    send(options: {
-        ward: string;
-        at: readonly string[];
-        box: Uint8Array;
-        wait?: number;
-    }): Promise<Sent>;
-    at(options?: {
-        toward?: string;
-    }): readonly string[];
-    vouched(options: {
-        ward: string;
-        at: readonly string[];
-    }): Promise<readonly string[]>;
-    close(): void;
-}
-export declare class LadderCarry implements Carry {
-    #private;
-    constructor(carry: () => Carry | string);
-    send(options: {
-        ward: string;
-        at: readonly string[];
-        box: Uint8Array;
-        wait?: number;
-    }): Promise<Sent>;
-    at(options?: {
-        toward?: string;
-    }): readonly string[];
-    vouched(options: {
-        ward: string;
-        at: readonly string[];
-    }): Promise<readonly string[]>;
-}
-type Writes = Readonly<Record<string, Readonly<Record<string, Uint8Array | null>>>>;
-type Expect = Readonly<Record<string, string | null>>;
-export declare class ViewMemory implements Memory {
-    #private;
-    constructor(memory: Memory, prefix: string);
-    read({ place }: {
-        place: string;
-    }): Promise<PlaceRead>;
-    list(): Promise<readonly string[]>;
-    write({ writes, expect }: {
-        writes: Writes;
-        expect: Expect;
-    }): Promise<Readonly<Record<string, string | null>> | null>;
-}
-export declare class SealedMemory implements Memory {
-    #private;
-    constructor(memory: Memory, key: Uint8Array, crypto: Crypto, tools: Tools);
-    read({ place }: {
-        place: string;
-    }): Promise<PlaceRead>;
-    list(): Promise<readonly string[]>;
-    write({ writes, expect }: {
-        writes: Writes;
-        expect: Expect;
-    }): Promise<Readonly<Record<string, string | null>> | null>;
-}
-export {};

package/dist/ground/views.js

@@ -1,208 +0,0 @@
-// The ground's clock as one house sees it: its waits named apart from every
-// other house's. When the ground closes it, every wait runs out, and each
-// wait asked after runs out once, so every ask in flight on the house ends
-// and none waits again.
-export class HouseClock {
-    #clock;
-    #prefix;
-    #waits = new Map();
-    /** The waits that ran out after the close, each once. */
-    #spent = new Set();
-    #turn = 0;
-    #closed = false;
-    constructor(clock, house) {
-        this.#clock = clock;
-        this.#prefix = `${house}\n`;
-    }
-    now() {
-        return this.#clock.now();
-    }
-    wait({ id, ms }) {
-        if (this.#closed) {
-            if (this.#spent.has(id))
-                return Promise.resolve(false);
-            this.#spent.add(id);
-            return Promise.resolve(true);
-        }
-        const turn = ++this.#turn;
-        return new Promise((run) => {
-            this.#waits.get(id)?.run(false);
-            this.#waits.set(id, { turn, run });
-            void this.#clock.wait({ id: this.#prefix + id, ms }).then((fired) => {
-                if (this.#waits.get(id)?.turn === turn)
-                    this.#waits.delete(id);
-                run(fired);
-            });
-        });
-    }
-    cancel({ id }) {
-        this.#clock.cancel({ id: this.#prefix + id });
-    }
-    close() {
-        this.#closed = true;
-        for (const [id, { run }] of this.#waits) {
-            this.#spent.add(id);
-            run(true);
-            this.#clock.cancel({ id: this.#prefix + id });
-        }
-        this.#waits.clear();
-    }
-}
-// The ground's carry as one house sees it: silent once the ground closes it.
-export class HouseCarry {
-    #carry;
-    #closed = false;
-    constructor(carry) {
-        this.#carry = carry;
-    }
-    send(options) {
-        return this.#closed ? Promise.resolve({ reply: null, heard: false }) : this.#carry.send(options);
-    }
-    at(options = {}) {
-        return this.#carry.at(options);
-    }
-    vouched(options) {
-        return this.#closed ? Promise.resolve([]) : this.#carry.vouched(options);
-    }
-    close() {
-        this.#closed = true;
-    }
-}
-// The carry the dock holds from before the ladder stands: each send goes by
-// the carries standing when it is made, and where none stands it is unheard.
-export class LadderCarry {
-    #carry;
-    constructor(carry) {
-        this.#carry = carry;
-    }
-    send(options) {
-        const carry = this.#carry();
-        return typeof carry === 'string' ? Promise.resolve({ reply: null, heard: false }) : carry.send(options);
-    }
-    at(options = {}) {
-        const carry = this.#carry();
-        return typeof carry === 'string' ? [] : carry.at(options);
-    }
-    vouched(options) {
-        const carry = this.#carry();
-        return typeof carry === 'string' ? Promise.resolve([]) : carry.vouched(options);
-    }
-}
-// The places of one memory under a prefix, named without it: a view lists
-// its own places alone, so one memory holds a ground's every house and
-// faculty, and each reads as a memory of its own.
-export class ViewMemory {
-    #memory;
-    #prefix;
-    constructor(memory, prefix) {
-        if (prefix === '')
-            throw new TypeError('a view names a prefix');
-        this.#memory = memory;
-        this.#prefix = prefix;
-    }
-    read({ place }) {
-        return this.#memory.read({ place: this.#prefix + place });
-    }
-    async list() {
-        return (await this.#memory.list()).filter((place) => place.startsWith(this.#prefix)).map((place) => place.slice(this.#prefix.length));
-    }
-    async write({ writes, expect }) {
-        const inner = (named) => Object.fromEntries(Object.entries(named).map(([place, value]) => [this.#prefix + place, value]));
-        const landed = await this.#memory.write({ writes: inner(writes), expect: inner(expect) });
-        if (landed === null)
-            return null;
-        return Object.fromEntries(Object.keys(writes).map((place) => [place, landed[this.#prefix + place] ?? null]));
-    }
-}
-const NONCE = 12;
-// A memory whose every entry is sealed under one key. A place and an entry
-// are kept under digests that say nothing, and each sealed entry carries
-// its place's name and its own, so the view reads back what was written.
-// Versions pass through, so `expect` guards one writer as it does below.
-export class SealedMemory {
-    #memory;
-    #key;
-    #crypto;
-    #tools;
-    constructor(memory, key, crypto, tools) {
-        if (key.length !== 32)
-            throw new TypeError('a sealed memory takes a key of thirty-two bytes');
-        this.#memory = memory;
-        this.#key = key;
-        this.#crypto = crypto;
-        this.#tools = tools;
-    }
-    async #digest(text) {
-        return this.#tools.hex((await this.#crypto.sha256(new Uint8Array([...this.#key, ...this.#tools.utf8(text)]))).subarray(0, 16));
-    }
-    #place(place) {
-        return this.#digest(`place\n${place}`);
-    }
-    #entry(place, entry) {
-        return this.#digest(`entry\n${place}\n${entry}`);
-    }
-    // One entry opened: its place, its name and its bytes, or `null` where it does not open under this key.
-    async #open(stored, name, sealed) {
-        const opened = await this.#crypto.open(this.#key, sealed.subarray(0, NONCE), sealed.subarray(NONCE), this.#tools.utf8(`${stored}\n${name}`));
-        if (opened === null || opened.length < 4)
-            return null;
-        const length = new DataView(opened.buffer, opened.byteOffset, opened.byteLength).getUint32(0);
-        const header = this.#tools.text(opened.subarray(4, 4 + length));
-        const parsed = header === null ? null : this.#tools.parse(header);
-        const names = parsed?.value;
-        if (!Array.isArray(names) || names.length !== 2 || typeof names[0] !== 'string' || typeof names[1] !== 'string')
-            return null;
-        return { place: names[0], entry: names[1], bytes: opened.slice(4 + length) };
-    }
-    async read({ place }) {
-        const stored = await this.#place(place);
-        const { entries, version } = await this.#memory.read({ place: stored });
-        const read = {};
-        for (const [name, sealed] of Object.entries(entries)) {
-            const opened = await this.#open(stored, name, sealed);
-            if (opened === null || opened.place !== place)
-                throw new Error('an entry does not open under this key');
-            read[opened.entry] = opened.bytes;
-        }
-        return { entries: read, version };
-    }
-    async list() {
-        const places = [];
-        for (const stored of await this.#memory.list()) {
-            const { entries } = await this.#memory.read({ place: stored });
-            const [first] = Object.entries(entries);
-            const opened = first === undefined ? null : await this.#open(stored, first[0], first[1]);
-            if (opened !== null)
-                places.push(opened.place);
-        }
-        return places;
-    }
-    async write({ writes, expect }) {
-        const sealed = {};
-        const stored = new Map();
-        for (const place of new Set([...Object.keys(writes), ...Object.keys(expect)]))
-            stored.set(place, await this.#place(place));
-        for (const [place, entries] of Object.entries(writes)) {
-            const at = stored.get(place);
-            sealed[at] = {};
-            for (const [entry, bytes] of Object.entries(entries)) {
-                const name = await this.#entry(place, entry);
-                if (bytes === null) {
-                    sealed[at][name] = null;
-                    continue;
-                }
-                const header = this.#tools.utf8(this.#tools.canonical([place, entry]));
-                const plain = new Uint8Array(4 + header.length + bytes.length);
-                new DataView(plain.buffer).setUint32(0, header.length);
-                plain.set(header, 4);
-                plain.set(bytes, 4 + header.length);
-                const nonce = this.#crypto.random(NONCE);
-                sealed[at][name] = new Uint8Array([...nonce, ...(await this.#crypto.seal(this.#key, nonce, plain, this.#tools.utf8(`${at}\n${name}`)))]);
-            }
-        }
-        const landed = await this.#memory.write({ writes: sealed, expect: Object.fromEntries(Object.entries(expect).map(([place, version]) => [stored.get(place), version])) });
-        if (landed === null)
-            return null;
-        return Object.fromEntries(Object.keys(writes).map((place) => [place, landed[stored.get(place)] ?? null]));
-    }
-}

package/dist/house/crossing.d.ts

@@ -1,50 +0,0 @@
-import type { Tools } from '../foundation.ts';
-type Node = Readonly<Record<string, unknown>>;
-/** Where a handle points, and who may pass it on. */
-export interface Pointed {
-    readonly being: string;
-    readonly occupant: string;
-    readonly holder: string;
-    /** How long each invitation minted from it may wait unspent, in milliseconds. */
-    readonly expires?: number;
-}
-/** A reference to an occupant: one of her own, or one her steward minted on another being. It is no value. */
-export declare class HandleRef {
-    readonly id: string;
-    constructor(occupant: string);
-}
-/** An invitation carried unopened. It is no value. */
-export declare class Carried {
-    readonly invitation = true;
-    constructor();
-    toJSON(): never;
-}
-/**
- * One house's marks on the objects it hands its beings: where each handle
- * points, and the bytes of each invitation carried. An object another
- * house marked is no handle and no invitation here.
- */
-export declare class Marks {
-    #private;
-    handle(being: string, occupant: string, holder?: string, expires?: number): HandleRef;
-    carried(hex: string): Carried;
-    /** Where a handle points, where it is one of this house's. */
-    handleOf(value: unknown): Pointed | undefined;
-    /** An invitation's bytes, where it is one this house carries. */
-    hexOf(value: unknown): string | undefined;
-}
-/** A failure of a crossing, with the message the caller reads. */
-export declare class Crossing extends Error {
-}
-/**
- * Her value made wire JSON. `mint` turns a handle she holds into the hex its
- * receiver can call. `owner` is her id: a handle she does not hold is refused.
- * A handle under `s.invitation` leaves as an invitation, as one carried does.
- * An invitation carried under `s.handle` leaves as itself, for its receiver
- * to take. `redeem` turns a carried invitation this house minted into what
- * its reader calls, where the reader is a faculty: a token for its occupant.
- */
-export declare const outward: (tools: Tools, marks: Marks, schema: Node | undefined, value: unknown, owner: string, mint: (handle: Pointed) => Promise<string>, redeem?: (hex: string) => Promise<string | undefined>) => Promise<unknown>;
-/** Wire JSON made her value. `accept` turns an invitation's hex into a standing id. */
-export declare const inward: (tools: Tools, marks: Marks, schema: Node | undefined, value: unknown, accept: (hex: string) => Promise<string>) => Promise<unknown>;
-export {};

package/dist/house/crossing.js

@@ -1,153 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// What crosses between a being and the wire. A handle, an invitation
-// carried unopened and bytes are objects in her hands and hex on the wire.
-// The schema says where each stands.
-import { HANDLE_MEDIA, INVITATION_MEDIA } from '../being/schema.js';
-/** A reference to an occupant: one of her own, or one her steward minted on another being. It is no value. */
-export class HandleRef {
-    id;
-    constructor(occupant) {
-        this.id = occupant;
-        Object.freeze(this);
-    }
-}
-/** An invitation carried unopened. It is no value. */
-export class Carried {
-    invitation = true;
-    constructor() {
-        Object.freeze(this);
-    }
-    toJSON() {
-        throw new Crossing('an invitation carried unopened is no value');
-    }
-}
-/**
- * One house's marks on the objects it hands its beings: where each handle
- * points, and the bytes of each invitation carried. An object another
- * house marked is no handle and no invitation here.
- */
-export class Marks {
-    #minted = new WeakMap();
-    #carried = new WeakMap();
-    handle(being, occupant, holder = being, expires) {
-        const handle = new HandleRef(occupant);
-        this.#minted.set(handle, { being, occupant, holder, ...(expires === undefined ? {} : { expires }) });
-        return handle;
-    }
-    carried(hex) {
-        const invitation = new Carried();
-        this.#carried.set(invitation, hex);
-        return invitation;
-    }
-    /** Where a handle points, where it is one of this house's. */
-    handleOf(value) {
-        return typeof value === 'object' && value !== null ? this.#minted.get(value) : undefined;
-    }
-    /** An invitation's bytes, where it is one this house carries. */
-    hexOf(value) {
-        return typeof value === 'object' && value !== null ? this.#carried.get(value) : undefined;
-    }
-}
-/** A failure of a crossing, with the message the caller reads. */
-export class Crossing extends Error {
-}
-const branchFits = (tools, branch, value) => tools.check(branch, value) === null;
-/**
- * Her value made wire JSON. `mint` turns a handle she holds into the hex its
- * receiver can call. `owner` is her id: a handle she does not hold is refused.
- * A handle under `s.invitation` leaves as an invitation, as one carried does.
- * An invitation carried under `s.handle` leaves as itself, for its receiver
- * to take. `redeem` turns a carried invitation this house minted into what
- * its reader calls, where the reader is a faculty: a token for its occupant.
- */
-export const outward = async (tools, marks, schema, value, owner, mint, redeem = () => Promise.resolve(undefined)) => {
-    const held = (at) => {
-        const handle = marks.handleOf(at);
-        return handle !== undefined && handle.holder === owner ? handle : undefined;
-    };
-    const walk = async (node, at) => {
-        if (node === undefined)
-            return at;
-        if (node.contentMediaType === HANDLE_MEDIA) {
-            const handle = held(at);
-            if (handle !== undefined)
-                return mint(handle);
-            // An invitation carried unopened is handed on, and its receiver takes it.
-            const hex = marks.hexOf(at);
-            if (hex === undefined)
-                throw new Crossing('a handle is owed where a value stands');
-            return (await redeem(hex)) ?? hex;
-        }
-        if (node.contentMediaType === INVITATION_MEDIA) {
-            const handle = held(at);
-            if (handle !== undefined)
-                return mint(handle);
-            const hex = marks.hexOf(at);
-            if (hex === undefined)
-                throw new Crossing('an invitation is owed where a value stands');
-            return (await redeem(hex)) ?? hex;
-        }
-        if (node.contentEncoding === 'base16' && at instanceof Uint8Array)
-            return tools.hex(at);
-        if (Array.isArray(node.anyOf)) {
-            for (const branch of node.anyOf) {
-                try {
-                    const out = await walk(branch, at);
-                    if (branchFits(tools, branch, out))
-                        return out;
-                }
-                catch (error) {
-                    if (!(error instanceof Crossing))
-                        throw error;
-                }
-            }
-            return at;
-        }
-        if (Array.isArray(at) && node.items !== undefined)
-            return Promise.all(at.map((item) => walk(node.items, item)));
-        if (typeof at === 'object' && at !== null && !Array.isArray(at) && !(at instanceof Uint8Array) && node.properties !== undefined) {
-            const properties = node.properties;
-            const out = {};
-            for (const [key, field] of Object.entries(at)) {
-                if (field === undefined)
-                    continue;
-                out[key] = await walk(Object.hasOwn(properties, key) ? properties[key] : undefined, field);
-            }
-            return out;
-        }
-        return at;
-    };
-    const out = await walk(schema, value);
-    const why = schema === undefined ? null : tools.check(schema, out);
-    if (why !== null)
-        throw new Crossing(why);
-    return out;
-};
-/** Wire JSON made her value. `accept` turns an invitation's hex into a standing id. */
-export const inward = async (tools, marks, schema, value, accept) => {
-    const walk = async (node, at) => {
-        if (node === undefined)
-            return at;
-        if (node.contentMediaType === HANDLE_MEDIA)
-            return accept(at);
-        if (node.contentMediaType === INVITATION_MEDIA)
-            return marks.carried(at);
-        if (node.contentEncoding === 'base16')
-            return tools.bytes(at);
-        if (Array.isArray(node.anyOf)) {
-            const branch = node.anyOf.find((option) => branchFits(tools, option, at));
-            return walk(branch, at);
-        }
-        if (Array.isArray(at) && node.items !== undefined)
-            return Promise.all(at.map((item) => walk(node.items, item)));
-        if (typeof at === 'object' && at !== null && !Array.isArray(at) && node.properties !== undefined) {
-            const properties = node.properties;
-            const out = {};
-            for (const [key, field] of Object.entries(at))
-                out[key] = await walk(Object.hasOwn(properties, key) ? properties[key] : undefined, field);
-            return out;
-        }
-        return at;
-    };
-    return walk(schema, value);
-};

package/dist/house/house.d.ts

@@ -1,88 +0,0 @@
-import type { Json } from '../being/being.ts';
-import type { Carry, Classes, Clock, Crypto, Keys, Memory, Tools } from '../foundation.ts';
-import { type Answer } from './rows-shape.ts';
-export type { Answer } from './rows-shape.ts';
-/** The seven references a house calls. */
-export interface Foundation {
-    readonly keys: Keys;
-    readonly memory: Memory;
-    readonly classes: Classes;
-    readonly carry: Carry;
-    readonly clock: Clock;
-    readonly crypto: Crypto;
-    readonly tools: Tools;
-}
-/** A faculty the ground offers to beings. */
-export interface Offer {
-    readonly blueprint: unknown;
-    readonly object: object;
-    readonly kinds?: readonly string[];
-    /** How long the faculty remembers a call id, in milliseconds. */
-    readonly window?: number;
-    /** Told once the house opens, with the house's context, so its tokens answer before any being calls it. */
-    opened?(context: OpenedContext): void | Promise<void>;
-}
-/** What a faculty is handed when a house that offers it opens: the house's ward, and its tokens called as a method's context calls them. */
-export interface OpenedContext {
-    readonly ward: string;
-    readonly call: FacultyContext['call'];
-    readonly describe: FacultyContext['describe'];
-}
-/** What a faculty's method receives beside its args. */
-export interface FacultyContext {
-    readonly id: string;
-    /**
-     * A token it was handed, asked. A handle's token asks its one ask. An
-     * occupant's token asks the `method` named, as that occupant, and
-     * `after` makes a `readOnly` ask a watch. `home` carries the answer's
-     * handles home: they leave as invitation bytes, which a house takes,
-     * in place of tokens.
-     */
-    call(options: {
-        token: string;
-        method?: string;
-        args?: Json;
-        id: string;
-        after?: Answer;
-        home?: boolean;
-    }): Promise<Answer>;
-    /** What the occupant behind a token may ask now, as her describe shows it. */
-    describe(options: {
-        token: string;
-    }): Promise<{
-        describe: Json;
-    } | {
-        error: {
-            message: string;
-        };
-    }>;
-}
-/** What `House.open` gives. */
-export interface Opened {
-    readonly ward: string;
-    door(box: Uint8Array): Promise<Uint8Array | null>;
-    /**
-     * The hand: a being asked by `id` as `root`, the steward where no id is
-     * named. `after` is the answer the caller holds, which makes a `readOnly`
-     * ask a watch. `cells` reads her cells and asks nothing, which no other
-     * way into the house can. `call` is the ask's call id: asked again, it
-     * answers what the first answered and runs nothing twice.
-     */
-    ask(request: {
-        id?: string;
-        method?: string;
-        args?: Json;
-        after?: Answer;
-        cells?: true;
-        call?: string;
-    }): Promise<Answer | {
-        readonly describe: Json;
-    }>;
-}
-/** What a ground may set on a house beside its foundation and offers. */
-export interface Options {
-    /** The longest any ask here may take, in milliseconds. Each entry's own wait stands under it. */
-    readonly wait?: number;
-}
-/** A house opened on its foundation and its offers: its ward, its door and its hand, and nothing more. */
-export declare const openHouse: (foundation: Foundation, offers: readonly Offer[], options?: Options) => Promise<Opened>;