@quo-systems/quo 0.2.9 → 0.2.11

package/dist/being/being.d.ts

@@ -13,10 +13,10 @@ export declare class Being {
     get cells(): Cells;
     get standings(): Standings;
     get occupants(): Occupants;
-    invite(id: string): Promise<Invitation | null>;
+    invite(id: string, notes?: JsonObject): Promise<Invitation | null>;
     knock(invitation: Invitation, method?: string, args?: JsonObject, wanted?: Wanted): Promise<Answer>;
     take(id: string, invitation: Invitation): Promise<string | null>;
-    boot(className: string, key: string): string | null;
+    boot(className: string, key: string, id?: string): 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

@@ -1,10 +1,29 @@
 // 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', 'boot', 'constructor']);
+// Whether she has a method of that name, written on her own prototype chain
+// below Object's. A name Object lends every object, `hasOwnProperty` or
+// `toString`, is not a method she wrote; and a field she assigns in her own
+// constructor is not there yet when the base checks, so an ask is a method
+// on the prototype and nothing else.
+const method = (self, name) => {
+    for (let p = Object.getPrototypeOf(self); p !== null && p !== Object.prototype; p = Object.getPrototypeOf(p)) {
+        if (Object.hasOwn(p, name))
+            return typeof p[name] === 'function';
+    }
+    return false;
+};
+// Both statics below are read off the class the object was made from, so a
+// subclass declaring either replaces its parent's rather than adding to it.
+// That is the rule: her blueprint is exactly what the class in front of you
+// declares, in the order she chose, and merging down a chain would hand her
+// asks she may mean to drop and an order she did not write. A subclass that
+// means to extend says so, `static override asks = { ...Parent.asks, mine: {} }`.
 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.
+    // What she can be asked. Declaration order is blueprint order, except a
+    // name that reads as an array index, which the language lists first.
     static asks = {};
     stance;
     constructor(stance) {
@@ -13,11 +32,13 @@ export class Being {
         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`);
+            if (!method(this, name))
+                throw new Error(`ask '${name}' has no method on the prototype`);
         }
+        // Own keys only: a default named after a member of Object's prototype is
+        // still hers, and still missing until she writes it.
         for (const [k, v] of Object.entries(C.cells))
-            if (!(k in stance.cells))
+            if (!Object.hasOwn(stance.cells, k))
                 stance.cells[k] = structuredClone(v);
     }
     get cells() {
@@ -29,8 +50,8 @@ export class Being {
     get occupants() {
         return this.stance.occupants;
     }
-    invite(id) {
-        return this.stance.occupants.invite(id);
+    invite(id, notes) {
+        return this.stance.occupants.invite(id, notes);
     }
     knock(invitation, method, args, wanted) {
         return this.stance.standings.knock(invitation, method, args, wanted);
@@ -38,13 +59,14 @@ export class Being {
     take(id, invitation) {
         return this.stance.standings.take(id, invitation);
     }
-    // A new being of her ward, by class name, under a key she chooses.
-    boot(className, key) {
-        return this.stance.boot(className, key);
+    // A new being of her ward, by class name, under a key she chooses. With an
+    // id, she holds a standing to the being she made, who knows her by her key.
+    boot(className, key, id) {
+        return this.stance.boot(className, key, id);
     }
     // 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];
+        return asker.id !== undefined && Object.hasOwn(this.cells.occupants, asker.id) ? this.cells.occupants[asker.id] : undefined;
     }
     // Her blueprint for this asker. Override to shape it by hand.
     describe(asker) {
@@ -72,8 +94,8 @@ export class Being {
         // 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;
+        // shows. What she shows is what she can be asked.
+        const spec = 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];

package/dist/being/digest.js

@@ -5,15 +5,33 @@
 // 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)
+// are serialized as ES does, which is what RFC 8785 specifies. A hole in a
+// list is null, as JSON writes it.
+export const canonical = (v) => {
+    if (Array.isArray(v))
+        return `[${Array.from(v, (slot) => (absent(slot) ? 'null' : canonical(slot))).join(',')}]`;
+    if (v !== null && typeof v === 'object') {
+        return `{${Object.keys(v)
             .filter((k) => !absent(v[k]))
             .sort()
             .map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`)
-            .join(',')}}`
-        : JSON.stringify(v);
+            .join(',')}}`;
+    }
+    return JSON.stringify(v);
+};
+// Hex and the guard are spelled here and again in `src/ward/arithmetic.ts`,
+// which is the price of the boundary: nothing under `src/being` imports
+// anything above it, because this is the whole world a being's own code sees
+// and a being reaching the ward is the thing the shape is against.
 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))));
+// `crypto.subtle` is read at the call and never captured at load. A browser
+// on a plain http:// origin has `crypto` without `subtle`, and a terrain may
+// install one after this module is first imported; either way the failure is
+// one sentence and not a TypeError from inside a digest nobody can read.
+const subtle = () => {
+    const s = globalThis.crypto?.subtle;
+    if (!s)
+        throw new Error('this terrain has no crypto.subtle: a being needs a secure context to be described');
+    return s;
+};
+export const digest = async (blueprint) => hex(await subtle().digest('SHA-256', new TextEncoder().encode(canonical(blueprint))));

package/dist/being/index.d.ts

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

package/dist/being/index.js

@@ -1,6 +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 { silence, isSilence, answered, unreached, isUnreached, word, isWord, wordOf, told, DOOR_WORDS, isDoorWord } from './silence.js';
 export { digest, canonical } from './digest.js';
-export { OWNER, PUBLIC, RESERVED_IDS } from './types.js';
+export { OWNER, PUBLIC, RESERVED_IDS, isBlueprint, invitationArgs } from './types.js';

package/dist/being/silence.d.ts

@@ -6,5 +6,7 @@ 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 answered: <T>(x: T) => x is Exclude<T, typeof silence | Word>;
+export declare const told: (x: unknown) => unknown;
 export declare const unreached: () => Unreached;
 export declare const isUnreached: (x: unknown) => x is Unreached;

package/dist/being/silence.js

@@ -22,6 +22,18 @@ export const word = (name) => {
 };
 export const isWord = (x) => x !== null && typeof x === 'object' && typeof x[WORD_KEY] === 'string';
 export const wordOf = (x) => x[WORD_KEY];
+// What came back is an answer and not one of the two things that are not
+// answers. A being who only wants the object writes one test instead of
+// three, and the three shapes stay three shapes: silence is no answer, a word
+// is her ward telling her why there is none.
+export const answered = (x) => !isSilence(x) && !isWord(x);
+// What she was told, with a word given its name and everything else left
+// exactly as it came. One value to compare against, so asking which word came
+// back is one test and not two joined by an and: `told(out) === 'late'` says
+// what `isWord(out) && wordOf(out) === 'late'` says, and says which answer
+// arrived instead when it is wrong, where the pair collapses to false and
+// names nothing. Silence stays the symbol it is, and an object stays itself.
+export const told = (x) => (isWord(x) ? wordOf(x) : x);
 // 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.

package/dist/being/types.d.ts

@@ -18,6 +18,7 @@ export type Invitation = {
     heir?: string;
     secret?: string;
 };
+export declare const invitationArgs: (inv: Invitation) => JsonObject;
 export type Schema = JsonObject;
 export type Ask = {
     name: string;
@@ -29,6 +30,7 @@ export type Blueprint = {
     asks: Ask[];
     notes: Json;
 };
+export declare const isBlueprint: (v: unknown) => v is Blueprint;
 export type StandingRecord = {
     id: string;
     digest: string | null;
@@ -70,14 +72,14 @@ export type Standings = {
     readonly [id: string]: Standing | undefined;
 };
 export type Occupants = {
-    invite(id: string): Promise<Invitation | null>;
+    invite(id: string, notes?: JsonObject): Promise<Invitation | null>;
     remove(id: string): void;
 };
 export type Stance = {
     readonly cells: Cells;
     readonly occupants: Occupants;
     readonly standings: Standings;
-    boot(className: string, key: string): string | null;
+    boot(className: string, key: string, id?: string): Promise<string | null>;
 };
 export interface BeingLike {
     answer(asker: Asker, method?: string, args?: JsonObject): Reply | Promise<Reply>;

package/dist/being/types.js

@@ -13,4 +13,29 @@
 export const OWNER = 'OWNER';
 export const PUBLIC = 'PUBLIC';
 export const RESERVED_IDS = [OWNER, PUBLIC];
+// An invitation as one object of values, which is what it already is. A being
+// who hands one on sends it as args, and args are values; this is the one
+// place that is spelled, so nobody spells it with a cast. Absent stays absent:
+// an invitation to a public being carries no heir and no secret, and a key
+// present and undefined is not the same object once JSON has been through it.
+export const invitationArgs = (inv) => ({
+    ward: inv.ward,
+    ...(inv.heir !== undefined ? { heir: inv.heir } : {}),
+    ...(inv.secret !== undefined ? { secret: inv.secret } : {}),
+});
+// Whether what came back from an empty ask is a blueprint. Every describe on
+// the far side of a door is somebody else's code, so nothing may be written
+// into a standing's record as a blueprint without being read as one first: a
+// side walks `asks` by name, and a list of anything else, or no list at all,
+// is a side that breaks on a far ward's answer. The asks are checked to the
+// depth a side reads them, a name and an input each, and no further: what a
+// far being puts beside those is hers.
+export const isBlueprint = (v) => {
+    if (v === null || typeof v !== 'object' || Array.isArray(v))
+        return false;
+    const { asks, notes } = v;
+    if (!Array.isArray(asks) || notes === undefined)
+        return false;
+    return asks.every((a) => a !== null && typeof a === 'object' && !Array.isArray(a) && typeof a.name === 'string' && a.input !== null && typeof a.input === 'object' && !Array.isArray(a.input));
+};
 export const WORD_KEY = Symbol.for('quo.word');

package/dist/conformance/assert.js

@@ -15,6 +15,15 @@ const show = (v) => {
         return 'undefined';
     if (typeof v === 'function')
         return `[function ${v.name}]`;
+    // A ward's word is a frozen object under one symbol key, and JSON shows it
+    // as `{}`. A red estate chapter saying `{} is not {}` names nothing, so a
+    // value whose own keys are all symbols is shown by its keys.
+    if (v !== null && typeof v === 'object') {
+        const keys = Object.keys(v);
+        const syms = Object.getOwnPropertySymbols(v).filter((s) => Object.getOwnPropertyDescriptor(v, s).enumerable);
+        if (keys.length === 0 && syms.length > 0)
+            return `{ ${syms.map((s) => `${s.toString()}: ${show(v[s])}`).join(', ')} }`;
+    }
     try {
         return JSON.stringify(v) ?? Object.prototype.toString.call(v);
     }
@@ -28,22 +37,47 @@ const fail = (why, message) => {
 // 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.
+// The four kinds this compares, and every other object is refused rather than
+// guessed at. A Date, a RegExp, a boxed primitive and a class instance each
+// carry state no key walk can see, so two of them with the same keys are
+// equal here and unequal in node, which is a wrong yes: the one answer a
+// suite must never give. A refusal is a red test that says so.
+const KNOWN = [Object.prototype, null, Array.prototype, Uint8Array.prototype];
+// What node compares: own enumerable keys, strings then enumerable symbols.
+// Not `Reflect.ownKeys`, which also lists what a definition hid.
+const keysOf = (v) => [...Object.keys(v), ...Object.getOwnPropertySymbols(v).filter((s) => Object.getOwnPropertyDescriptor(v, s).enumerable)];
 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))
+    const proto = Object.getPrototypeOf(a);
+    if (proto !== Object.getPrototypeOf(b))
         return false;
+    if (!KNOWN.includes(proto))
+        return false; // a Date, a RegExp, a boxed number, a class of hers
     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);
+    // An array is its indices and whatever else was hung on it, and a hole is
+    // not a present undefined: `[, 1]` and `[undefined, 1]` differ in node and
+    // must differ here. `every` skips holes, so the loop is written out.
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i += 1) {
+            if (i in a !== i in b)
+                return false;
+            if (i in a && !same(a[i], b[i]))
+                return false;
+        }
+        const extra = (v) => keysOf(v).filter((k) => typeof k !== 'string' || !/^(?:0|[1-9]\d*)$/.test(k));
+        const xa = extra(a), xb = extra(b);
+        const at = (v, k) => v[k];
+        return xa.length === xb.length && xa.every((k) => xb.includes(k) && same(at(a, k), at(b, k)));
+    }
+    const ka = keysOf(a), kb = keysOf(b);
     if (ka.length !== kb.length)
         return false;
     return ka.every((k) => kb.includes(k) && same(a[k], b[k]));

package/dist/conformance/beings.d.ts

@@ -1,5 +1,5 @@
 import { Being } from '../being/being.ts';
-import type { Asker, Blueprint, Invitation, JsonObject, OccupantRecord, Reply, Stance } from '../being/types.ts';
+import type { Asker, Blueprint, Invitation, Json, JsonObject, OccupantRecord, Reply, Stance } from '../being/types.ts';
 export declare class Printer extends Being {
     static cells: {
         jobs: JsonObject[];
@@ -14,8 +14,8 @@ export declare class Printer extends Being {
     };
     describe(): Blueprint;
     print({ doc }: JsonObject, asker: Asker): {
-        printed: string | number | boolean | import("../being/types.ts").Json[] | {
-            [key: string]: import("../being/types.ts").Json;
+        printed: string | number | boolean | Json[] | {
+            [key: string]: Json;
         } | null;
     };
 }
@@ -68,7 +68,7 @@ export declare class Shop extends Being {
         error?: undefined;
         retry?: undefined;
         ok: boolean;
-        receipt: import("../being/types.ts").Json;
+        receipt: Json;
     }>;
     refund(): {
         ok: boolean;
@@ -85,7 +85,9 @@ export declare class Customer extends Being {
             };
         };
     };
-    join(invitation: Invitation): Promise<typeof import("../being/silence.ts").silence | import("../being/types.ts").Word | import("../being/types.ts").Json>;
+    join(invitation: Invitation): Promise<string | number | boolean | typeof import("../being/silence.ts").silence | Json[] | import("../being/types.ts").Word<import("../being/types.ts").WordName> | {
+        [key: string]: Json;
+    } | null>;
     buy(item: string): Promise<import("../being/types.ts").Answer>;
     learn(): Promise<import("../being/types.ts").Answer>;
     hi(_args: JsonObject, asker: Asker): {
@@ -97,6 +99,47 @@ export declare class Echo {
     constructor(stance: Stance);
     answer(asker: Asker, method?: string, args?: JsonObject): Reply;
 }
+export declare class Maker extends Being {
+    static cells: {
+        made: string[];
+    };
+    static asks: {
+        open: {
+            input: {
+                type: string;
+                properties: {
+                    class: {
+                        type: string;
+                    };
+                    key: {
+                        type: string;
+                    };
+                    id: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+        say: {
+            input: {
+                type: string;
+                properties: {
+                    id: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+    };
+    open({ class: className, key, id }: JsonObject): Promise<{
+        made: string | null;
+    }>;
+    say({ id }: JsonObject): Promise<{
+        said: Json;
+    }>;
+}
 export declare class Member extends Being {
     static cells: {
         heard: JsonObject[];

package/dist/conformance/beings.js

@@ -1,14 +1,18 @@
 // 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.
+// shop, a customer on the base class, a maker, a member, and one raw being
+// with no base at all.
 import { Being } from '../being/being.js';
-import { isSilence, isUnreached, isWord } from '../being/silence.js';
+import { answered, isUnreached } from '../being/silence.js';
+import { invitationArgs } from '../being/types.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() {
+        // Her own cells, which a test writes to change her shape. Cells are Json
+        // to the ward, so the asks are named for what she keeps in them.
         return { asks: this.cells.asks, notes: { model: 'LX-2' } };
     }
     print({ doc }, asker) {
@@ -41,7 +45,7 @@ export class Shop extends Being {
     }
     async keepPrinter(invitation) {
         const bp = await this.knock(invitation);
-        if (isSilence(bp) || isWord(bp))
+        if (!answered(bp))
             return false;
         this.cells.printerId = await this.take('prn', invitation);
         return true;
@@ -50,7 +54,7 @@ export class Shop extends Being {
         const rec = this.occupant(asker);
         if (rec?.notes.tier === 'gold' && invitation) {
             const back = await this.knock(invitation, 'hi');
-            if (!isSilence(back) && !isWord(back))
+            if (answered(back))
                 await this.take(`vip-${asker.id}`, invitation);
         }
         return { welcome: true };
@@ -65,7 +69,7 @@ export class Shop extends Being {
         const out = await printer.ask('print', { doc: `receipt for ${item}` });
         if (isUnreached(out))
             return { error: 'printer unreachable', retry: true };
-        if (isSilence(out) || isWord(out))
+        if (!answered(out))
             return { error: 'printer refused' };
         const st = this.cells.standings[id];
         if (st.seen !== st.digest)
@@ -83,9 +87,13 @@ 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))
+        // A way back for the shop, if she can mint one. She may not: two joins on
+        // one invitation race, and the second finds the id taken. Then she offers
+        // nothing and knocks all the same, which is what the shop is asked to
+        // survive. The old shape said `!` here and was wrong about it.
+        const mine = await this.invite('shop-back');
+        const out = await this.knock(invitation, 'hello', { invitation: mine === null ? null : invitationArgs(mine) });
+        if (!answered(out))
             return out; // nothing was born
         await this.take('shop', invitation); // now, and only now
         return out;
@@ -116,6 +124,29 @@ export class Echo {
 // 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.
+// A being who makes beings. `boot` is on every stance, so it is the ward's
+// promise and not this kit's, and a second kit that never wired it hands its
+// beings a call that answers null for ever. She says what came of it: the key
+// back, or null for a key already taken, a class the harbor does not hold, or
+// a constructor that threw. With an id she also asks for a way back, and then
+// she holds a standing to what she made like any other.
+export class Maker extends Being {
+    static cells = { made: [] };
+    static asks = {
+        open: { input: { type: 'object', properties: { class: { type: 'string' }, key: { type: 'string' }, id: { type: 'string' } }, required: ['class', 'key'] } },
+        say: { input: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] } },
+    };
+    async open({ class: className, key, id }) {
+        const made = await this.boot(className, key, id);
+        if (made !== null)
+            this.cells.made.push(made);
+        return { made };
+    }
+    async say({ id }) {
+        const standing = this.standings[id];
+        return { said: standing === undefined ? null : (await standing.ask('ping')) };
+    }
+}
 export class Member extends Being {
     static cells = { heard: [] };
     static asks = { ping: { input: { type: 'object' } } };