@quo-systems/quo 0.1.0

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@quo-systems/quo",
+  "version": "0.1.0",
+  "description": "Quo: an object asks another object and gets an answer, without knowing where it is. Being, Ward, Harbor.",
+  "keywords": [
+    "quo",
+    "protocol",
+    "capability",
+    "object-capability",
+    "rpc",
+    "ed25519",
+    "x25519"
+  ],
+  "author": "Razvan Gherghina",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    ".": "./src/being/index.ts",
+    "./ward": "./src/ward/index.ts",
+    "./harbor": "./src/harbor/index.ts",
+    "./conformance": "./src/conformance/index.ts"
+  },
+  "scripts": {
+    "check": "npm run typecheck && npm run lint && npm test && npm run check:estate",
+    "check:estate": "node --test \"estate/test/*.test.ts\"",
+    "typecheck": "tsc",
+    "typecheck:watch": "tsc --watch",
+    "lint": "npm run lint:ts && npm run lint:md",
+    "lint:ts": "oxlint --type-aware",
+    "lint:md": "markdownlint-cli2",
+    "lint:fix": "oxlint --type-aware --fix && markdownlint-cli2 --fix",
+    "test": "node --test \"test/*.test.ts\"",
+    "check:terrain": "node --test \"test/terrain/*.test.ts\" \"estate/test/terrain/*.test.ts\"",
+    "test:being": "node --test test/being.test.ts",
+    "test:ward": "node --test test/ward.test.ts",
+    "prepublishOnly": "npm run check && npm run check:terrain"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.1",
+    "bun": "^1.4.0",
+    "deno": "^2.9.6",
+    "esbuild": "^0.28.2",
+    "markdownlint-cli2": "^0.23.2",
+    "oxlint": "^1.81.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "playwright": "^1.62.1",
+    "typescript": "^7.0.2",
+    "workerd": "^1.20260904.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "vectors",
+    "SPEC.md",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/being/being.ts

@@ -0,0 +1,92 @@
+// 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';
+
+// 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.
+export type AskSpec = {
+  description?: string;
+  input?: Schema;
+  output?: Schema;
+  for?: (occupant: OccupantRecord | undefined, asker: Asker) => 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', '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: JsonObject = {};
+  // What she can be asked. Declaration order is blueprint order.
+  static asks: Record<string, AskSpec> = {};
+
+  readonly stance: Stance;
+
+  constructor(stance: Stance) {
+    this.stance = stance;
+    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 (typeof (this as unknown as Record<string, unknown>)[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(): Cells {
+    return this.stance.cells;
+  }
+  get standings(): Standings {
+    return this.stance.standings;
+  }
+  get occupants(): Occupants {
+    return this.stance.occupants;
+  }
+  invite(id: string): Promise<Invitation | null> {
+    return this.stance.occupants.invite(id);
+  }
+  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);
+  }
+  // The occupant record for whoever is at the door. Undefined at a public being.
+  occupant(asker: Asker): OccupantRecord | undefined {
+    return asker.id === undefined ? undefined : this.cells.occupants[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 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);
+    }
+    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> {
+    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
+    // 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 as unknown as Record<string, (args: JsonObject, asker: Asker) => Reply | Promise<Reply>>)[method];
+    return fn.call(this, args ?? {}, asker);
+  }
+}

package/src/being/digest.ts

@@ -0,0 +1,31 @@
+// 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 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.
+export const canonical = (v: Json): string =>
+  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: ArrayBuffer): string =>
+  Array.from(new Uint8Array(bytes), (b) => b.toString(16).padStart(2, '0')).join('');
+
+export const digest = async (blueprint: Json): Promise<string> =>
+  hex(await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonical(blueprint))));

package/src/being/index.ts

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: Apache-2.0
+// @quo-systems/quo — the Being side. What a being author imports, if anything.
+export { Being, type AskSpec } from './being.ts';
+export { silence, isSilence, unreached, isUnreached } from './silence.ts';
+export { digest, canonical } from './digest.ts';
+export { OWNER, PUBLIC, RESERVED_IDS } from './types.ts';
+export type * from './types.ts';

package/src/being/silence.ts

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
+// Silence is one distinguished value. Null is an answer. Silence is no answer.
+import { UNREACHED_KEY, type Unreached } from './types.ts';
+
+export const silence: unique symbol = Symbol.for('quo.silence');
+export const isSilence = (x: unknown): x is typeof silence => x === silence;
+
+// Unreached is the ward's own word: no far door was reached. It carries no
+// reason. Safe to retry, because nothing was delivered. A being cannot
+// produce it: a ward that sees it come out of a being treats it as silence.
+const UNREACHED: Unreached = Object.freeze({ [UNREACHED_KEY]: true });
+export const unreached = (): Unreached => UNREACHED;
+export const isUnreached = (x: unknown): x is Unreached =>
+  x !== null && typeof x === 'object' && (x as Record<symbol, unknown>)[UNREACHED_KEY] === true;

package/src/being/types.ts

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: Apache-2.0
+// The Being side of Quo, as types. Everything a being author can hold.
+// Nothing here knows a runtime, a key, or a wire.
+import type { silence } from './silence.ts';
+
+// I-JSON. Everything that crosses an edge.
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+export type JsonObject = { [key: string]: Json };
+
+// The asker: her own id for the being at the door. {} at a public being.
+export type Asker = { id: string } | { id?: undefined };
+
+// 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: readonly string[] = [OWNER, PUBLIC];
+
+// An invitation is a value. Opaque to her: the far ward's pk, a heir pk,
+// and the heir's secret. Without a heir it addresses a ward's public being.
+export type Invitation = { ward: string; heir?: string; secret?: string };
+
+// A blueprint is an MCP tool list plus notes.
+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 Unreached = { readonly [K in typeof UNREACHED_KEY]: true };
+export const UNREACHED_KEY: unique symbol = Symbol.for('quo.unreached');
+
+// What comes back from an ask or a knock.
+export type Answer = Json | Silence | Unreached;
+// What a being answers.
+export type Reply = Json | Silence;
+
+// What a being may ask for when she wants to say so herself: the time this
+// one ask may spend. Optional, and so is saying anything at all: an ask that
+// says nothing gets her ward's default, which is the ordinary way to ask.
+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>; // awaitable: a key is minted
+
+  remove(id: string): void;
+};
+
+// The stance. What every being, in every language, is handed at birth.
+export type Stance = {
+  readonly cells: Cells;
+  readonly occupants: Occupants;
+  readonly standings: Standings;
+};
+
+// The raw shape of a being. Anything with these two is a being.
+export interface BeingLike {
+  answer(asker: Asker, method?: string, args?: JsonObject): Reply | Promise<Reply>;
+}
+export type BeingClass = new (stance: Stance) => BeingLike;

package/src/conformance/assert.ts

@@ -0,0 +1,67 @@
+// 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: unknown): string => {
+  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: string, message?: string): never => {
+  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: unknown, b: unknown): boolean {
+  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 as Record<PropertyKey, unknown>)[k], (b as Record<PropertyKey, unknown>)[k]));
+}
+
+// `ok` narrows, the way `node:assert/strict`'s does: the suite leans on it to
+// turn a `string | null` into a `string`. That needs the explicit type below,
+// so the interface is written out rather than inferred.
+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 const assert: Assert = {
+  ok(value: unknown, message?: string): asserts value {
+    if (!value) fail(`${show(value)} is not truthy`, message);
+  },
+  equal(actual: unknown, expected: unknown, message?: string): void {
+    if (!Object.is(actual, expected)) fail(`${show(actual)} !== ${show(expected)}`, message);
+  },
+  notEqual(actual: unknown, expected: unknown, message?: string): void {
+    if (Object.is(actual, expected)) fail(`${show(actual)} === ${show(expected)}`, message);
+  },
+  deepEqual(actual: unknown, expected: unknown, message?: string): void {
+    if (!same(actual, expected)) fail(`${show(actual)} is not ${show(expected)}`, message);
+  },
+  match(actual: string, re: RegExp, message?: string): void {
+    if (typeof actual !== 'string' || !re.test(actual)) fail(`${show(actual)} does not match ${String(re)}`, message);
+  },
+};

package/src/conformance/beings.ts

@@ -0,0 +1,129 @@
+// 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.ts';
+import { isSilence, isUnreached } from '../being/silence.ts';
+import type { Asker, Blueprint, Invitation, JsonObject, OccupantRecord, Reply, Stance } from '../being/types.ts';
+
+// 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 override cells = { jobs: [] as JsonObject[], asks: [{ name: 'print', input: { type: 'object' } }] as JsonObject[] };
+  static override asks = { print: { input: { type: 'object' } } };
+  override describe(): Blueprint {
+    return { asks: this.cells.asks as never, notes: { model: 'LX-2' } };
+  }
+  print({ doc }: JsonObject, asker: Asker) {
+    (this.cells.jobs as JsonObject[]).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 override cells = { printerId: null as string | null, sales: [] as JsonObject[], minted: 0 };
+  static override asks = {
+    hello: { input: { type: 'object' } },
+    buy: { input: { type: 'object', properties: { item: { type: 'string' } } } },
+    refund: { input: { type: 'object' }, for: (rec: OccupantRecord | undefined) => rec?.notes.tier === 'gold' },
+  };
+
+  override async answer(asker: Asker, method?: string, args?: JsonObject): Promise<Reply> {
+    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'): Promise<Invitation> {
+    const id = `cust${++(this.cells.minted as number)}`;
+    const inv = (await super.invite(id))!;
+    this.cells.occupants[id].notes.tier = tier;
+    return inv;
+  }
+
+  async keepPrinter(invitation: Invitation): Promise<boolean> {
+    const bp = await this.knock(invitation);
+    if (isSilence(bp) || isUnreached(bp)) return false;
+    this.cells.printerId = await this.take('prn', invitation);
+    return true;
+  }
+
+  async hello({ invitation }: JsonObject, asker: Asker) {
+    const rec = this.occupant(asker);
+    if (rec?.notes.tier === 'gold' && invitation) {
+      const back = await this.knock(invitation as Invitation, 'hi');
+      if (!isSilence(back) && !isUnreached(back)) await this.take(`vip-${asker.id}`, invitation as Invitation);
+    }
+    return { welcome: true };
+  }
+
+  async buy({ item }: JsonObject, asker: Asker) {
+    if (typeof item !== 'string') return { error: 'no such item' }; // args are hers to check
+    const id = this.cells.printerId as string | null;
+    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)) return { error: 'printer refused' };
+    const st = this.cells.standings[id!];
+    if (st.seen !== st.digest) this.occupant(asker)!.notes.printerChanged = true;
+    (this.cells.sales as JsonObject[]).push({ item: item ?? null, by: asker.id ?? null });
+    return { ok: true, receipt: (out as JsonObject).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 override cells = { heard: [] as JsonObject[] };
+  static override asks = { hi: { input: { type: 'object' } } };
+
+  async join(invitation: Invitation) {
+    const mine = (await this.invite('shop-back'))!;
+    const out = await this.knock(invitation, 'hello', { invitation: mine as never });
+    if (isSilence(out) || isUnreached(out)) return out; // nothing was born
+    await this.take('shop', invitation); // now, and only now
+    return out;
+  }
+  buy(item: string) {
+    return this.standings.shop!.ask('buy', { item });
+  }
+  learn() {
+    return this.standings.shop!.ask();
+  }
+  hi(_args: JsonObject, asker: Asker) {
+    (this.cells.heard as JsonObject[]).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: Stance;
+  constructor(stance: Stance) {
+    this.s = stance;
+  }
+  answer(asker: Asker, method?: string, args: JsonObject = {}): Reply {
+    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 override cells = { heard: [] as JsonObject[] };
+  static override asks = { ping: { input: { type: 'object' } } };
+  ping(_args: JsonObject, asker: Asker) {
+    (this.cells.heard as JsonObject[]).push({ from: asker.id ?? null });
+    return { pong: asker.id ?? null };
+  }
+}