nervur 0.22.0 → 0.22.2-3

package/dist/app/native.js

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0
+// The two native bodies of a phone's ground, over what the shell hands in.
+// The shell's secret store is the iOS Keychain or the Android Keystore, and
+// its store is a native file or database the operating system never
+// evicts. The library holds the contracts' logic here; a shell holds only
+// the two small interfaces below, in its own native code.
+import { SeedKeys } from '../bodies/seed-keys.js';
+const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const SEED = /^[0-9a-f]{64}$/;
+const hex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+const bytes = (text) => new Uint8Array(text.match(/../g)?.map((pair) => parseInt(pair, 16)) ?? []);
+/** One seed for each house in the platform's secret store, drawn on first use. */
+export class NativeCustody {
+    #secrets;
+    #turn = Promise.resolve();
+    constructor(secrets) {
+        this.#secrets = secrets;
+    }
+    keys({ house }) {
+        if (!NAME.test(house))
+            return Promise.reject(new TypeError(`no house is named ${house}`));
+        // One seed is drawn at a time, so two first uses of a house never draw two.
+        const turn = this.#turn.then(async () => {
+            const name = `nervur.seed.${house}`;
+            let seed = await this.#secrets.get(name);
+            if (seed === null) {
+                seed = hex(crypto.getRandomValues(new Uint8Array(32)));
+                await this.#secrets.set(name, seed);
+            }
+            if (!SEED.test(seed))
+                throw new Error(`the seed of ${house} is not sixty-four hex digits`);
+            return new SeedKeys(seed);
+        });
+        this.#turn = turn.catch(() => undefined);
+        return turn;
+    }
+}
+/**
+ * Memory over a native store, one memory for each name. Each place is one
+ * key, its entries as hex beside its version. Versions come from one
+ * counter for the memory, so a place removed and written again never
+ * shows a version it showed before. A write reads every place it names
+ * and swaps them all against what it read.
+ */
+export class NativeMemory {
+    #store;
+    #prefix;
+    constructor(store, name) {
+        if (!NAME.test(name))
+            throw new TypeError(`no memory is named ${name}`);
+        this.#store = store;
+        this.#prefix = `nervur/${name}/`;
+    }
+    #key(place) {
+        return `${this.#prefix}p/${place}`;
+    }
+    async read({ place }) {
+        const text = await this.#store.get(this.#key(place));
+        if (text === null)
+            return { entries: {}, version: null };
+        const held = JSON.parse(text);
+        return { entries: Object.fromEntries(Object.entries(held.e).map(([name, value]) => [name, bytes(value)])), version: String(held.v) };
+    }
+    async list() {
+        const places = `${this.#prefix}p/`;
+        return (await this.#store.keys(places)).map((key) => key.slice(places.length));
+    }
+    async write({ writes, expect, }) {
+        const places = [...new Set([...Object.keys(writes), ...Object.keys(expect)])];
+        const count = `${this.#prefix}count`;
+        const held = { [count]: await this.#store.get(count) };
+        for (const place of places)
+            held[this.#key(place)] = await this.#store.get(this.#key(place));
+        for (const place of places) {
+            const text = held[this.#key(place)];
+            const version = text === null ? null : String(JSON.parse(text).v);
+            if (!(place in expect) || expect[place] !== version)
+                return null;
+        }
+        let next = held[count] === null ? 0 : Number(held[count]);
+        const landing = {};
+        const versions = {};
+        for (const [place, entries] of Object.entries(writes)) {
+            const text = held[this.#key(place)];
+            const kept = { ...(text === null ? {} : JSON.parse(text).e) };
+            for (const [name, value] of Object.entries(entries)) {
+                if (value === null)
+                    delete kept[name];
+                else
+                    kept[name] = hex(value);
+            }
+            next += 1;
+            const empty = Object.keys(kept).length === 0;
+            landing[this.#key(place)] = empty ? null : JSON.stringify({ v: next, e: kept });
+            versions[place] = empty ? null : String(next);
+        }
+        landing[count] = String(next);
+        // What another writer moved since the read refuses the swap, as it would the versions.
+        return (await this.#store.swap(landing, held)) ? versions : null;
+    }
+}

package/dist/being/being.d.ts

@@ -0,0 +1,229 @@
+import type { MethodSpec, Need, BLUEPRINT } from './need.ts';
+import type { Handle, Inbound, Infer, Invitation, Outbound } from './schema.ts';
+/** A JSON value, as cells and notes hold. */
+export type Json = null | boolean | number | string | readonly Json[] | {
+    readonly [key: string]: Json;
+};
+/** What a call outward carries: JSON, bytes, and the handles and invitations the callee's schema places. */
+export type Passed = Json | Uint8Array | Handle | Invitation | readonly Passed[] | {
+    readonly [key: string]: Passed;
+};
+/** Notes on a relation. */
+export type Notes = Readonly<Record<string, Json>>;
+/** Where the house placed her. */
+export type Position = 'steward' | 'public' | 'normal';
+/** Who asks now. */
+export interface Asker {
+    readonly id: string;
+    readonly notes: Notes;
+    readonly steward: Notes;
+    readonly signer?: Uint8Array;
+}
+/** What a role and her state read of her. */
+export interface Me<C> {
+    readonly id: string;
+    readonly position: Position;
+    readonly cells: Readonly<C>;
+}
+type Names = string | readonly string[];
+/** One example of an ask, run by the bench and nowhere else. */
+export interface Example {
+    readonly description?: string;
+    readonly cells?: Json;
+    readonly role?: string;
+    readonly args?: Json;
+    readonly fakes?: Json;
+    readonly gives?: Json;
+}
+/** An ask's entry: the method's gate. */
+export interface Entry extends MethodSpec {
+    readonly in?: Names;
+    readonly for?: Names;
+    readonly to?: Names;
+    readonly examples?: readonly Example[];
+}
+/** What a class declares. */
+export interface Declaration<C = Record<string, Json>, N = Record<string, Need>, A = Record<string, Entry>> {
+    readonly kind: string;
+    readonly description?: string;
+    readonly cells?: C;
+    readonly needs?: N;
+    readonly roles?: Readonly<Record<string, (asker: Asker, me: Me<C>) => boolean>>;
+    readonly state?: (me: Me<C>) => string;
+    readonly asks: A;
+    /** Markup as text over her asks, which a screen renders. */
+    readonly view?: string;
+}
+/** A relation, with her notes and her steward's. */
+export interface Relation {
+    readonly id: string;
+    readonly notes: Notes;
+    readonly steward: Notes;
+}
+type Resolved<S> = S extends {
+    readonly result: infer R;
+} ? Inbound<Infer<R>> : null;
+type Sent<S> = S extends {
+    readonly args: infer A;
+} ? Outbound<Infer<A>> : Record<string, never>;
+type IsAwaited<S> = S extends {
+    readonly hints: {
+        readonly idempotent: true;
+    };
+} ? true : S extends {
+    readonly hints: {
+        readonly readOnly: true;
+    };
+} ? true : false;
+/** How she calls one method: awaited, or an effect answered through `reply`. */
+type Given<S, O extends unknown[]> = {} extends Sent<S> ? [args?: Sent<S>, ...O] : [args: Sent<S>, ...O];
+type IsReadOnly<S> = S extends {
+    readonly hints: {
+        readonly readOnly: true;
+    };
+} ? true : false;
+export type Call<S, R extends string> = IsReadOnly<S> extends true ? (...given: Given<S, [options?: {
+    after?: Resolved<S>;
+}]>) => Promise<Resolved<S>> : IsAwaited<S> extends true ? (...given: Given<S, []>) => Promise<Resolved<S>> : (...given: Given<S, [options?: {
+    reply?: R;
+}]>) => void;
+/** The frozen face of a need: its methods and nothing else. */
+export type Face<X, R extends string = string> = {
+    readonly [K in Exclude<keyof X, typeof BLUEPRINT>]: Call<X[K], R>;
+};
+/** A standing asked with no need matched, such as her steward. */
+export type Untyped = Readonly<Record<string, (args?: Passed, options?: {
+    reply?: string;
+}) => Promise<unknown> | void>>;
+/** What `this.house` gives every being. */
+export interface HouseReach<R extends string = string> {
+    now(): number;
+    random(options: {
+        length: number;
+    }): Uint8Array;
+    alarm(options: {
+        at: number;
+        ask: R;
+        args?: Json;
+        key: string;
+    }): void;
+    cancelAlarm(options: {
+        key: string;
+    }): void;
+}
+/** Her standings. */
+export interface Standings {
+    list(): readonly Relation[];
+    note(id: string, notes: Notes): void;
+    drop(id: string): void;
+}
+/** Her occupants and handles. */
+export interface Occupants {
+    list(): readonly Relation[];
+    note(id: string, notes: Notes): void;
+    dismiss(id: string): void;
+}
+/** The steward's six powers. */
+export interface Powers {
+    /** A new occupant of another being, as a handle she may pass on. */
+    invite(options: {
+        id: string;
+        occupant: string;
+        notes?: Notes;
+        expires?: number;
+    }): Handle;
+    bear(options: {
+        kind: string;
+        id: string;
+        args?: Json;
+    }): void;
+    remove(options: {
+        id: string;
+    }): void;
+    /** Every being, her kind, whether she is absent, and the replies her table refused. */
+    list(): Promise<readonly {
+        id: string;
+        kind: string;
+        absent: boolean;
+        dead: readonly {
+            ask: string;
+            args: Json;
+            at: number;
+            why: string;
+        }[];
+    }[]>;
+    /** Her args may carry a handle she holds or an invitation she carries, as any call outward. */
+    ask(call: {
+        id: string;
+        method: string;
+        args?: Passed;
+    }, options?: {
+        reply?: string;
+    }): Promise<unknown> | void;
+    introduce(options: {
+        from: string;
+        to: string;
+        notes?: Notes;
+    }): void;
+}
+export declare const DECLARATION: unique symbol;
+declare const ASKS: unique symbol;
+/** The asks of a class, carried in its type alone. */
+export interface Typed<A> {
+    readonly [ASKS]?: A;
+}
+type AskOf<T, K> = T extends Typed<infer A> ? (K extends keyof A ? A[K] : never) : never;
+/** The args her method `K` receives. */
+export type Args<T, K extends string> = AskOf<T, K> extends {
+    readonly args: infer S;
+} ? Inbound<Infer<S>> : Record<string, never>;
+/** What her method `K` answers. */
+export type Result<T, K extends string> = AskOf<T, K> extends {
+    readonly result: infer S;
+} ? Outbound<Infer<S>> : void;
+/** What every being reaches. */
+export declare abstract class Being<C = Record<string, Json>, R extends string = string> {
+    readonly id: string;
+    readonly position: Position;
+    readonly asker: Asker;
+    cells: C;
+    readonly house: HouseReach<R>;
+    readonly standings: Standings;
+    readonly occupants: Occupants;
+    /** Her steward, asked as a standing, where she is not one. */
+    readonly steward?: Untyped;
+    /** The house's powers, where she is the steward. */
+    readonly powers?: Powers;
+    /** A standing matched to a need. */
+    held: <X extends Need>(id: string, need: X) => Face<X, R>;
+    /**
+     * A handle to one of her asks. Each invitation it leaves as is spent within
+     * `expires` milliseconds of leaving, or never binds.
+     */
+    handle: (ask: R, options?: {
+        bind?: Json;
+        notes?: Notes;
+        once?: boolean;
+        expires?: number;
+    }) => Handle;
+    /** A new occupant, as a handle, with `expires` as `handle` has it. */
+    invite: (id: string, options?: {
+        notes?: Notes;
+        expires?: number;
+    }) => Handle;
+    /** Throws an error the asker can act on. */
+    fail: (message: string) => never;
+    /** A class, declared by one object. */
+    static of<C extends Record<string, Json> = Record<string, never>, const N extends Record<string, Need> = Record<never, never>, const A extends Record<string, Entry> = Record<string, Entry>>(declaration: Declaration<C, N, A>): BeingClass<C, N, A>;
+}
+/** What `Being.of` gives: a class to extend. */
+export type BeingClass<C, N, A> = (abstract new () => Being<C, keyof A & string> & {
+    readonly [K in keyof N]: Face<N[K], keyof A & string>;
+} & Typed<A>) & {
+    readonly [DECLARATION]: Declaration<C, N, A>;
+};
+/** The members of `Being` a class may not name. */
+export declare const MEMBERS: ReadonlySet<string>;
+/** The declaration a class carries, or nothing where it is no class of `Being.of`. */
+export declare const declarationOf: (value: unknown) => Declaration | undefined;
+export {};

package/dist/being/being.js

@@ -0,0 +1,20 @@
+export const DECLARATION = Symbol('declaration');
+/** What every being reaches. */
+export class Being {
+    /** A class, declared by one object. */
+    static of(declaration) {
+        // A class of her own, so the house reads her declaration from it.
+        class Declared extends Being {
+            static [DECLARATION] = declaration;
+        }
+        return Declared;
+    }
+}
+/** The members of `Being` a class may not name. */
+export const MEMBERS = new Set(['id', 'position', 'asker', 'cells', 'house', 'standings', 'occupants', 'steward', 'powers', 'held', 'handle', 'invite', 'fail']);
+/** The declaration a class carries, or nothing where it is no class of `Being.of`. */
+export const declarationOf = (value) => {
+    if (typeof value !== 'function' || !(value.prototype instanceof Being))
+        return undefined;
+    return value[DECLARATION];
+};

package/dist/being/covers.d.ts

@@ -0,0 +1,9 @@
+import type { Blueprint } from './need.ts';
+/** Covered, or the first rule that fails, as a sentence. */
+export type Cover = {
+    readonly covered: true;
+} | {
+    readonly covered: false;
+    readonly why: string;
+};
+export declare const covers: (offer: Blueprint, want: Blueprint) => Cover;

package/dist/being/covers.js

@@ -0,0 +1,21 @@
+const requiredOf = (schema) => {
+    const required = schema.required;
+    return Array.isArray(required) ? required : [];
+};
+export const covers = (offer, want) => {
+    if (offer.name !== want.name)
+        return { covered: false, why: `the offer is ${offer.name}, and the need is ${want.name}` };
+    for (const [name, wanted] of Object.entries(want.methods)) {
+        const offered = offer.methods[name];
+        if (offered === undefined)
+            return { covered: false, why: `${want.name} offers no ${name}` };
+        const sent = new Set(requiredOf(wanted.args));
+        const extra = requiredOf(offered.args).find((key) => !sent.has(key));
+        if (extra !== undefined)
+            return { covered: false, why: `${want.name}.${name} requires ${extra}, which the need does not send` };
+        if (offered.hints.idempotent !== wanted.hints.idempotent) {
+            return { covered: false, why: `${want.name}.${name} is idempotent in one and not the other` };
+        }
+    }
+    return { covered: true };
+};

package/dist/being/index.d.ts

@@ -0,0 +1,3 @@
+export { Being, type Args, type Result } from './being.ts';
+export { need } from './need.ts';
+export { s } from './schema.ts';

package/dist/being/index.js

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur/being`: what a being's author imports, and nothing else.
+export { Being } from './being.js';
+export { need } from './need.js';
+export { s } from './schema.js';

package/dist/being/need.d.ts

@@ -0,0 +1,49 @@
+import { type Schema } from './schema.ts';
+/** The three hints an ask or a method may carry. */
+export interface Hints {
+    readonly readOnly?: boolean;
+    readonly idempotent?: boolean;
+    readonly destructive?: boolean;
+}
+/** A method as its author writes it, in a need or in an ask's entry. */
+export interface MethodSpec {
+    readonly args?: Schema;
+    readonly result?: Schema;
+    readonly hints?: Hints;
+    readonly description?: string;
+    /** How long an awaited caller waits for it, in milliseconds, within the bound. */
+    readonly wait?: number;
+}
+/** A method of a blueprint, every field settled. */
+export interface BlueprintMethod {
+    readonly args: Schema;
+    readonly result?: Schema;
+    readonly hints: Required<Hints>;
+    readonly description?: string;
+    readonly wait: number;
+}
+/** An awaited call's wait where none is named, and the bound no wait passes. */
+export declare const WAIT = 30000;
+export declare const WAIT_BOUND = 300000;
+/** The shape of what can be called: a name and its methods. */
+export interface Blueprint {
+    readonly name: string;
+    readonly methods: Readonly<Record<string, BlueprintMethod>>;
+}
+export declare const BLUEPRINT: unique symbol;
+/** A need: her methods by name, and the blueprint they make. */
+export type Need<M extends Record<string, MethodSpec> = Record<string, MethodSpec>> = {
+    readonly [K in keyof M]: M[K];
+} & {
+    readonly [BLUEPRINT]: Blueprint;
+};
+/** Whether a method is awaited: `readOnly` implies `idempotent`. */
+export declare const awaited: (hints: Hints | undefined) => boolean;
+/** Hints settled, `readOnly` carrying `idempotent` with it. */
+export declare const settled: (hints: Hints | undefined) => Required<Hints>;
+/** One method settled: the empty object where args are omitted. */
+export declare const method: (spec: MethodSpec) => BlueprintMethod;
+/** A blueprint at its minimum, under the name matching uses. */
+export declare const need: <const M extends Record<string, MethodSpec>>(name: string, methods: M) => Need<M>;
+/** The blueprint a need makes, or nothing where the value is no need. */
+export declare const blueprintOf: (value: unknown) => Blueprint | undefined;

package/dist/being/need.js

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: Apache-2.0
+// A need: a blueprint at its minimum, the shape of what she calls.
+import { s } from './schema.js';
+/** An awaited call's wait where none is named, and the bound no wait passes. */
+export const WAIT = 30_000;
+export const WAIT_BOUND = 300_000;
+export const BLUEPRINT = Symbol('blueprint');
+/** Whether a method is awaited: `readOnly` implies `idempotent`. */
+export const awaited = (hints) => hints?.idempotent === true || hints?.readOnly === true;
+/** Hints settled, `readOnly` carrying `idempotent` with it. */
+export const settled = (hints) => ({
+    readOnly: hints?.readOnly === true,
+    idempotent: awaited(hints),
+    destructive: hints?.destructive === true,
+});
+/** One method settled: the empty object where args are omitted. */
+export const method = (spec) => Object.freeze({
+    args: spec.args ?? s.object({}),
+    ...(spec.result === undefined ? {} : { result: spec.result }),
+    hints: Object.freeze(settled(spec.hints)),
+    ...(spec.description === undefined ? {} : { description: spec.description }),
+    wait: typeof spec.wait === 'number' ? Math.min(spec.wait, WAIT_BOUND) : WAIT,
+});
+/** A blueprint at its minimum, under the name matching uses. */
+export const need = (name, methods) => {
+    const blueprint = Object.freeze({
+        name,
+        methods: Object.freeze(Object.fromEntries(Object.entries(methods).map(([key, spec]) => [key, method(spec)]))),
+    });
+    return Object.freeze({ ...methods, [BLUEPRINT]: blueprint });
+};
+/** The blueprint a need makes, or nothing where the value is no need. */
+export const blueprintOf = (value) => typeof value === 'object' && value !== null && BLUEPRINT in value ? value[BLUEPRINT] : undefined;

package/dist/being/schema.d.ts

@@ -0,0 +1,100 @@
+declare const TYPE: unique symbol;
+/** A schema in the closed subset, typed by what it admits. */
+export type Schema<T = unknown> = {
+    readonly [key: string]: unknown;
+} & {
+    readonly [TYPE]?: T;
+};
+/** The type a schema admits. */
+export type Infer<S> = S extends {
+    readonly [TYPE]?: infer T;
+} ? T : never;
+/** A relation crossing: a handle on the way out, a standing id on the way in. */
+export interface HandleMark {
+    readonly handleMark: true;
+}
+/** An invitation carried unopened. It is an object and never a value. */
+export interface Invitation {
+    readonly invitation: true;
+}
+/** A reference to one of her asks, or to an occupant she minted. */
+export interface Handle {
+    readonly id: string;
+}
+type Mapped<T, H> = T extends HandleMark ? H : T extends Invitation ? // A handle under s.invitation leaves as an invitation too.
+Invitation | (H extends Handle ? Handle : never) : T extends Uint8Array ? T : T extends readonly (infer E)[] ? Mapped<E, H>[] : T extends object ? {
+    [K in keyof T]: Mapped<T[K], H>;
+} : T;
+/** What a method receives: a handle has arrived as a standing id. */
+export type Inbound<T> = Mapped<T, string>;
+/** What a call sends: a handle leaves as a handle, or as an invitation she carries, for its receiver to take. */
+export type Outbound<T> = Mapped<T, Handle | Invitation>;
+export declare const HANDLE_MEDIA = "application/vnd.nervur.handle";
+export declare const INVITATION_MEDIA = "application/vnd.nervur.invitation";
+/** The keywords the house checks, and no other. */
+export declare const KEYWORDS: ReadonlySet<string>;
+declare const OPTIONAL: unique symbol;
+type Optional<S extends Schema> = S & {
+    readonly [OPTIONAL]: true;
+};
+type Flat<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type Props = Record<string, Schema>;
+type OptionalKeys<P extends Props> = {
+    [K in keyof P]: P[K] extends {
+        readonly [OPTIONAL]: true;
+    } ? K : never;
+}[keyof P];
+type ObjectOf<P extends Props> = Flat<{
+    -readonly [K in Exclude<keyof P, OptionalKeys<P>>]: Infer<P[K]>;
+} & {
+    -readonly [K in OptionalKeys<P>]?: Infer<P[K]>;
+}>;
+/** A method of a need, as `s.reply` reads it. */
+export interface MethodRef<R = unknown> {
+    readonly args?: Schema;
+    readonly result?: Schema<R>;
+}
+/** The args of a reply: the method's result, or its error. */
+export type Reply<R> = {
+    result: R;
+    error?: undefined;
+} | {
+    error: {
+        message: string;
+    };
+    result?: undefined;
+};
+type Bounds = {
+    minimum?: number;
+    maximum?: number;
+};
+type Lengths = {
+    minLength?: number;
+    maxLength?: number;
+};
+type Scalar = string | number | boolean | null;
+export declare const s: Readonly<{
+    object: <P extends Props>(properties: P) => Schema<ObjectOf<P>>;
+    string: (lengths?: Lengths & {
+        pattern?: string;
+    }) => Schema<string>;
+    number: (bounds?: Bounds) => Schema<number>;
+    integer: (bounds?: Bounds) => Schema<number>;
+    boolean: () => Schema<boolean>;
+    array: <S extends Schema>(items: S) => Schema<Infer<S>[]>;
+    enum: <const V extends readonly Scalar[]>(values: V) => Schema<V[number]>;
+    const: <const V extends Scalar>(value: V) => Schema<V>;
+    bytes: (lengths?: Lengths) => Schema<Uint8Array>;
+    optional: <S extends Schema>(schema: S) => Optional<S>;
+    handle: () => Schema<HandleMark>;
+    invitation: () => Schema<Invitation>;
+    reply: <R>(method: MethodRef<R>) => Schema<Reply<unknown extends R ? null : R>>;
+}>;
+/**
+ * Every way a schema leaves the subset, each as a sentence naming where.
+ * The empty list is a schema the house checks.
+ */
+export declare const outside: (schema: unknown, at?: string) => string[];
+export {};