@quo-systems/quo 0.1.0 → 0.2.0

package/dist/being/being.d.ts

@@ -0,0 +1,22 @@
+import type { Asker, Blueprint, Cells, Invitation, JsonObject, Wanted, OccupantRecord, Occupants, Reply, Schema, Stance, Standings, Answer } from './types.ts';
+export type AskSpec = {
+    description?: string;
+    input?: Schema;
+    output?: Schema;
+    for?: (occupant: OccupantRecord | undefined, asker: Asker) => boolean;
+};
+export declare class Being {
+    static cells: JsonObject;
+    static asks: Record<string, AskSpec>;
+    readonly stance: Stance;
+    constructor(stance: Stance);
+    get cells(): Cells;
+    get standings(): Standings;
+    get occupants(): Occupants;
+    invite(id: string): Promise<Invitation | null>;
+    knock(invitation: Invitation, method?: string, args?: JsonObject, wanted?: Wanted): Promise<Answer>;
+    take(id: string, invitation: Invitation): Promise<string | null>;
+    occupant(asker: Asker): OccupantRecord | undefined;
+    describe(asker: Asker): Blueprint;
+    answer(asker: Asker, method?: string, args?: JsonObject): Promise<Reply>;
+}

package/dist/being/being.js

@@ -0,0 +1,78 @@
+// Names a subclass may not use for an ask, because they are the base's own.
+const RESERVED = new Set(['answer', 'describe', 'stance', 'cells', 'standings', 'occupants', 'occupant', 'invite', 'knock', 'take', 'constructor']);
+export class Being {
+    // Her cells' defaults. Merged in at birth, only where a key is missing, so
+    // a restart keeps what she wrote.
+    static cells = {};
+    // What she can be asked. Declaration order is blueprint order.
+    static asks = {};
+    stance;
+    constructor(stance) {
+        this.stance = stance;
+        const C = this.constructor;
+        for (const name of Object.keys(C.asks)) {
+            if (RESERVED.has(name))
+                throw new Error(`ask '${name}' is a reserved name`);
+            if (typeof this[name] !== 'function')
+                throw new Error(`ask '${name}' has no method`);
+        }
+        for (const [k, v] of Object.entries(C.cells))
+            if (!(k in stance.cells))
+                stance.cells[k] = structuredClone(v);
+    }
+    get cells() {
+        return this.stance.cells;
+    }
+    get standings() {
+        return this.stance.standings;
+    }
+    get occupants() {
+        return this.stance.occupants;
+    }
+    invite(id) {
+        return this.stance.occupants.invite(id);
+    }
+    knock(invitation, method, args, wanted) {
+        return this.stance.standings.knock(invitation, method, args, wanted);
+    }
+    take(id, invitation) {
+        return this.stance.standings.take(id, invitation);
+    }
+    // The occupant record for whoever is at the door. Undefined at a public being.
+    occupant(asker) {
+        return asker.id === undefined ? undefined : this.cells.occupants[asker.id];
+    }
+    // Her blueprint for this asker. Override to shape it by hand.
+    describe(asker) {
+        const C = this.constructor;
+        const rec = this.occupant(asker);
+        const asks = [];
+        for (const [name, spec] of Object.entries(C.asks)) {
+            if (spec.for && !spec.for(rec, asker))
+                continue;
+            const ask = { name, input: spec.input ?? { type: 'object' } };
+            if (spec.description !== undefined)
+                ask.description = spec.description;
+            if (spec.output !== undefined)
+                ask.output = spec.output;
+            asks.push(ask);
+        }
+        return { asks, notes: {} };
+    }
+    // The one function. Override to wrap it; call super to keep the dispatch.
+    async answer(asker, method, args = {}) {
+        if (method === undefined)
+            return this.describe(asker);
+        const C = this.constructor;
+        // Declared, by her, on purpose. `asks` is an ordinary object, so a bare
+        // lookup would also find every name on Object's prototype: `valueOf`
+        // would answer with her stance, `toString` with a string, and neither is
+        // an ask she wrote. Only her own keys are asks, which is what describe
+        // has always shown. What she shows is what she can be asked.
+        const spec = typeof method === 'string' && Object.hasOwn(C.asks, method) ? C.asks[method] : undefined;
+        if (!spec || (spec.for && !spec.for(this.occupant(asker), asker)))
+            return { error: 'unknown ask' };
+        const fn = this[method];
+        return fn.call(this, args ?? {}, asker);
+    }
+}

package/dist/being/digest.d.ts

@@ -0,0 +1,3 @@
+import type { Json } from './types.ts';
+export declare const canonical: (v: Json) => string;
+export declare const digest: (blueprint: Json) => Promise<string>;

package/dist/being/digest.js

@@ -0,0 +1,19 @@
+// A value I-JSON has no room for: a key left empty, a function, a symbol.
+// None of them cross an edge, so none of them may reach a digest. A key
+// carrying one is dropped and a slot carrying one is null, which is what
+// crossing does to them, so the digest names what arrived and not what she
+// happened to be holding.
+const absent = (v) => v === undefined || typeof v === 'function' || typeof v === 'symbol';
+// JCS for I-JSON values: sorted keys, no whitespace, JSON escaping. Numbers
+// are serialized as ES does, which is what RFC 8785 specifies.
+export const canonical = (v) => Array.isArray(v)
+    ? `[${v.map((slot) => (absent(slot) ? 'null' : canonical(slot))).join(',')}]`
+    : v !== null && typeof v === 'object'
+        ? `{${Object.keys(v)
+            .filter((k) => !absent(v[k]))
+            .sort()
+            .map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`)
+            .join(',')}}`
+        : JSON.stringify(v);
+const hex = (bytes) => Array.from(new Uint8Array(bytes), (b) => b.toString(16).padStart(2, '0')).join('');
+export const digest = async (blueprint) => hex(await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonical(blueprint))));

package/dist/being/index.d.ts

@@ -0,0 +1,5 @@
+export { Being, type AskSpec } from './being.ts';
+export { silence, isSilence, unreached, isUnreached, word, isWord, wordOf, DOOR_WORDS, isDoorWord } from './silence.ts';
+export { digest, canonical } from './digest.ts';
+export { OWNER, PUBLIC, RESERVED_IDS } from './types.ts';
+export type * from './types.ts';

package/dist/being/index.js

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// @quo-systems/quo — the Being side. What a being author imports, if anything.
+export { Being } from './being.js';
+export { silence, isSilence, unreached, isUnreached, word, isWord, wordOf, DOOR_WORDS, isDoorWord } from './silence.js';
+export { digest, canonical } from './digest.js';
+export { OWNER, PUBLIC, RESERVED_IDS } from './types.js';

package/dist/being/silence.d.ts

@@ -0,0 +1,10 @@
+import { type DoorWord, type Unreached, type Word, type WordName } from './types.ts';
+export declare const silence: unique symbol;
+export declare const isSilence: (x: unknown) => x is typeof silence;
+export declare const DOOR_WORDS: readonly DoorWord[];
+export declare const isDoorWord: (s: unknown) => s is DoorWord;
+export declare const word: <W extends WordName>(name: W) => Word<W>;
+export declare const isWord: (x: unknown) => x is Word;
+export declare const wordOf: (x: Word) => WordName;
+export declare const unreached: () => Unreached;
+export declare const isUnreached: (x: unknown) => x is Unreached;

package/dist/being/silence.js

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: Apache-2.0
+// Silence is one distinguished value. Null is an answer. Silence is no answer.
+//
+// The ward's words are the other distinguished values: what her ward tells
+// her when no object came back and it knows why. Each is one frozen object
+// under one symbol key, so a being cannot make one by accident, none of them
+// crosses an edge as a value, and a being who compares against them needs
+// no fourth shape. `unreached` is one of them.
+import { WORD_KEY } from './types.js';
+export const silence = Symbol.for('quo.silence');
+export const isSilence = (x) => x === silence;
+// The words a door says to a key it has bound, and no other. They ride on
+// the wire as `{ quo: word }`, so a reply is checked against this list.
+export const DOOR_WORDS = ['removed', 'absent', 'unannounced', 'repeated', 'threw'];
+export const isDoorWord = (s) => typeof s === 'string' && DOOR_WORDS.includes(s);
+const WORDS = new Map();
+export const word = (name) => {
+    let w = WORDS.get(name);
+    if (!w)
+        WORDS.set(name, (w = Object.freeze({ [WORD_KEY]: name })));
+    return w;
+};
+export const isWord = (x) => x !== null && typeof x === 'object' && typeof x[WORD_KEY] === 'string';
+export const wordOf = (x) => x[WORD_KEY];
+// Unreached: no far door was reached. Nothing is known to have been
+// delivered, so asking again is safe. A being cannot produce it: a ward that
+// sees a word come out of a being reads it as her having thrown.
+export const unreached = () => word('unreached');
+export const isUnreached = (x) => isWord(x) && wordOf(x) === 'unreached';

package/dist/being/types.d.ts

@@ -0,0 +1,84 @@
+import type { silence } from './silence.ts';
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export type JsonObject = {
+    [key: string]: Json;
+};
+export type Asker = {
+    id: string;
+} | {
+    id?: undefined;
+};
+export declare const OWNER = "OWNER";
+export declare const PUBLIC = "PUBLIC";
+export declare const RESERVED_IDS: readonly string[];
+export type Invitation = {
+    ward: string;
+    heir?: string;
+    secret?: string;
+};
+export type Schema = JsonObject;
+export type Ask = {
+    name: string;
+    description?: string;
+    input: Schema;
+    output?: Schema;
+};
+export type Blueprint = {
+    asks: Ask[];
+    notes: Json;
+};
+export type StandingRecord = {
+    id: string;
+    digest: string | null;
+    blueprint: Blueprint | null;
+    seen: string | null;
+};
+export type OccupantRecord = {
+    id: string;
+    notes: JsonObject;
+};
+export type Cells = {
+    standings: Record<string, StandingRecord>;
+    occupants: Record<string, OccupantRecord>;
+    [hers: string]: Json;
+};
+export type Silence = typeof silence;
+export type DoorWord = 'removed' | 'absent' | 'unannounced' | 'repeated' | 'threw';
+export type WardWord = 'unreached' | 'late' | 'invitation' | 'dropped';
+export type WordName = DoorWord | WardWord;
+export declare const WORD_KEY: unique symbol;
+export type Word<W extends WordName = WordName> = {
+    readonly [K in typeof WORD_KEY]: W;
+};
+export type Unreached = Word<'unreached'>;
+export type Answer = Json | Silence | Word;
+export type Reply = Json | Silence;
+export type Wanted = {
+    time?: number;
+};
+export type Standing = {
+    readonly id: string;
+    ask(method?: string, args?: JsonObject, wanted?: Wanted): Promise<Answer>;
+};
+export type Standings = {
+    knock(invitation: Invitation, method?: string, args?: JsonObject, wanted?: Wanted): Promise<Answer>;
+    take(id: string, invitation: Invitation): Promise<string | null>;
+    remove(id: string): void;
+} & {
+    readonly [id: string]: Standing | undefined;
+};
+export type Occupants = {
+    invite(id: string): Promise<Invitation | null>;
+    remove(id: string): void;
+};
+export type Stance = {
+    readonly cells: Cells;
+    readonly occupants: Occupants;
+    readonly standings: Standings;
+};
+export interface BeingLike {
+    answer(asker: Asker, method?: string, args?: JsonObject): Reply | Promise<Reply>;
+}
+export type BeingClass = new (stance: Stance) => BeingLike;

package/dist/being/types.js

@@ -0,0 +1,16 @@
+// The ids the ward speaks under, and no being may mint. An asker id is hers:
+// she chooses the strings, and the ward has no business in her namespace. But
+// the ward must sometimes stand at her door itself — its describe asks every
+// being under OWNER — and an id it shares with one of her occupants is two
+// different parties wearing one name. She could not tell them apart, and the
+// ward would shape its describe through an occupant's gate.
+//
+// So the ward's words are shouted, and refused at the mint. A word can only
+// be reserved before anyone has used it: a partition already holding an
+// occupant of that name could never have it taken back. PUBLIC guards nothing
+// today — a public asker is {} and carries no id at all — and that is exactly
+// why it is claimed now, while claiming it is free.
+export const OWNER = 'OWNER';
+export const PUBLIC = 'PUBLIC';
+export const RESERVED_IDS = [OWNER, PUBLIC];
+export const WORD_KEY = Symbol.for('quo.word');

package/dist/conformance/assert.d.ts

@@ -0,0 +1,11 @@
+export declare class Failed extends Error {
+}
+export declare function same(a: unknown, b: unknown): boolean;
+export type Assert = {
+    ok(value: unknown, message?: string): asserts value;
+    equal(actual: unknown, expected: unknown, message?: string): void;
+    notEqual(actual: unknown, expected: unknown, message?: string): void;
+    deepEqual(actual: unknown, expected: unknown, message?: string): void;
+    match(actual: string, re: RegExp, message?: string): void;
+};
+export declare const assert: Assert;

package/dist/conformance/assert.js

@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: Apache-2.0
+// The five assertions the conformance suite makes, and no more. Node has all
+// five in `node:assert/strict`, and naming that module would tie the suite to
+// one terrain -- the suite is the ward's truth, and the ward's truth has to be
+// checkable wherever a ward runs. So they are written here, in the language
+// alone, and `test/assert.test.ts` holds them to Node's own behaviour.
+export class Failed extends Error {
+}
+const show = (v) => {
+    if (typeof v === 'symbol')
+        return v.toString();
+    if (typeof v === 'bigint')
+        return `${v}n`;
+    if (v === undefined)
+        return 'undefined';
+    if (typeof v === 'function')
+        return `[function ${v.name}]`;
+    try {
+        return JSON.stringify(v) ?? Object.prototype.toString.call(v);
+    }
+    catch {
+        return Object.prototype.toString.call(v); // a cycle, or a null prototype
+    }
+};
+const fail = (why, message) => {
+    throw new Failed(message ? `${message}: ${why}` : why);
+};
+// Structural, and strict about shape the way `node:assert/strict` is: a value
+// is not equal to one of another kind, and an array is not equal to an object
+// that happens to hold the same keys.
+export function same(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b))
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((x, i) => same(x, b[i]));
+    if (a instanceof Uint8Array && b instanceof Uint8Array)
+        return a.length === b.length && a.every((x, i) => x === b[i]);
+    if (a instanceof Map || b instanceof Map || a instanceof Set || b instanceof Set)
+        return false; // the suite has none, and a wrong yes is worse than a refusal
+    const ka = Reflect.ownKeys(a), kb = Reflect.ownKeys(b);
+    if (ka.length !== kb.length)
+        return false;
+    return ka.every((k) => kb.includes(k) && same(a[k], b[k]));
+}
+export const assert = {
+    ok(value, message) {
+        if (!value)
+            fail(`${show(value)} is not truthy`, message);
+    },
+    equal(actual, expected, message) {
+        if (!Object.is(actual, expected))
+            fail(`${show(actual)} !== ${show(expected)}`, message);
+    },
+    notEqual(actual, expected, message) {
+        if (Object.is(actual, expected))
+            fail(`${show(actual)} === ${show(expected)}`, message);
+    },
+    deepEqual(actual, expected, message) {
+        if (!same(actual, expected))
+            fail(`${show(actual)} is not ${show(expected)}`, message);
+    },
+    match(actual, re, message) {
+        if (typeof actual !== 'string' || !re.test(actual))
+            fail(`${show(actual)} does not match ${String(re)}`, message);
+    },
+};

package/dist/conformance/beings.d.ts

@@ -0,0 +1,114 @@
+import { Being } from '../being/being.ts';
+import type { Asker, Blueprint, Invitation, JsonObject, OccupantRecord, Reply, Stance } from '../being/types.ts';
+export declare class Printer extends Being {
+    static cells: {
+        jobs: JsonObject[];
+        asks: JsonObject[];
+    };
+    static asks: {
+        print: {
+            input: {
+                type: string;
+            };
+        };
+    };
+    describe(): Blueprint;
+    print({ doc }: JsonObject, asker: Asker): {
+        printed: string | number | boolean | import("../being/types.ts").Json[] | {
+            [key: string]: import("../being/types.ts").Json;
+        } | null;
+    };
+}
+export declare class Shop extends Being {
+    static cells: {
+        printerId: string | null;
+        sales: JsonObject[];
+        minted: number;
+    };
+    static asks: {
+        hello: {
+            input: {
+                type: string;
+            };
+        };
+        buy: {
+            input: {
+                type: string;
+                properties: {
+                    item: {
+                        type: string;
+                    };
+                };
+            };
+        };
+        refund: {
+            input: {
+                type: string;
+            };
+            for: (rec: OccupantRecord | undefined) => boolean;
+        };
+    };
+    answer(asker: Asker, method?: string, args?: JsonObject): Promise<Reply>;
+    invite(tier?: string): Promise<Invitation>;
+    keepPrinter(invitation: Invitation): Promise<boolean>;
+    hello({ invitation }: JsonObject, asker: Asker): Promise<{
+        welcome: boolean;
+    }>;
+    buy({ item }: JsonObject, asker: Asker): Promise<{
+        error: string;
+        retry?: undefined;
+        ok?: undefined;
+        receipt?: undefined;
+    } | {
+        error: string;
+        retry: boolean;
+        ok?: undefined;
+        receipt?: undefined;
+    } | {
+        error?: undefined;
+        retry?: undefined;
+        ok: boolean;
+        receipt: import("../being/types.ts").Json;
+    }>;
+    refund(): {
+        ok: boolean;
+    };
+}
+export declare class Customer extends Being {
+    static cells: {
+        heard: JsonObject[];
+    };
+    static asks: {
+        hi: {
+            input: {
+                type: string;
+            };
+        };
+    };
+    join(invitation: Invitation): Promise<typeof import("../being/silence.ts").silence | import("../being/types.ts").Word | import("../being/types.ts").Json>;
+    buy(item: string): Promise<import("../being/types.ts").Answer>;
+    learn(): Promise<import("../being/types.ts").Answer>;
+    hi(_args: JsonObject, asker: Asker): {
+        heard: string;
+    };
+}
+export declare class Echo {
+    s: Stance;
+    constructor(stance: Stance);
+    answer(asker: Asker, method?: string, args?: JsonObject): Reply;
+}
+export declare class Member extends Being {
+    static cells: {
+        heard: JsonObject[];
+    };
+    static asks: {
+        ping: {
+            input: {
+                type: string;
+            };
+        };
+    };
+    ping(_args: JsonObject, asker: Asker): {
+        pong: string | null;
+    };
+}

package/dist/conformance/beings.js

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: Apache-2.0
+// The fixture beings. Fixed, so that the ward is what varies. A printer, a
+// shop, a customer on the base class, and one raw being with no base at all.
+import { Being } from '../being/being.js';
+import { isSilence, isUnreached, isWord } from '../being/silence.js';
+// A printer. Invites whom she is told to, prints for her occupants. Her
+// blueprint lives in her cells so a test can change her shape.
+export class Printer extends Being {
+    static cells = { jobs: [], asks: [{ name: 'print', input: { type: 'object' } }] };
+    static asks = { print: { input: { type: 'object' } } };
+    describe() {
+        return { asks: this.cells.asks, notes: { model: 'LX-2' } };
+    }
+    print({ doc }, asker) {
+        this.cells.jobs.push({ by: asker.id ?? null, doc: doc ?? null });
+        return { printed: doc ?? null };
+    }
+}
+// A shop. Invites customers in her own time. Keeps a printer as a standing.
+// Takes a gold customer back if the customer offers a way. Counts every ask
+// per occupant, by wrapping answer.
+export class Shop extends Being {
+    static cells = { printerId: null, sales: [], minted: 0 };
+    static asks = {
+        hello: { input: { type: 'object' } },
+        buy: { input: { type: 'object', properties: { item: { type: 'string' } } } },
+        refund: { input: { type: 'object' }, for: (rec) => rec?.notes.tier === 'gold' },
+    };
+    async answer(asker, method, args) {
+        const rec = this.occupant(asker);
+        if (rec && method !== undefined)
+            rec.notes.asks = (Number(rec.notes.asks) || 0) + 1;
+        return super.answer(asker, method, args);
+    }
+    // Outside any ask. She mints, her ward seals, she hands it out by mail.
+    async invite(tier = 'plain') {
+        const id = `cust${++this.cells.minted}`;
+        const inv = (await super.invite(id));
+        this.cells.occupants[id].notes.tier = tier;
+        return inv;
+    }
+    async keepPrinter(invitation) {
+        const bp = await this.knock(invitation);
+        if (isSilence(bp) || isWord(bp))
+            return false;
+        this.cells.printerId = await this.take('prn', invitation);
+        return true;
+    }
+    async hello({ invitation }, asker) {
+        const rec = this.occupant(asker);
+        if (rec?.notes.tier === 'gold' && invitation) {
+            const back = await this.knock(invitation, 'hi');
+            if (!isSilence(back) && !isWord(back))
+                await this.take(`vip-${asker.id}`, invitation);
+        }
+        return { welcome: true };
+    }
+    async buy({ item }, asker) {
+        if (typeof item !== 'string')
+            return { error: 'no such item' }; // args are hers to check
+        const id = this.cells.printerId;
+        const printer = id ? this.standings[id] : undefined;
+        if (!printer)
+            return { error: 'no printer' };
+        const out = await printer.ask('print', { doc: `receipt for ${item}` });
+        if (isUnreached(out))
+            return { error: 'printer unreachable', retry: true };
+        if (isSilence(out) || isWord(out))
+            return { error: 'printer refused' };
+        const st = this.cells.standings[id];
+        if (st.seen !== st.digest)
+            this.occupant(asker).notes.printerChanged = true;
+        this.cells.sales.push({ item: item ?? null, by: asker.id ?? null });
+        return { ok: true, receipt: out.printed };
+    }
+    refund() {
+        return { ok: true };
+    }
+}
+// A customer. Consumes an invitation, and only then decides to keep the
+// shop. Offers the shop a way back so the shop can reach her.
+export class Customer extends Being {
+    static cells = { heard: [] };
+    static asks = { hi: { input: { type: 'object' } } };
+    async join(invitation) {
+        const mine = (await this.invite('shop-back'));
+        const out = await this.knock(invitation, 'hello', { invitation: mine });
+        if (isSilence(out) || isWord(out))
+            return out; // nothing was born
+        await this.take('shop', invitation); // now, and only now
+        return out;
+    }
+    buy(item) {
+        return this.standings.shop.ask('buy', { item });
+    }
+    learn() {
+        return this.standings.shop.ask();
+    }
+    hi(_args, asker) {
+        this.cells.heard.push({ from: asker.id ?? null, method: 'hi' });
+        return { heard: 'hi' };
+    }
+}
+// The raw shape. No base class, no import from the kit. A being all the same.
+export class Echo {
+    s;
+    constructor(stance) {
+        this.s = stance;
+    }
+    answer(asker, method, args = {}) {
+        if (method === undefined)
+            return { asks: [{ name: 'echo', input: {} }], notes: {} };
+        return { from: asker.id ?? null, ...args };
+    }
+}
+// A member of an estate. Nothing scripted: she invites whom she is told to,
+// knocks where she is told to, and answers `ping` with the asker's own name.
+// The estate chapter drives her, and what it drives is the graph, not her.
+export class Member extends Being {
+    static cells = { heard: [] };
+    static asks = { ping: { input: { type: 'object' } } };
+    ping(_args, asker) {
+        this.cells.heard.push({ from: asker.id ?? null });
+        return { pong: asker.id ?? null };
+    }
+}

package/dist/conformance/estate.d.ts

@@ -0,0 +1,5 @@
+import type { Runner, World } from './index.ts';
+export declare function estate(label: string, make: () => Promise<World>, { canDown, test }: {
+    canDown: boolean;
+    test: Runner;
+}): void;