nervur 0.19.2 → 0.20.1

package/package.json

@@ -1,54 +1,47 @@
 {
   "name": "nervur",
-  "version": "0.19.2",
-  "description": "Nervur's kit of Quo: an object asks another object and gets an answer, without knowing where it is. Being, Ward, Harbor.",
+  "version": "0.20.1",
+  "description": "Nervur's kit of Quo: an object asks another object and gets an answer, without knowing where it is.",
   "keywords": [
     "quo",
     "protocol",
     "capability",
-    "object-capability",
-    "rpc",
-    "ed25519",
-    "x25519"
+    "object-capability"
   ],
   "author": "Razvan Gherghina",
   "license": "Apache-2.0",
   "homepage": "https://nervur.org",
   "type": "module",
-  "engines": {
-    "node": ">=22.18"
+  "bin": {
+    "nervur": "dist/cli/main.js"
   },
   "exports": {
     ".": {
-      "types": "./dist/being/index.d.ts",
-      "default": "./dist/being/index.js"
-    },
-    "./ward": {
-      "types": "./dist/ward/index.d.ts",
-      "default": "./dist/ward/index.js"
-    },
-    "./harbor": {
-      "types": "./dist/harbor/index.d.ts",
-      "default": "./dist/harbor/index.js"
-    },
-    "./conformance": {
-      "types": "./dist/conformance/index.d.ts",
-      "default": "./dist/conformance/index.js"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
-    "./vector": {
-      "types": "./dist/vector/index.d.ts",
-      "default": "./dist/vector/index.js"
+    "./folder": {
+      "types": "./dist/folder/index.d.ts",
+      "default": "./dist/folder/index.js"
     },
-    "./package.json": "./package.json"
+    "./tcp": {
+      "types": "./dist/tcp/index.d.ts",
+      "default": "./dist/tcp/index.js"
+    }
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json",
-    "check": "node ../../test.mjs \"test/*.test.ts\"",
-    "experimental": "node ../../test.mjs \"experimental/*.test.ts\"",
-    "deep": "node --test --test-timeout=300000 \"test/terrain/*.test.ts\"",
-    "cover": "node --test --test-timeout=60000 --experimental-test-coverage --test-coverage-exclude=\"**/dist/**\" --test-coverage-exclude=\"**/test/**\" --test-coverage-lines=99 --test-coverage-branches=93 --test-coverage-functions=95 \"test/*.test.ts\"",
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json && npm run build && node ../../test.mjs \"test/unit/*.test.ts\" \"test/e2e/*.test.ts\"",
+    "deep": "node ../../test.mjs \"test/terrain/*.test.ts\"",
+    "cover": "node --test --test-timeout=60000 --experimental-test-coverage --test-coverage-exclude=\"**/dist/**\" --test-coverage-exclude=\"**/test/**\" --test-coverage-exclude=\"**/src/stand/**\" --test-coverage-exclude=\"../../quo/**\" --test-coverage-lines=99 --test-coverage-branches=93 --test-coverage-functions=95 \"test/unit/*.test.ts\" \"test/e2e/*.test.ts\"",
     "prepublishOnly": "test \"$NERVUR_GATED\" = 1 || { echo 'a publish is /release, from the root, on the human'\"'\"'s word' >&2; exit 1; }"
   },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "dependencies": {
+    "@noble/post-quantum": "0.7.1"
+  },
   "publishConfig": {
     "access": "public"
   },

package/src/being/being.ts

@@ -1,28 +1,23 @@
 // SPDX-License-Identifier: Apache-2.0
-// The base class most beings extend. It writes `answer` for you: the empty
-// ask becomes a blueprint from the asks you declare, filtered per asker; a
-// named ask becomes a method call; anything not declared, or hidden from
-// this asker, is an error object. Underneath it is still one function, and
-// a class that writes that function by hand is a being just the same.
-import type { Ask, Asker, Blueprint, Cells, Invitation, JsonObject, Wanted, OccupantRecord, Occupants, Reply, Schema, Stance, Standings, Answer } from './types.ts';
+// The base class most beings extend. It writes `answer`: the empty ask is
+// her blueprint for this asker, a named ask calls her method of that name,
+// and an ask she did not declare, or hides from this asker, is an error
+// object. A class that writes `answer` by hand is a being just the same.
+// What she acts through is `this.stance`.
+import type { Ask, Asker, Blueprint, JsonObject, Reply, Schema, Stance } from './types.ts';
 
-// One declared ask. `for` decides whether this asker sees it, and so whether
-// this asker may call it: what she shows is what she can be asked.
+// One declared ask. `for` decides whether this asker sees it, and so
+// whether this asker may call it.
 export type AskSpec = {
-  description?: string;
-  input?: Schema;
-  output?: Schema;
-  for?: (occupant: OccupantRecord | undefined, asker: Asker) => boolean;
+  readonly description?: string;
+  readonly input?: Schema;
+  readonly for?: (asker: Asker, notes: JsonObject | undefined) => boolean;
 };
 
-// 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', 'lend', 'constructor']);
+// Names a subclass may not declare as an ask, because they are the base's.
+const RESERVED = new Set(['answer', 'describe', 'stance', 'cells', 'notes', '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.
+// Whether she wrote a method of that name, below Object's prototype.
 const wrote = (self: object, name: string): boolean => {
   for (let p = Object.getPrototypeOf(self); p !== null && p !== Object.prototype; p = Object.getPrototypeOf(p)) {
     if (Object.hasOwn(p, name)) return typeof (p as Record<string, unknown>)[name] === 'function';
@@ -30,18 +25,17 @@ const wrote = (self: object, name: string): boolean => {
   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: {} }`.
+type Method = (args: JsonObject, asker: Asker) => Reply | Promise<Reply>;
+
+// A subclass's statics replace its parent's and never merge: her blueprint
+// is what the class in front of you declares, in its order. Her kind is
+// never inherited: see `kind.ts`.
 export class Being {
-  // Her cells' defaults. Merged in at birth, only where a key is missing, so
-  // a restart keeps what she wrote.
+  // The name her row keeps for this class. Every class that stands declares
+  // its own.
+  static readonly kind: string = 'org.nervur.being';
+  // Her cells' defaults, written at birth only where a key is missing.
   static cells: JsonObject = {};
-  // 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: Record<string, AskSpec> = {};
 
   readonly stance: Stance;
@@ -51,73 +45,36 @@ export class Being {
     const C = this.constructor as typeof Being;
     for (const name of Object.keys(C.asks)) {
       if (RESERVED.has(name)) throw new Error(`ask '${name}' is a reserved name`);
-      if (!wrote(this, name)) throw new Error(`ask '${name}' has no method on the prototype`);
+      if (!wrote(this, name)) throw new Error(`ask '${name}' has no method`);
     }
-    // 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 (!Object.hasOwn(stance.cells, k)) stance.cells[k] = structuredClone(v);
   }
 
-  get cells(): Cells {
+  get cells(): JsonObject {
     return this.stance.cells;
   }
-  get standings(): Standings {
-    return this.stance.standings;
-  }
-  get occupants(): Occupants {
-    return this.stance.occupants;
-  }
-  // A standing at one of the things this device can do, under an id of hers.
-  // The ward knocks and takes it for her; the invitation never reaches her.
-  lend(name: string, id: string): Promise<string | null> {
-    return this.stance.lend(name, id);
-  }
-  invite(id: string, notes?: JsonObject): Promise<Invitation | null> {
-    return this.stance.occupants.invite(id, notes);
-  }
-  knock(invitation: Invitation, method?: string, args?: JsonObject, wanted?: Wanted): Promise<Answer> {
-    return this.stance.standings.knock(invitation, method, args, wanted);
-  }
-  take(id: string, invitation: Invitation): Promise<string | null> {
-    return this.stance.standings.take(id, invitation);
-  }
-  // 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: string, key: string, id?: string): Promise<string | null> {
-    return this.stance.boot(className, key, id);
-  }
-  // The occupant record for whoever is at the door. Undefined at a public being.
-  occupant(asker: Asker): OccupantRecord | undefined {
-    return asker.id !== undefined && Object.hasOwn(this.cells.occupants, asker.id) ? this.cells.occupants[asker.id] : undefined;
+
+  // The notes she invited this asker under.
+  notes(asker: Asker): JsonObject | undefined {
+    return asker.id === undefined ? undefined : this.stance.occupants.notes(asker.id);
   }
 
-  // Her blueprint for this asker. Override to shape it by hand.
   describe(asker: Asker): Blueprint {
     const C = this.constructor as typeof Being;
-    const rec = this.occupant(asker);
+    const notes = this.notes(asker);
     const asks: Ask[] = [];
     for (const [name, spec] of Object.entries(C.asks)) {
-      if (spec.for && !spec.for(rec, asker)) continue;
-      const ask: 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);
+      if (spec.for && !spec.for(asker, notes)) continue;
+      asks.push({ name, ...(spec.description === undefined ? {} : { description: spec.description }), input: spec.input ?? { type: 'object' } });
     }
     return { asks, notes: {} };
   }
 
-  // The one function. Override to wrap it; call super to keep the dispatch.
-  async answer(asker: Asker, method?: string, args: JsonObject = {}): Promise<Reply> {
+  async answer(asker: Asker, method: string | undefined, args: JsonObject): Promise<Reply> {
     if (method === undefined) return this.describe(asker);
     const C = this.constructor as typeof Being;
-    // 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
-    // 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 as unknown as Record<string, (args: JsonObject, asker: Asker) => Reply | Promise<Reply>>)[method];
-    return fn.call(this, args ?? {}, asker);
+    if (!spec || (spec.for && !spec.for(asker, this.notes(asker)))) return { error: 'unknown ask' };
+    return ((this as unknown as Record<string, Method>)[method] as Method).call(this, args, asker);
   }
 }

package/src/being/digest.ts

@@ -1,46 +1,18 @@
 // SPDX-License-Identifier: Apache-2.0
-// The digest: SHA-256, as hex, over the JCS (RFC 8785) canonical form of a
-// blueprint. Same bytes from every language. WebCrypto only, so it runs
-// wherever the language runs.
-import type { Json } from './types.ts';
+// A being's `seen`: SHA-256, lowercase hex, over the canonical form of her
+// blueprint for one asker. Keys sorted by UTF-16 code units, numbers as
+// ECMAScript writes them, no whitespace.
+import { hex, sha256, utf8, type Json } from '../crypto/index.ts';
 
-// 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: unknown): boolean => 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. A hole in a
-// list is null, as JSON writes it.
 export const canonical = (v: Json): string => {
-  if (Array.isArray(v)) return `[${Array.from(v, (slot) => (absent(slot) ? 'null' : canonical(slot))).join(',')}]`;
+  if (Array.isArray(v)) return `[${v.map(canonical).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])}`)
+      .map((k) => `${JSON.stringify(k)}:${canonical(v[k]!)}`)
       .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: ArrayBuffer): string =>
-  Array.from(new Uint8Array(bytes), (b) => b.toString(16).padStart(2, '0')).join('');
-
-// `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 = (): SubtleCrypto => {
-  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: Json): Promise<string> => hex(await subtle().digest('SHA-256', new TextEncoder().encode(canonical(blueprint))));
+export const digest = async (blueprint: Json): Promise<string> => hex(await sha256(utf8(canonical(blueprint))));

package/src/being/faculty.ts

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+// A faculty: a being of the box ward that fulfils a contract. A contract is
+// a class between `Faculty` and the class that stands, usually abstract:
+//
+//   abstract class Timer extends Faculty {           the contract
+//     static override kind = 'com.acme.timer' }
+//   class IntervalTimer extends Timer {              one class that fulfils it
+//     static override kind = 'com.acme.interval-timer' }
+//
+// A being lends by the contract's kind and never learns the class. Every
+// class between the faculty and `Faculty` is a contract and declares its
+// own kind, and a faculty fulfils each of them and her own. Two asks are the
+// faculty's own and answered to the ward-being that opened her alone:
+// `offer`, an invitation on herself for a ward the dock vouches for, and
+// `retract`, an offer that was not taken.
+import { Being } from './being.ts';
+import { kindOf } from './kind.ts';
+import { WARD, type Asker, type Blueprint, type JsonObject, type Reply } from './types.ts';
+
+export class Faculty extends Being {
+  static override readonly kind: string = 'org.nervur.faculty';
+
+  // The contracts a class fulfils: itself and every class between it and
+  // `Faculty`, by kind. A class among them with no kind of its own throws.
+  static contracts(C: abstract new (...args: never[]) => unknown): string[] {
+    const kinds: string[] = [];
+    for (let c: unknown = C; typeof c === 'function' && c !== Faculty; c = Object.getPrototypeOf(c)) kinds.push(kindOf(c));
+    return kinds;
+  }
+
+  static fulfils(C: unknown): C is typeof Faculty {
+    return typeof C === 'function' && C.prototype instanceof Faculty;
+  }
+
+  #open(): Record<string, string> {
+    if (this.cells.offers === undefined) this.cells.offers = {};
+    return this.cells.offers as Record<string, string>;
+  }
+
+  async #offer(): Promise<JsonObject> {
+    const n = ((this.cells.offered as number | undefined) ?? 0) + 1;
+    this.cells.offered = n;
+    const id = `lent:${n}`;
+    const invitation = await this.stance.occupants.invite(id);
+    if (invitation === null) return { error: 'not invited' };
+    this.#open()[invitation.heir] = id;
+    return { invitation };
+  }
+
+  #retract(args: JsonObject): JsonObject {
+    const open = this.#open();
+    const id = typeof args.heir === 'string' && Object.hasOwn(open, args.heir) ? open[args.heir] : undefined;
+    if (id === undefined) return { retracted: null };
+    this.stance.occupants.remove(id);
+    delete open[args.heir as string];
+    return { retracted: id };
+  }
+
+  override describe(asker: Asker): Blueprint {
+    const blueprint = super.describe(asker);
+    if (asker.id !== WARD) return blueprint;
+    return { ...blueprint, asks: [...blueprint.asks, { name: 'offer', input: { type: 'object' } }, { name: 'retract', input: { type: 'object', required: ['heir'] } }] };
+  }
+
+  // An offer is closed by the first word from the occupant it was made for.
+  override answer(asker: Asker, method: string | undefined, args: JsonObject): Promise<Reply> {
+    if (asker.id === WARD && method === 'offer') return this.#offer();
+    if (asker.id === WARD && method === 'retract') return Promise.resolve(this.#retract(args));
+    const open = this.#open();
+    for (const [heir, id] of Object.entries(open)) if (id === asker.id) delete open[heir];
+    return super.answer(asker, method, args);
+  }
+}

package/src/being/index.ts

@@ -1,8 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
-// nervur — the Being side. What a being author imports, if anything.
+// What a being author imports.
 export { Being, type AskSpec } from './being.ts';
-export { Lent, BOX, LENT_ASKS } from './lent.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, isBlueprint, invitationArgs, isInvitation } from './types.ts';
-export type * from './types.ts';
+export { canonical, digest } from './digest.ts';
+export { Faculty } from './faculty.ts';
+export { isKind, KIT, kindOf, ownKind } from './kind.ts';
+export { OWNER, WARD, type Answer, type Ask, type Asker, type BeingClass, type BeingLike, type Blueprint, type Invitation, type Json, type JsonObject, type Occupants, type Reply, type Schema, type Stance, type Standing, type Standings, type Wanted } from './types.ts';
+export { isSilence, isWord, silence, told, word, type Silence, type Word, type WordName } from './words.ts';

package/src/being/kind.ts

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+// A kind: the name a row keeps for the class a being is born of, and the
+// name a contract is lent by. It is declared on the class, never taken from
+// the name the language gives it, because a bundler renames classes.
+//
+//   static kind = 'com.acme.shop'
+//
+// A kind is a reversed domain its author owns, then a name: at least three
+// segments joined by `.`, each lowercase letters, digits and `-`, starting
+// with a letter or digit. `org.nervur.` is the kit's own. A class declares
+// its own kind: one it inherits names its parent, so it is none.
+export const KIT = 'org.nervur.';
+
+const KIND = /^[a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*){2,}$/;
+
+export const isKind = (text: unknown): text is string => typeof text === 'string' && KIND.test(text);
+
+// The kind a class declares on itself, or undefined.
+export const ownKind = (C: unknown): string | undefined => {
+  if (typeof C !== 'function' || !Object.hasOwn(C, 'kind')) return undefined;
+  const kind = (C as { kind?: unknown }).kind;
+  return isKind(kind) ? kind : undefined;
+};
+
+// The kind a class declares on itself, or a throw naming the class.
+export const kindOf = (C: unknown): string => {
+  const kind = ownKind(C);
+  if (kind === undefined) throw new Error(`class ${typeof C === 'function' ? C.name : String(C)} declares no kind of its own`);
+  return kind;
+};