nervur 0.21.4 → 0.22.0

package/src/ward/ward-being.ts

@@ -1,103 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The ward-being: the first being of every ward, the ward itself. Her asks
-// are the root's, shown and answered to `OWNER` alone.
-import { Being, isSilence, isWord, KIT, OWNER, told, type Answer, type Asker, type AskSpec, type BeingClass, type Blueprint, type Invitation, type JsonObject, type Stance } from '../being/index.ts';
-
-// What the ward lends its ward-being, and no other being.
-export interface Steward {
-  pk(): string;
-  classOf(name: string): BeingClass | undefined;
-  beings(): Record<string, { class: string; public: boolean; absent: boolean }>;
-  boot(key: string, className: string): Promise<'booted' | 'key taken' | 'no such class' | 'threw at birth'>;
-  unboot(key: string): boolean;
-  publish(key: string | null): boolean;
-  invite(being: string, id: string, notes: JsonObject): Promise<Invitation | null>;
-  ask(being: string | null, method: string | undefined, args: JsonObject): Promise<Answer>;
-}
-
-export type WardBeingStance = Stance & { readonly steward: Steward };
-
-// Whoever pilots a ward: the root, holding its unsealed ask, or an owner,
-// an occupant of the ward-being the root invited as one.
-export const pilots = (asker: Asker, notes: JsonObject | undefined): boolean => asker.id === OWNER || notes?.owner === true;
-
-// An ask whoever pilots the ward may make.
-export const ownerAsk = (description: string, input: JsonObject = {}): AskSpec => ({ description, input: { type: 'object', ...input }, for: pilots });
-
-// An ask the root alone may make, so a carried key pilots but never hands
-// piloting on.
-export const rootAsk = (description: string, input: JsonObject = {}): AskSpec => ({ description, input: { type: 'object', ...input }, for: (asker: Asker) => asker.id === OWNER });
-// The one kit kind the root boots: every other kit class stands where the
-// kit puts it.
-export const PILOT = 'org.nervur.pilot';
-
-const text = (v: unknown): v is string => typeof v === 'string';
-const object = (v: unknown): v is JsonObject => typeof v === 'object' && v !== null && !Array.isArray(v);
-
-export class WardBeing extends Being {
-  static override readonly kind: string = 'org.nervur.ward-being';
-  static override asks: Record<string, AskSpec> = {
-    boot: ownerAsk('a new being of this ward', { required: ['key', 'class'] }),
-    unboot: ownerAsk('a being out, with every relation she holds', { required: ['being'] }),
-    public: ownerAsk('the being a stranger reaches, or none', { required: ['key'] }),
-    invite: ownerAsk('an invitation on a being of this ward', { required: ['being', 'id'] }),
-    ask: ownerAsk('a being of this ward, asked as the owner; with no being, the public being asked as nobody'),
-    own: rootAsk('an invitation for an owner of this ward, under an id', { required: ['id'] }),
-    disown: rootAsk('an owner no more', { required: ['id'] }),
-  };
-
-  readonly steward: Steward;
-
-  constructor(stance: WardBeingStance) {
-    super(stance);
-    this.steward = stance.steward;
-  }
-
-  override describe(asker: Asker): Blueprint {
-    const { asks } = super.describe(asker);
-    return { asks, notes: pilots(asker, this.notes(asker)) ? { pk: this.steward.pk(), beings: this.steward.beings() } : {} };
-  }
-
-  async own(args: JsonObject): Promise<JsonObject> {
-    if (!text(args.id)) return { error: 'id is text' };
-    return (await this.stance.occupants.invite(args.id, { owner: true })) ?? { error: 'id taken' };
-  }
-
-  disown(args: JsonObject): JsonObject {
-    if (!text(args.id) || this.stance.occupants.notes(args.id)?.owner !== true) return { error: 'no such owner' };
-    this.stance.occupants.remove(args.id);
-    return { disowned: args.id };
-  }
-
-  async boot(args: JsonObject): Promise<JsonObject> {
-    if (!text(args.key) || !text(args.class)) return { error: 'key and class are text' };
-    if (args.class.startsWith(KIT) && args.class !== PILOT) return { error: 'no such class' };
-    const out = await this.steward.boot(args.key, args.class);
-    return out === 'booted' ? { booted: args.key } : { error: out };
-  }
-
-  unboot(args: JsonObject): JsonObject | Promise<JsonObject> {
-    return text(args.being) && this.steward.unboot(args.being) ? { unbooted: args.being } : { error: 'no such being' };
-  }
-
-  public(args: JsonObject): JsonObject {
-    if (args.key !== null && !text(args.key)) return { error: 'key is text or null' };
-    return this.steward.publish(args.key) ? { public: args.key } : { error: 'no such being' };
-  }
-
-  async invite(args: JsonObject): Promise<JsonObject> {
-    if (!text(args.being) || !text(args.id) || (args.notes !== undefined && !object(args.notes))) return { error: 'being and id are text, notes an object' };
-    const invitation = await this.steward.invite(args.being, args.id, args.notes ?? {});
-    return invitation ?? { error: 'not invited' };
-  }
-
-  async ask(args: JsonObject): Promise<JsonObject> {
-    if ((args.being !== undefined && !text(args.being)) || (args.method !== undefined && !text(args.method)) || (args.args !== undefined && !object(args.args))) {
-      return { error: 'being and method are text, args an object' };
-    }
-    const out = await this.steward.ask(args.being ?? null, args.method, args.args ?? {});
-    if (isSilence(out)) return { error: 'silence' };
-    if (isWord(out)) return { error: told(out) as string };
-    return { answer: out };
-  }
-}

package/src/ward/ward.ts

@@ -1,328 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The ward: one door, one partition, and the beings behind the door. It
-// unpacks from its seed, its memory and a catalogue of classes, the
-// ward-being first and every other being from her own row, and it stands
-// what is behind its door for `quo/`.
-import { readValue, writeValue } from '../crypto/index.ts';
-import { Door, readInvitation, WardKey, type Behind, type Choice, type Invitation, type Payload } from '../quo/index.ts';
-import type { Carrier, Clock, Entropy, Rows } from '../contract/index.ts';
-import { digest, isSilence, isWord, kindOf, OWNER, silence, WARD, word, type Answer, type Asker, type BeingClass, type BeingLike, type JsonObject, type Reply } from '../being/index.ts';
-import { Partition, PartitionRelations, type BeingRow } from './partition.ts';
-import { DEPTH, WardStance, type Inside } from './stance.ts';
-import { WardBeing, type Steward, type WardBeingStance } from './ward-being.ts';
-
-// Where a ward finds a class by the kind its row keeps.
-export interface Catalogue {
-  classOf(kind: string): BeingClass | undefined;
-}
-
-export type WardParts = {
-  readonly seed: Uint8Array | string;
-  readonly memory: Rows;
-  readonly catalogue: Catalogue;
-  readonly entropy: Entropy;
-  readonly clock: Clock;
-  readonly carrier: Carrier;
-  // The ward-being: `WardBeing`, or a being that extends it.
-  readonly root?: (stance: WardBeingStance) => WardBeing;
-  // An invitation on the dock, taken by the ward-being under `dock` when
-  // she holds no such standing yet.
-  readonly dock?: Invitation;
-  // Where the ward is reached, and where a ward it takes an invitation of
-  // is reached. A ward alone is reached nowhere and learns nothing.
-  readonly routes?: Routes;
-};
-
-export interface Routes {
-  reach(): readonly string[];
-  learn(ward: string, at: readonly string[]): Promise<void>;
-}
-
-// The standing every hosted ward's ward-being holds on the dock.
-export const DOCK = 'dock';
-
-// A ward-being that lends to her own ward's beings, as the dock does.
-export interface Lender {
-  offer(contract: string): Promise<Invitation | null>;
-  withdraw(contract: string, heir: string): Promise<void>;
-}
-const lends = (being: unknown): being is Lender => typeof (being as Partial<Lender>).offer === 'function';
-
-type Birth = 'booted' | 'key taken' | 'no such class' | 'threw at birth';
-type Resident = { being: BeingLike; row: BeingRow; stance: WardStance };
-
-class RootStance extends WardStance implements WardBeingStance {
-  readonly steward: Steward;
-  constructor(inside: Inside, row: BeingRow, steward: Steward) {
-    super(inside, WARD, row);
-    this.steward = steward;
-  }
-}
-
-export class Ward implements Behind, Inside {
-  readonly key: WardKey;
-  readonly partition: Partition;
-  readonly door: Door;
-  readonly clock: Clock;
-  readonly #parts: WardParts;
-  readonly #residents = new Map<string, Resident>();
-  readonly #birthing = new Set<string>();
-
-  private constructor(parts: WardParts, key: WardKey) {
-    this.#parts = parts;
-    this.key = key;
-    this.clock = parts.clock;
-    this.partition = new Partition(parts.memory);
-    this.door = new Door(key, new PartitionRelations(this.partition), this, parts.entropy.drawer);
-  }
-
-  // The ward-being first, then every being her row names. A class the
-  // catalogue lacks, or one that throws, leaves that being absent and her
-  // row as it was.
-  static async unpack(parts: WardParts): Promise<Ward> {
-    const ward = new Ward(parts, await WardKey.from(parts.seed));
-    if (!ward.partition.being(WARD)) {
-      ward.partition.beings[WARD] = { class: '', cells: {}, occupants: {}, standings: {} };
-      ward.partition.told(WARD);
-      ward.partition.toldHead();
-    }
-    const own = ward.partition.being(WARD)!;
-    const stance = new RootStance(ward, own, ward.#steward);
-    const being = parts.root ? parts.root(stance) : new WardBeing(stance);
-    own.class = kindOf(being.constructor);
-    ward.#residents.set(WARD, { being, row: own, stance });
-    // The standing on the dock is kept at once: its heir is spent, so a
-    // restart before the ward's first keep would find no way back.
-    if (parts.dock && !Object.hasOwn(own.standings, DOCK) && (await stance.standings.take(DOCK, parts.dock)) !== null && !(await ward.partition.kept())) {
-      throw new Error('the standing on the dock was not kept');
-    }
-    for (const [key, row] of Object.entries(ward.partition.beings)) {
-      const C = key === WARD ? undefined : parts.catalogue.classOf(row.class);
-      if (C) ward.#bear(key, row, C);
-    }
-    return ward;
-  }
-
-  get pk(): string {
-    return this.key.pk;
-  }
-
-  get draw() {
-    return this.#parts.entropy.drawer;
-  }
-
-  get wardBeing(): WardBeing {
-    return this.#residents.get(WARD)!.being as WardBeing;
-  }
-
-  // The being standing under a key, for the harbor's own faculties.
-  being(key: string): BeingLike | undefined {
-    return this.#residents.get(key)?.being;
-  }
-
-  // Every being her row names, of the class the catalogue now resolves for
-  // her kind: an absent being is born, and one whose class a module
-  // replaced is born again of the new class on the stance she holds, so
-  // her relations and their lanes stay hers. A new class that throws at
-  // birth leaves her as she was.
-  bearAnew(): void {
-    for (const [key, row] of Object.entries(this.partition.beings)) {
-      const C = key === WARD ? undefined : this.#parts.catalogue.classOf(row.class);
-      const resident = this.#residents.get(key);
-      if (!C || resident?.being.constructor === C) continue;
-      if (!resident) {
-        this.#bear(key, row, C);
-        continue;
-      }
-      try {
-        resident.being = new C(resident.stance);
-      } catch {
-        continue;
-      }
-    }
-  }
-
-  // The unsealed ask: the ward-being, asked by whoever holds this ward.
-  // It reaches every being of the ward through the ward-being, so every
-  // row is put back where the memory refuses.
-  async root(method?: string, args: JsonObject = {}): Promise<Answer> {
-    return this.#kept(Object.keys(this.partition.beings), () => this.#answer(WARD, { id: OWNER }, method, args));
-  }
-
-  // An answer, kept. Where the memory refuses, what the beings wrote is put
-  // back and the answer is silence. What their relations stand on is not
-  // put back: a relation's keys move only as far as its standing follows.
-  async #kept(keys: readonly string[], work: () => Promise<Answer>): Promise<Answer> {
-    const before = keys.flatMap((key): [string, JsonObject, string][] => {
-      const row = this.partition.being(key);
-      return row ? [[key, row.cells, JSON.stringify(row.cells)]] : [];
-    });
-    const out = await work();
-    if (await this.partition.kept()) return out;
-    for (const [key, cells, was] of before) {
-      if (JSON.stringify(cells) === was) continue;
-      for (const k of Object.keys(cells)) delete cells[k];
-      for (const [k, v] of Object.entries(JSON.parse(was) as JsonObject)) Object.defineProperty(cells, k, { value: v, enumerable: true, writable: true, configurable: true });
-      this.partition.told(key);
-    }
-    return silence;
-  }
-
-  // Behind: the zero head reaches the public being, an heir the being that
-  // invited it.
-  get zero(): boolean {
-    const key = this.partition.head.public;
-    return key !== null && this.#residents.has(key);
-  }
-
-  async answer(heir: string | null, p: Payload): Promise<Choice> {
-    const bound = heir === null ? undefined : this.partition.head.bind[heir];
-    const key = heir === null ? this.partition.head.public : bound?.being;
-    const asker: Asker = bound ? { id: bound.id } : {};
-    const args = p.args === undefined ? {} : readValue(p.args, DEPTH + 1);
-    if (key === null || key === undefined || typeof args !== 'object' || args === null || Array.isArray(args)) return { silence: true };
-    const out = await this.#kept([key], () => this.#answer(key, asker, p.method, args));
-    const object = isSilence(out) || isWord(out) ? undefined : writeValue(out, DEPTH);
-    if (object === undefined) return { silence: true };
-    const being = this.#residents.get(key)?.being;
-    const seen = p.method === undefined || !being?.describe ? null : await digest(being.describe(asker));
-    return { object, seen };
-  }
-
-  // Every path that reaches a being's answer. A throw, a word out of her,
-  // or nothing at all is silence.
-  async #answer(key: string, asker: Asker, method: string | undefined, args: JsonObject): Promise<Answer> {
-    const resident = this.#residents.get(key);
-    if (!resident) return silence;
-    let out: Reply;
-    try {
-      out = await resident.being.answer(asker, method, args);
-    } catch {
-      return silence;
-    }
-    return out === undefined || isWord(out) ? silence : out;
-  }
-
-  // Inside: what every stance of this ward stands on.
-
-  // One path through a door for every ask, this ward's own included.
-  async send(pk: string, bytes: Uint8Array): Promise<Uint8Array | null> {
-    if (pk === this.pk) return (await this.door.arrive(bytes)).bytes;
-    return this.#parts.carrier.carry(pk, bytes);
-  }
-
-  // A lend: the ward-being lends herself, as the dock does, or asks the dock
-  // through her standing.
-  async offer(contract: string): Promise<Invitation | null> {
-    const own = this.#residents.get(WARD)!;
-    if (lends(own.being)) return own.being.offer(contract);
-    const out = await own.stance.standings.get(DOCK)?.ask('lend', { contract });
-    return readInvitation((out as { invitation?: unknown } | undefined)?.invitation);
-  }
-
-  async retract(contract: string, heir: string): Promise<void> {
-    const own = this.#residents.get(WARD)!;
-    if (lends(own.being)) return own.being.withdraw(contract, heir);
-    await own.stance.standings.get(DOCK)?.ask('retract', { contract, heir });
-  }
-
-  reach(): readonly string[] {
-    return this.#parts.routes?.reach() ?? [];
-  }
-
-  learn(ward: string, at: readonly string[]): Promise<void> {
-    return this.#parts.routes?.learn(ward, at) ?? Promise.resolve();
-  }
-
-  live(key: string, row: BeingRow): boolean {
-    return this.#residents.get(key)?.row === row;
-  }
-
-  // A being boots another of this ward. With an id, the new being invites
-  // her maker under the maker's key, and the maker takes it under id; a
-  // relation that could not be made unmakes the new being.
-  async boot(maker: string, className: string, key: string, id?: string): Promise<string | null> {
-    if ((await this.#make(key, className)) !== 'booted') return null;
-    if (id === undefined) return key;
-    const invitation = await this.#residents.get(key)!.stance.occupants.invite(maker);
-    const taken = invitation ? await this.#residents.get(maker)?.stance.standings.take(id, invitation) : null;
-    if (taken) return key;
-    this.#unboot(key);
-    return null;
-  }
-
-  async #make(key: string, className: string): Promise<Birth> {
-    if (key === '' || key === WARD || this.partition.being(key) || this.#birthing.has(key)) return 'key taken';
-    const C = this.#parts.catalogue.classOf(className);
-    if (!C) return 'no such class';
-    this.#birthing.add(key);
-    try {
-      const row: BeingRow = { class: className, cells: {}, occupants: {}, standings: {} };
-      this.partition.beings[key] = row;
-      if (!this.#bear(key, row, C)) {
-        delete this.partition.beings[key];
-        return 'threw at birth';
-      }
-      this.partition.told(key);
-      return 'booted';
-    } finally {
-      this.#birthing.delete(key);
-    }
-  }
-
-  #bear(key: string, row: BeingRow, C: BeingClass): boolean {
-    const stance = new WardStance(this, key, row);
-    try {
-      this.#residents.set(key, { being: new C(stance), row, stance });
-      return true;
-    } catch {
-      this.#residents.delete(key);
-      return false;
-    }
-  }
-
-  #unboot(key: string): boolean {
-    const row = key === WARD ? undefined : this.partition.being(key);
-    if (!row) return false;
-    for (const { heir } of Object.values(row.occupants)) {
-      this.door.remove(heir);
-      delete this.partition.head.bind[heir];
-    }
-    if (this.partition.head.public === key) this.partition.head.public = null;
-    delete this.partition.beings[key];
-    this.#residents.delete(key);
-    this.partition.toldHead();
-    this.partition.told(key);
-    return true;
-  }
-
-  // What the ward-being asks of her ward.
-  readonly #steward: Steward = {
-    pk: () => this.pk,
-    classOf: (name) => this.#parts.catalogue.classOf(name),
-    beings: () => {
-      const out: ReturnType<Steward['beings']> = {};
-      for (const [key, row] of Object.entries(this.partition.beings)) {
-        if (key !== WARD) out[key] = { class: row.class, public: this.partition.head.public === key, absent: !this.#residents.has(key) };
-      }
-      return out;
-    },
-    boot: (key, className) => this.#make(key, className),
-    unboot: (key) => this.#unboot(key),
-    publish: (key) => {
-      if (key !== null && (key === WARD || !this.partition.being(key))) return false;
-      this.partition.head.public = key;
-      this.partition.toldHead();
-      return true;
-    },
-    invite: (being, id, notes): Promise<Invitation | null> => {
-      const resident = being === WARD ? undefined : this.#residents.get(being);
-      return resident ? resident.stance.occupants.invite(id, notes) : Promise.resolve(null);
-    },
-    ask: (being, method, args) => {
-      const key = being ?? this.partition.head.public;
-      if (key === null || key === WARD) return Promise.resolve(word('unreached'));
-      return this.#answer(key, being === null ? {} : { id: OWNER }, method, args);
-    },
-  };
-}