nervur 0.23.0 → 0.24.0

package/dist/house/rows-shape.d.ts

@@ -1,110 +0,0 @@
-import type { Json, Notes } from '../being/being.ts';
-import type { Occupant as QuoOccupant, Standing as QuoStanding } from '../quo/index.ts';
-/** A JSON value copied, as every row and cell is JSON. */
-export declare const copy: <T>(value: T) => T;
-export type Answer = {
-    readonly result: Json;
-} | {
-    readonly error: {
-        readonly message: string;
-    };
-};
-/**
- * The ward's own place: the bound, and the index of its beings. Only the
- * steward writes it, so no other being's write waits on it.
- */
-export interface WardRow {
-    bound: string;
-    beings: Record<string, {
-        kind: string;
-    }>;
-}
-/**
- * An heir's place, or a token's, one a place: whose occupant it reaches. A
- * mint writes a place of its own, so no two beings' mints meet.
- */
-export interface OwnerRow {
-    being: string;
-    occupant: string;
-    /** A token's: the blueprint of the faculty it was handed to, which alone calls it. */
-    faculty?: string;
-}
-export interface OccupantRow {
-    notes: Notes;
-    steward: Notes;
-    /** A handle: the one ask it is admitted to. */
-    ask?: string;
-    bind?: Json;
-    once?: boolean;
-    /** The heirs minted for it, each the door's end of a relation. */
-    quo?: Record<string, QuoOccupant>;
-    /** The addresses each heir's holder last heard, in its invitation or in a reply. */
-    told?: Record<string, readonly string[]>;
-    /** Each heir still unspent that has a time, and the time after which it never binds. */
-    until?: Record<string, number>;
-    /** The tokens minted for it, which faculties call. */
-    tokens?: string[];
-}
-export interface StandingRow {
-    notes: Notes;
-    steward: Notes;
-    /** A standing on a being of this house, bound at once. */
-    local?: {
-        being: string;
-        occupant: string;
-    };
-    /** A standing on a far ward. */
-    quo?: QuoStanding;
-    /** The address of hers that last answered: where each ask goes first. */
-    route?: string;
-    /** The domains that vouch for a far standing's ward, read once its take landed and again when it moves. */
-    vouched?: string[];
-}
-/** Where an effect goes. */
-export type Target = {
-    need: string;
-} | {
-    standing: string;
-} | {
-    being: string;
-};
-export interface OutboxEntry {
-    id: string;
-    to: Target;
-    method: string;
-    args: Json;
-    reply?: string;
-    /** A watch: the digest of the answer she holds, and how long the far side may hold it. */
-    after?: string;
-    wait?: number;
-    queued: number;
-    deadline: number;
-    next: number;
-    tries: number;
-}
-export interface DeadLetter {
-    ask: string;
-    args: Json;
-    at: number;
-    why: string;
-}
-export interface BeingRow {
-    kind: string;
-    cells: Record<string, Json>;
-    /** The args of her `born`, until it has run. */
-    born?: Json;
-    occupants: Record<string, OccupantRow>;
-    standings: Record<string, StandingRow>;
-    outbox: OutboxEntry[];
-    alarms: Record<string, {
-        at: number;
-        ask: string;
-        args: Json;
-    }>;
-    dead: DeadLetter[];
-    calls: Record<string, {
-        answer: Answer;
-        at: number;
-    }>;
-}
-export declare const emptyRow: (kind: string, cells: Record<string, Json>) => BeingRow;

package/dist/house/rows-shape.js

@@ -1,12 +0,0 @@
-/** A JSON value copied, as every row and cell is JSON. */
-export const copy = (value) => (value === undefined ? value : JSON.parse(JSON.stringify(value)));
-export const emptyRow = (kind, cells) => ({
-    kind,
-    cells,
-    occupants: {},
-    standings: {},
-    outbox: [],
-    alarms: {},
-    dead: [],
-    calls: {},
-});

package/dist/house/rows.d.ts

@@ -1,27 +0,0 @@
-import type { Crypto, Keys, Memory, Tools } from '../foundation.ts';
-/** A transaction's view: rows read once, changed as drafts, written together. */
-export interface Draft {
-    get<T>(place: string): Promise<T | null>;
-    set(place: string, row: unknown): void;
-}
-export declare class Rows {
-    #private;
-    private constructor();
-    static open(memory: Memory, keys: Keys, crypto: Crypto, tools: Tools): Promise<Rows>;
-    /** The place a name is kept at: a digest that says nothing of the name. */
-    place(name: string): Promise<string>;
-    /** A row as it stands, or `null`. */
-    get<T>(place: string): Promise<T | null>;
-    /** What is told each row as it lands: its place, and the row, or `null` where it went. */
-    whenLanded(told: (place: string, row: unknown) => void): void;
-    /** Every place memory lists. */
-    list(): Promise<readonly string[]>;
-    /**
-     * One transaction. Its change runs on drafts of the rows it reads, and it
-     * lands holding those rows alone, so writes on other rows land beside it.
-     * Where another write of this house landed on a row it read, its change
-     * runs again on the rows as they stand. `false` where memory refused the
-     * write or failed; the rows it read are read again next time.
-     */
-    transact(change: (draft: Draft) => Promise<void> | void): Promise<boolean>;
-}

package/dist/house/rows.js

@@ -1,185 +0,0 @@
-import { copy } from './rows-shape.js';
-const ENTRY = 'row';
-// The runs a change gets where other writes keep moving the rows it read, before it counts as refused.
-const RUNS = 64;
-export class Rows {
-    #memory;
-    #crypto;
-    #tools;
-    #names;
-    #key;
-    #held = new Map();
-    #placeNames = new Map();
-    /** The last write holding each row, which the next one to hold it waits for. */
-    #holds = new Map();
-    // How many times each row's cache has moved, so a read overtaken by a write never lands behind it.
-    #moves = new Map();
-    #landed;
-    constructor(memory, crypto, tools, names, key) {
-        this.#memory = memory;
-        this.#crypto = crypto;
-        this.#tools = tools;
-        this.#names = names;
-        this.#key = key;
-    }
-    static async open(memory, keys, crypto, tools) {
-        return new Rows(memory, crypto, tools, await keys.derive('place-names', 32), await keys.derive('rows', 32));
-    }
-    /** The place a name is kept at: a digest that says nothing of the name. */
-    async place(name) {
-        let place = this.#placeNames.get(name);
-        if (place === undefined) {
-            const digest = await this.#crypto.sha256(new Uint8Array([...this.#names, ...this.#tools.utf8(name)]));
-            place = this.#tools.hex(digest.subarray(0, 16));
-            this.#placeNames.set(name, place);
-        }
-        return place;
-    }
-    // A row's cache moved, by a write that landed or one refused: a read in flight across it is behind.
-    #moved(place) {
-        this.#moves.set(place, (this.#moves.get(place) ?? 0) + 1);
-    }
-    #forget(place) {
-        this.#moved(place);
-        this.#held.delete(place);
-    }
-    async #read(place) {
-        for (;;) {
-            const cached = this.#held.get(place);
-            if (cached !== undefined)
-                return cached;
-            const move = this.#moves.get(place) ?? 0;
-            const { entries, version } = await this.#memory.read({ place });
-            const sealed = entries[ENTRY];
-            let held = { row: null, text: null, version };
-            if (sealed !== undefined) {
-                const opened = await this.#crypto.open(this.#key, sealed.subarray(0, 12), sealed.subarray(12), this.#tools.utf8(place));
-                const text = opened === null ? null : this.#tools.text(opened);
-                if (text === null)
-                    throw new Error('a row does not open under these keys');
-                held = { row: JSON.parse(text), text, version };
-            }
-            // A write that moved the row while this read was in flight wins, and this read looks again.
-            if ((this.#moves.get(place) ?? 0) !== move)
-                continue;
-            this.#held.set(place, held);
-            return held;
-        }
-    }
-    /** A row as it stands, or `null`. */
-    async get(place) {
-        return copy((await this.#read(place)).row);
-    }
-    /** What is told each row as it lands: its place, and the row, or `null` where it went. */
-    whenLanded(told) {
-        this.#landed = told;
-    }
-    /** Every place memory lists. */
-    list() {
-        return this.#memory.list();
-    }
-    /**
-     * One transaction. Its change runs on drafts of the rows it reads, and it
-     * lands holding those rows alone, so writes on other rows land beside it.
-     * Where another write of this house landed on a row it read, its change
-     * runs again on the rows as they stand. `false` where memory refused the
-     * write or failed; the rows it read are read again next time.
-     */
-    async transact(change) {
-        for (let run = 0; run < RUNS; run++) {
-            const landed = await this.#transact(change);
-            if (landed !== 'moved')
-                return landed;
-        }
-        return false;
-    }
-    // The rows named, each held in the order of its place, so two writes never wait on each other.
-    async #hold(places) {
-        const releases = [];
-        for (const place of [...places].sort()) {
-            const before = this.#holds.get(place) ?? Promise.resolve();
-            let release;
-            const mine = new Promise((resolve) => (release = resolve));
-            const tail = before.then(() => mine);
-            this.#holds.set(place, tail);
-            await before;
-            releases.push(() => {
-                release();
-                if (this.#holds.get(place) === tail)
-                    this.#holds.delete(place);
-            });
-        }
-        return () => {
-            for (const release of releases)
-                release();
-        };
-    }
-    async #transact(change) {
-        const read = new Map();
-        const drafts = new Map();
-        const draft = {
-            get: async (place) => {
-                if (drafts.has(place))
-                    return drafts.get(place);
-                const held = await this.#read(place);
-                read.set(place, held);
-                const drafted = copy(held.row);
-                drafts.set(place, drafted);
-                return drafted;
-            },
-            set: (place, row) => {
-                drafts.set(place, row);
-            },
-        };
-        await change(draft);
-        const release = await this.#hold([...new Set([...read.keys(), ...drafts.keys()])]);
-        try {
-            // A row this change read moved since: it runs again on the row as it stands.
-            for (const [place, held] of read)
-                if (this.#held.get(place) !== held)
-                    return 'moved';
-            const writes = {};
-            // Every row read is expected as it was read, so memory refuses a write on rows another writer moved.
-            const expect = Object.fromEntries([...read].map(([place, held]) => [place, held.version]));
-            const landed = new Map();
-            for (const [place, row] of drafts) {
-                const before = read.get(place) ?? (await this.#read(place));
-                const text = row === null ? null : this.#tools.canonical(row);
-                if (text === before.text)
-                    continue;
-                expect[place] = before.version;
-                if (text === null)
-                    writes[place] = { [ENTRY]: null };
-                else {
-                    const nonce = this.#crypto.random(12);
-                    const sealed = await this.#crypto.seal(this.#key, nonce, this.#tools.utf8(text), this.#tools.utf8(place));
-                    writes[place] = { [ENTRY]: new Uint8Array([...nonce, ...sealed]) };
-                }
-                landed.set(place, { row: text === null ? null : JSON.parse(text), text, version: null });
-            }
-            if (Object.keys(writes).length === 0)
-                return true;
-            let versions = null;
-            try {
-                versions = await this.#memory.write({ writes, expect });
-            }
-            catch {
-                versions = null;
-            }
-            if (versions === null) {
-                for (const place of Object.keys(expect))
-                    this.#forget(place);
-                return false;
-            }
-            for (const [place, held] of landed) {
-                this.#moved(place);
-                this.#held.set(place, { ...held, version: versions[place] ?? null });
-                this.#landed?.(place, held.row);
-            }
-            return true;
-        }
-        finally {
-            release();
-        }
-    }
-}

package/dist/index.d.ts

@@ -1,33 +0,0 @@
-import type { Carry, Classes, Clock, Crypto, Keys, Memory, Tools } from './foundation.ts';
-import { type Offer, type Opened } from './house/house.ts';
-export type { Carry, Classes, Clock, Crypto, Keys, Memory, Sent, Tools } from './foundation.ts';
-export { JoinedCarry } from './bodies/joined-carry.ts';
-export { WebCarry, type Handler } from './bodies/web-carry.ts';
-export { vouchesOf } from './bodies/vouch.ts';
-export type { FacultyContext, Offer, Opened } from './house/house.ts';
-export { Ground, type Body, type Faculty, type FacultyEntry, type ForHouse, type Hooked, type Registry, type Serves, type Takes, type Unlock, type Up } from './ground/ground.ts';
-export { DockPilot } from './ground/dock.ts';
-export { ClassList } from './bodies/class-list.ts';
-export { NobleCrypto } from './bodies/noble-crypto.ts';
-export { SeedKeys } from './bodies/seed-keys.ts';
-export { StrictTools } from './bodies/strict-tools.ts';
-export { WebClock } from './bodies/web-clock.ts';
-/** The house: opened on its foundation and its offers, and the ground's bound on every ask. */
-export declare const House: Readonly<{
-    /**
-     * `clock`, `crypto` and `tools` take the library's defaults where the
-     * ground hands none. `wait` bounds every ask here, where the ground can
-     * hold less than an entry asks.
-     */
-    open(foundation: {
-        keys: Keys;
-        memory: Memory;
-        classes: Classes;
-        carry: Carry;
-        clock?: Clock;
-        crypto?: Crypto;
-        tools?: Tools;
-    }, offers?: readonly Offer[], options?: {
-        readonly wait?: number;
-    }): Promise<Opened>;
-}>;

package/dist/index.js

@@ -1,29 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// `nervur`: what a ground's author imports on any engine. The house, the
-// blueprints of its foundation and the ground's unlock, and the bodies
-// that fill them anywhere.
-import { NobleCrypto } from './bodies/noble-crypto.js';
-import { StrictTools } from './bodies/strict-tools.js';
-import { WebClock } from './bodies/web-clock.js';
-import { openHouse } from './house/house.js';
-export { JoinedCarry } from './bodies/joined-carry.js';
-export { WebCarry } from './bodies/web-carry.js';
-export { vouchesOf } from './bodies/vouch.js';
-export { Ground } from './ground/ground.js';
-export { DockPilot } from './ground/dock.js';
-export { ClassList } from './bodies/class-list.js';
-export { NobleCrypto } from './bodies/noble-crypto.js';
-export { SeedKeys } from './bodies/seed-keys.js';
-export { StrictTools } from './bodies/strict-tools.js';
-export { WebClock } from './bodies/web-clock.js';
-/** The house: opened on its foundation and its offers, and the ground's bound on every ask. */
-export const House = Object.freeze({
-    /**
-     * `clock`, `crypto` and `tools` take the library's defaults where the
-     * ground hands none. `wait` bounds every ask here, where the ground can
-     * hold less than an entry asks.
-     */
-    open(foundation, offers = [], options = {}) {
-        return openHouse({ ...foundation, clock: foundation.clock ?? new WebClock(), crypto: foundation.crypto ?? new NobleCrypto(), tools: foundation.tools ?? new StrictTools() }, offers, options);
-    },
-});

package/dist/node/bridge.d.ts

@@ -1,20 +0,0 @@
-import type { Memory } from '../foundation.ts';
-import type { Body } from '../ground/ground.ts';
-export interface BridgeOptions {
-    /** The program, by path or by a name the ground's PATH finds. */
-    readonly command: string;
-    readonly args?: readonly string[];
-    /** Everything the program's environment holds. The ground's own is never passed. */
-    readonly env?: Readonly<Record<string, string>>;
-    readonly cwd?: string;
-    /** The faculty's own memory, which the program reads and writes by its memory lines. */
-    readonly memory?: Memory;
-    /** How long its `describe` may take, in milliseconds. */
-    readonly wait?: number;
-}
-/**
- * A program in any language, raised as a body: its blueprint and its
- * window from its own `describe`, and an object whose every method is a
- * line to it. It answers once the program has described itself.
- */
-export declare const bridge: (options: BridgeOptions) => Promise<Body>;