nervur 0.19.2 → 0.20.0

package/src/folder/index.ts

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: Apache-2.0
+// A harbor on a disk, for local proof: `nervur/folder`, the one entry that
+// names a platform.
+//
+//   <root>/<ward>/seed               the ward's seed, as hex
+//   <root>/<ward>/ward.json          the ward's head
+//   <root>/<ward>/<key>/being.json   one being: class, cells, relations
+//
+// A folder name is the ward's name or the being's key, escaped, so no name
+// reaches outside its folder. A file is written whole, beside itself and
+// then renamed over, so a crash leaves the last kept copy. Seeds are plain
+// files: custody that seals them is a terrain's, in the dock.
+import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { hex, isHex, unhex } from '../crypto/index.ts';
+import { Custody, Memory, type Entropy, type Rows } from '../contract/index.ts';
+import { HEAD_ROW } from '../ward/index.ts';
+
+const HEAD = 'ward.json';
+const BEING = 'being.json';
+
+export const folderName = (name: string): string => encodeURIComponent(name).replaceAll('.', '%2E').replaceAll('*', '%2A') || '%';
+const nameOf = (folder: string): string => (folder === '%' ? '' : decodeURIComponent(folder));
+
+const missing = (e: unknown): boolean => (e as { code?: string }).code === 'ENOENT';
+
+const readJson = async (path: string): Promise<unknown> => {
+  try {
+    return JSON.parse(await readFile(path, 'utf8')) as unknown;
+  } catch (e) {
+    if (missing(e)) return undefined;
+    throw e;
+  }
+};
+
+const writeWhole = async (path: string, text: string): Promise<void> => {
+  await writeFile(`${path}.next`, text, { mode: 0o600 });
+  await rename(`${path}.next`, path);
+};
+
+class FolderRows implements Rows {
+  readonly rows: Record<string, unknown>;
+  readonly #dir: string;
+  readonly #told = new Set<string>();
+  #line: Promise<boolean> = Promise.resolve(true);
+
+  constructor(dir: string, rows: Record<string, unknown>) {
+    this.#dir = dir;
+    this.rows = rows;
+  }
+
+  told(row: string): void {
+    this.#told.add(row);
+  }
+
+  // Every row told since the last keep, written in order, one keep at a time.
+  kept(): Promise<boolean> {
+    const rows = [...this.#told];
+    this.#told.clear();
+    this.#line = this.#line.then(() => this.#write(rows)).catch(() => false);
+    return this.#line;
+  }
+
+  async #write(told: string[]): Promise<boolean> {
+    await mkdir(this.#dir, { recursive: true, mode: 0o700 });
+    const beings = (this.rows.beings ?? {}) as Record<string, unknown>;
+    for (const row of told) {
+      if (row === HEAD_ROW) {
+        await writeWhole(join(this.#dir, HEAD), JSON.stringify(this.rows.ward ?? null));
+        continue;
+      }
+      const dir = join(this.#dir, folderName(row));
+      if (!Object.hasOwn(beings, row)) {
+        await rm(dir, { recursive: true, force: true });
+        continue;
+      }
+      await mkdir(dir, { recursive: true, mode: 0o700 });
+      await writeWhole(join(dir, BEING), JSON.stringify(beings[row]));
+    }
+    return true;
+  }
+}
+
+export class FolderMemory extends Memory {
+  readonly root: string;
+
+  constructor(root: string) {
+    super();
+    this.root = root;
+  }
+
+  // The rows as the disk holds them now.
+  async open(name: string): Promise<Rows> {
+    const dir = join(this.root, folderName(name));
+    const rows: Record<string, unknown> = {};
+    const head = await readJson(join(dir, HEAD));
+    if (head !== undefined) rows.ward = head;
+    const beings: Record<string, unknown> = {};
+    const entries = await readdir(dir, { withFileTypes: true }).catch((e: unknown) => (missing(e) ? [] : Promise.reject(e)));
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const row = await readJson(join(dir, entry.name, BEING));
+      if (row !== undefined) beings[nameOf(entry.name)] = row;
+    }
+    if (head !== undefined || Object.keys(beings).length > 0) rows.beings = beings;
+    return new FolderRows(dir, rows);
+  }
+}
+
+export class FolderCustody extends Custody {
+  readonly root: string;
+  readonly #entropy: Entropy;
+
+  constructor(root: string, entropy: Entropy) {
+    super();
+    this.root = root;
+    this.#entropy = entropy;
+  }
+
+  async seed(name: string): Promise<Uint8Array> {
+    const dir = join(this.root, folderName(name));
+    const path = join(dir, 'seed');
+    const kept = await readFile(path, 'utf8').catch((e: unknown) => (missing(e) ? undefined : Promise.reject(e)));
+    if (kept !== undefined) {
+      const text = kept.trim();
+      if (!isHex(text, 32)) throw new Error(`${path} is not a seed`);
+      return unhex(text);
+    }
+    const seed = this.#entropy.draw(32);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await writeFile(path, `${hex(seed)}\n`, { mode: 0o600, flag: 'wx' });
+    return seed;
+  }
+}

package/src/harbor/dock.ts

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0
+// The dock: the box ward's ward-being. Beside the root's asks of every ward,
+// she opens faculties, hosts wards, and lends each contract a faculty
+// fulfils to the wards she hosts.
+//
+//   open    { key, class }      a faculty stands in the box ward, and the
+//                               dock holds a standing on her under her key
+//   host    { ward }            a hosted ward stands, holding a standing on
+//                               the dock
+//   lend    { contract }        asked by a hosted ward: an offer from a
+//                               faculty that fulfils the contract
+//   retract { contract, heir }  an offer that was not taken
+import { Faculty, type Asker, type AskSpec, type Invitation, type JsonObject } from '../being/index.ts';
+import { readInvitation } from '../quo/index.ts';
+import { ownerAsk, WardBeing, type Lender, type WardBeingStance } from '../ward/index.ts';
+
+// What the dock asks of her harbor.
+export interface Hosting {
+  host(name: string, invitation: Invitation): Promise<boolean>;
+}
+
+export const BOX = 'box';
+const text = (v: unknown): v is string => typeof v === 'string';
+const hosted: AskSpec['for'] = (_: Asker, notes: JsonObject | undefined) => notes?.hosted === true;
+
+export class Dock extends WardBeing implements Lender {
+  static override cells: JsonObject = { hosted: [] };
+  static override asks: Record<string, AskSpec> = {
+    ...WardBeing.asks,
+    open: ownerAsk('a faculty of this harbor', { required: ['key', 'class'] }),
+    host: ownerAsk('a ward this harbor hosts', { required: ['ward'] }),
+    lend: { description: 'an offer from a faculty fulfilling a contract', input: { type: 'object', required: ['contract'] }, for: hosted },
+    retract: { description: 'an offer that was not taken', input: { type: 'object', required: ['contract', 'heir'] }, for: hosted },
+  };
+
+  readonly #hosting: Hosting;
+
+  constructor(stance: WardBeingStance, hosting: Hosting) {
+    super(stance);
+    this.#hosting = hosting;
+  }
+
+  get hosted(): string[] {
+    return [...(this.cells.hosted as string[])];
+  }
+
+  async open(args: JsonObject): Promise<JsonObject> {
+    if (!text(args.key) || !text(args.class)) return { error: 'key and class are text' };
+    if (!Faculty.fulfils(this.steward.classOf(args.class))) return { error: 'no such faculty' };
+    const opened = await this.stance.boot(args.class, args.key, args.key);
+    return opened === null ? { error: 'not opened' } : { opened };
+  }
+
+  async host(args: JsonObject): Promise<JsonObject> {
+    const name = args.ward;
+    if (!text(name) || name === BOX || this.hosted.includes(name)) return { error: 'no such ward to host' };
+    const invitation = await this.stance.occupants.invite(name, { hosted: true });
+    if (invitation === null) return { error: 'not hosted' };
+    if (!(await this.#hosting.host(name, invitation))) {
+      this.stance.occupants.remove(name);
+      return { error: 'not hosted' };
+    }
+    (this.cells.hosted as string[]).push(name);
+    return { hosted: name };
+  }
+
+  async lend(args: JsonObject): Promise<JsonObject> {
+    if (!text(args.contract)) return { error: 'contract is text' };
+    const invitation = await this.offer(args.contract);
+    return invitation ? { invitation } : { error: 'nothing lent' };
+  }
+
+  async retract(args: JsonObject): Promise<JsonObject> {
+    if (!text(args.contract) || !text(args.heir)) return { error: 'contract and heir are text' };
+    await this.withdraw(args.contract, args.heir);
+    return { retracted: args.heir };
+  }
+
+  // Lender: the first standing faculty that fulfils the contract offers.
+  async offer(contract: string): Promise<Invitation | null> {
+    for (const key of this.#fulfilling(contract)) {
+      const out = await this.stance.standings.get(key)?.ask('offer');
+      const invitation = readInvitation((out as { invitation?: unknown } | undefined)?.invitation);
+      if (invitation) return invitation;
+    }
+    return null;
+  }
+
+  async withdraw(contract: string, heir: string): Promise<void> {
+    for (const key of this.#fulfilling(contract)) await this.stance.standings.get(key)?.ask('retract', { heir });
+  }
+
+  #fulfilling(contract: string): string[] {
+    const beings = this.steward.beings();
+    return this.stance.standings.ids().filter((key) => {
+      const being = beings[key];
+      const C = being && !being.absent ? this.steward.classOf(being.class) : undefined;
+      return Faculty.fulfils(C) && Faculty.contracts(C).includes(contract);
+    });
+  }
+}

package/src/harbor/harbor.ts

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: Apache-2.0
+// The harbor: the onion, unpacked from a terrain and a catalogue.
+//
+//   1. custody and memory     the box ward's seed and rows, from the terrain
+//   2. the box ward           unpacked as every ward is, its ward-being the dock
+//   3. the faculties          the box ward's beings, each from her own row
+//   4. the hosted wards       as the dock's cells list them
+//   5. the beings             in each ward, each from her own row
+//
+// Genesis and wake are one path: empty memory unpacks a box ward holding
+// the dock alone, and the root's asks write the rest.
+import type { Answer, BeingClass, Invitation, JsonObject } from '../being/index.ts';
+import { Carrier } from '../contract/index.ts';
+import { DOCK, Ward, type WardParts } from '../ward/index.ts';
+import { BOX, Dock, type Hosting } from './dock.ts';
+import { Registry } from './registry.ts';
+import type { Terrain } from './terrain.ts';
+
+export class Harbor extends Carrier implements Hosting {
+  readonly terrain: Terrain;
+  readonly registry: Registry;
+  readonly #wards = new Map<string, Ward>();
+
+  private constructor(terrain: Terrain, registry: Registry) {
+    super();
+    this.terrain = terrain;
+    this.registry = registry;
+  }
+
+  static async open(terrain: Terrain, classes: readonly BeingClass[]): Promise<Harbor> {
+    const harbor = new Harbor(terrain, new Registry(classes));
+    await harbor.#unpack(BOX, undefined, (stance) => new Dock(stance, harbor));
+    for (const name of harbor.dock.hosted) await harbor.#unpack(name);
+    return harbor;
+  }
+
+  get box(): Ward {
+    return this.#wards.get(BOX)!;
+  }
+
+  get dock(): Dock {
+    return this.box.wardBeing as Dock;
+  }
+
+  ward(name: string): Ward | undefined {
+    return this.#wards.get(name);
+  }
+
+  get names(): string[] {
+    return [...this.#wards.keys()].filter((name) => name !== BOX);
+  }
+
+  // The unsealed ask on the box ward: what a command line carries.
+  root(method?: string, args?: JsonObject): Promise<Answer> {
+    return this.box.root(method, args);
+  }
+
+  holds(pk: string): boolean {
+    return this.#door(pk) !== undefined;
+  }
+
+  // Bytes for one of this harbor's doors, or nothing.
+  async arrive(pk: string, bytes: Uint8Array): Promise<Uint8Array | null> {
+    const ward = this.#door(pk);
+    return ward ? (await ward.door.arrive(bytes)).bytes : null;
+  }
+
+  // Carrier: this harbor's own doors first, then the terrain's.
+  carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null> {
+    return this.holds(pk) ? this.arrive(pk, bytes) : this.terrain.carrier.carry(pk, bytes);
+  }
+
+  // Hosting: a ward the dock hosts stands now.
+  async host(name: string, invitation: Invitation): Promise<boolean> {
+    if (this.#wards.has(name)) return false;
+    try {
+      await this.#unpack(name, invitation);
+    } catch {
+      return false;
+    }
+    if (this.#wards.get(name)!.wardBeing.stance.standings.get(DOCK)) return true;
+    this.#wards.delete(name);
+    return false;
+  }
+
+  async #unpack(name: string, dock?: Invitation, root?: WardParts['root']): Promise<void> {
+    const { entropy, clock, custody, memory } = this.terrain;
+    const ward = await Ward.unpack({
+      seed: await custody.seed(name),
+      memory: await memory.open(name),
+      catalogue: this.registry,
+      entropy,
+      clock,
+      carrier: this,
+      ...(dock ? { dock } : {}),
+      ...(root ? { root } : {}),
+    });
+    this.#wards.set(name, ward);
+  }
+
+  #door(pk: string): Ward | undefined {
+    for (const ward of this.#wards.values()) if (ward.pk === pk) return ward;
+    return undefined;
+  }
+}

package/src/harbor/index.ts

@@ -1,20 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
-// nervur/harbor — the Ground contract and the harbors. The only
-// place in the package that may know a wire, and it knows one on the
-// standard surface alone: fetch and WebSocket. MemoryHarbor knows none: it
-// is one process talking to itself, where every ward assertion is made.
-export { MemoryHarbor, type Booted, type WardFactory } from './memory.ts';
-export { Harbor, DEFAULT_CODE, type Hosted, type Bound, type Loader } from './core.ts';
-export { dial, type Dialer } from './dial.ts';
-export { MemoryStore, values, rowsOf, type Store, type Kept, type WardRecord } from './store.ts';
-// What a store keeping a ward in rows needs: the name of the row that is not
-// a being, and the partition back from the rows it was cut into.
-export { HEAD, fromRows, rowsIn } from '../ward/partition.ts';
-export { request, Socket, SUITE, REFUSED, type Reach, type Carry, type Line, type Announce } from './reach.ts';
-export type { Ground, WardPointers, Memory } from '../ward/ground.ts';
-export { BOX, OFFER, RETRACT, volatile } from '../ward/ground.ts';
-// The box as one being, and the acts a harbor runs to stand it.
-export { Box, BOX_SEED, BOX_ASKS, stand, hold, offerTo, roll } from './box.ts';
-// What a harbor builds a ground out of. Convenience, never contract: a kit
-// writing its own harbor may write these three again.
-export { maker, entropy, learnPk } from '../ward/ground.ts';
+// The onion: a terrain, a registry, the dock, and the harbor.
+export { BOX, Dock, type Hosting } from './dock.ts';
+export { Harbor } from './harbor.ts';
+export { Registry } from './registry.ts';
+export { Terrain } from './terrain.ts';

package/src/harbor/registry.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+// The catalogue a program hands its harbor, indexed by class name. It
+// resolves a name a row keeps, and decides nothing about what stands.
+import type { BeingClass } from '../being/index.ts';
+import type { Catalogue } from '../ward/index.ts';
+
+export class Registry implements Catalogue {
+  readonly #classes = new Map<string, BeingClass>();
+
+  constructor(classes: readonly BeingClass[]) {
+    for (const C of classes) {
+      if (this.#classes.has(C.name) && this.#classes.get(C.name) !== C) throw new Error(`two classes are named ${C.name}`);
+      this.#classes.set(C.name, C);
+    }
+  }
+
+  classOf(name: string): BeingClass | undefined {
+    return this.#classes.get(name);
+  }
+}

package/src/harbor/terrain.ts

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: Apache-2.0
+// Where a harbor runs. A terrain hands the harbor one body for each
+// contract the onion cannot unpack from cells.
+import type { Carrier, Clock, Custody, Entropy, Memory } from '../contract/index.ts';
+
+export abstract class Terrain {
+  abstract readonly entropy: Entropy;
+  abstract readonly clock: Clock;
+  abstract readonly custody: Custody;
+  abstract readonly memory: Memory;
+  // What reaches a ward pk this harbor does not hold.
+  abstract readonly carrier: Carrier;
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+// `nervur`: what a stranger writes a world with. It imports no platform, so
+// it runs wherever JavaScript runs. A disk is `nervur/folder`.
+
+// Beings, faculties, and what they are told.
+export { Being, canonical, digest, Faculty, isSilence, isWord, OWNER, silence, told, WARD, word } from './being/index.ts';
+export type { Answer, Ask, Asker, AskSpec, BeingClass, BeingLike, Blueprint, Invitation, Json, JsonObject, Occupants, Reply, Schema, Silence, Stance, Standing, Standings, Wanted, Word, WordName } from './being/index.ts';
+export { readInvitation } from './quo/index.ts';
+
+// What a terrain gives a harbor.
+export { Carrier, Clock, Custody, Entropy, Memory, type Rows } from './contract/index.ts';
+
+// Wards and the ward-being.
+export { CEILING, DEFAULT, DEPTH, ownerAsk, pilots, WardBeing, type Steward, type WardBeingStance } from './ward/index.ts';
+
+// The onion.
+export { BOX, Dock, Harbor, Registry, Terrain } from './harbor/index.ts';
+
+// The pointer dock: a whole world in one process.
+export { CryptoEntropy, HeldCustody, NoCarrier, PointerCarrier, PointerTerrain, SystemClock, VolatileMemory, World, type PointerParts } from './pointer/index.ts';

package/src/pointer/bodies.ts

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: Apache-2.0
+// The pointer terrain's bodies: each contract fulfilled in one process,
+// with nothing beyond JavaScript.
+import { Clock, Custody, Entropy, Memory, type Rows } from '../contract/index.ts';
+
+export class CryptoEntropy extends Entropy {
+  draw(length: number): Uint8Array {
+    return globalThis.crypto.getRandomValues(new Uint8Array(length));
+  }
+}
+
+export class SystemClock extends Clock {
+  now(): number {
+    return Date.now();
+  }
+  wait(ms: number): { done: Promise<void>; cancel(): void } {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const done = new Promise<void>((resolve) => (timer = setTimeout(resolve, ms)));
+    return { done, cancel: () => clearTimeout(timer) };
+  }
+}
+
+// Seeds drawn once per name and held by this object.
+export class HeldCustody extends Custody {
+  readonly #entropy: Entropy;
+  readonly #seeds = new Map<string, Uint8Array>();
+  constructor(entropy: Entropy) {
+    super();
+    this.#entropy = entropy;
+  }
+  seed(name: string): Promise<Uint8Array> {
+    let seed = this.#seeds.get(name);
+    if (!seed) this.#seeds.set(name, (seed = this.#entropy.draw(32)));
+    return Promise.resolve(seed);
+  }
+}
+
+// Rows that live as long as this object: opening a name again gives the
+// same rows, which is what a restart in one process finds.
+export class VolatileMemory extends Memory {
+  readonly #wards = new Map<string, Rows>();
+  open(name: string): Promise<Rows> {
+    let rows = this.#wards.get(name);
+    if (!rows) this.#wards.set(name, (rows = { rows: {}, told: () => {}, kept: () => Promise.resolve(true) }));
+    return Promise.resolve(rows);
+  }
+}

package/src/pointer/index.ts

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// The pointer dock: a whole world with `nervur` alone.
+export { CryptoEntropy, HeldCustody, SystemClock, VolatileMemory } from './bodies.ts';
+export { NoCarrier, PointerCarrier, PointerTerrain, World, type PointerParts } from './world.ts';

package/src/pointer/world.ts

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+// The pointer world: harbors in one process, an address book from ward pk
+// to harbor that stands in for the internet, and weather between them. A
+// restart drops a harbor and opens a new one on the terrain the world
+// keeps for it, so only what its memory kept comes back.
+import type { BeingClass } from '../being/index.ts';
+import { Carrier, type Clock, type Custody, type Entropy, type Memory } from '../contract/index.ts';
+import { Harbor, Terrain } from '../harbor/index.ts';
+import { CryptoEntropy, HeldCustody, SystemClock, VolatileMemory } from './bodies.ts';
+
+// A carrier that reaches no one: a harbor alone.
+export class NoCarrier extends Carrier {
+  carry(): Promise<Uint8Array | null> {
+    return Promise.resolve(null);
+  }
+}
+
+// Bytes to whichever harbor of a world holds the ward pk.
+export class PointerCarrier extends Carrier {
+  readonly #world: World;
+  constructor(world: World) {
+    super();
+    this.#world = world;
+  }
+  carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null> {
+    return this.#world.carry(pk, bytes);
+  }
+}
+
+export type PointerParts = { entropy?: Entropy; clock?: Clock; custody?: Custody; memory?: Memory; carrier?: Carrier };
+
+export class PointerTerrain extends Terrain {
+  readonly entropy: Entropy;
+  readonly clock: Clock;
+  readonly custody: Custody;
+  readonly memory: Memory;
+  readonly carrier: Carrier;
+
+  constructor(parts: PointerParts = {}) {
+    super();
+    this.entropy = parts.entropy ?? new CryptoEntropy();
+    this.clock = parts.clock ?? new SystemClock();
+    this.custody = parts.custody ?? new HeldCustody(this.entropy);
+    this.memory = parts.memory ?? new VolatileMemory();
+    this.carrier = parts.carrier ?? new NoCarrier();
+  }
+}
+
+type Place = { harbor: Harbor; terrain: Terrain; classes: readonly BeingClass[] };
+
+export class World {
+  readonly #places = new Map<string, Place>();
+  // Harbors the world reaches no one in, nor anyone out of.
+  readonly cut = new Set<string>();
+
+  // A harbor of this world. `parts` replaces the pointer bodies, a folder's
+  // memory and custody among them.
+  async harbor(name: string, classes: readonly BeingClass[], parts: Omit<PointerParts, 'carrier'> = {}): Promise<Harbor> {
+    if (this.#places.has(name)) throw new Error(`a harbor named ${name} stands`);
+    const terrain = new PointerTerrain({ ...parts, carrier: new PointerCarrier(this) });
+    const harbor = await Harbor.open(terrain, classes);
+    this.#places.set(name, { harbor, terrain, classes });
+    return harbor;
+  }
+
+  get(name: string): Harbor {
+    const place = this.#places.get(name);
+    if (!place) throw new Error(`no harbor named ${name}`);
+    return place.harbor;
+  }
+
+  // The harbor opened again on its own terrain, with the classes it was
+  // made with unless others are named. `parts` replaces bodies of the
+  // terrain, as a new process would build them over the same disk.
+  async restart(name: string, classes?: readonly BeingClass[], parts?: Omit<PointerParts, 'carrier'>): Promise<Harbor> {
+    const place = this.#places.get(name);
+    if (!place) throw new Error(`no harbor named ${name}`);
+    const t = place.terrain;
+    const terrain = parts ? new PointerTerrain({ entropy: t.entropy, clock: t.clock, custody: t.custody, memory: t.memory, ...parts, carrier: t.carrier }) : t;
+    const harbor = await Harbor.open(terrain, classes ?? place.classes);
+    this.#places.set(name, { ...place, harbor, terrain });
+    return harbor;
+  }
+
+  carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null> {
+    for (const [name, { harbor }] of this.#places) {
+      if (harbor.holds(pk)) return this.cut.has(name) ? Promise.resolve(null) : harbor.arrive(pk, bytes);
+    }
+    return Promise.resolve(null);
+  }
+}