nervur 0.16.0 → 0.17.0

package/src/ward/ward.ts

@@ -0,0 +1,378 @@
+// SPDX-License-Identifier: Apache-2.0
+// A ward that is its own ward. Booted by a harbor with one object, the
+// ground, and hands back two pointers: the door and the ask. Boots itself as
+// the first being in its own map, and every being it later instantiates gets
+// a stance built by the same code. Mints every key, seals every ask that
+// leaves, opens every one that arrives.
+import { silence, isSilence, unreached, isWord, word } from '../being/silence.ts';
+import { OWNER } from '../being/types.ts';
+import type { Asker, BeingLike, Cells, JsonObject, Reply, Stance, Wanted, Word } from '../being/types.ts';
+import type { Ground, WardPointers } from './ground.ts';
+import { at, drop, open, put, emptyBind, emptyCells, HEAD, MINTED, type Bind, type Partition, type StandingKeys } from './partition.ts';
+import { Heirs } from './heirs.ts';
+import { makeDoor, type Door } from './door.ts';
+import { buildStance } from './stance.ts';
+import { ownerAnswer } from './owner.ts';
+import { allow, within, LATE } from './allowance.ts';
+import { beingKey, openReply, sealAsk, wardKey, wardPadlock, wardSignPk, type ReplyPayload, type WardKey } from './seal.ts';
+import { unhex } from './arithmetic.ts';
+import { guardCells, unguarded, cellFault } from './cells.ts';
+
+// One being of the ward as the ward holds her: her door, her bind table, her
+// stance and her cells. The owner's asks see this and nothing more. Not
+// `Booted`, which is a harbor's word for a ward it started: this is a ward's
+// word for a being living in it, and the two are one module apart.
+export type Resident = Door & { bind: Bind; stance: Stance; cells: Cells & { class?: string } };
+
+// The ward. One call in, two pointers out. Async because keys are derived.
+export async function Ward(ground: Ground): Promise<WardPointers> {
+  const w = await Self.boot(ground);
+  return { door: w.door, ask: w.ask };
+}
+
+class Self implements BeingLike {
+  readonly key: WardKey;
+  readonly pk: string;
+  readonly g: Ground;
+  readonly p: Partition;
+  readonly heirs: Heirs;
+  readonly doors = new Map<string, Resident>();
+  readonly #birthing = new Set<string>(); // keys whose constructor is running: taken, though no door and no row say so yet
+  readonly door: WardPointers['door'];
+  readonly ask: WardPointers['ask'];
+
+  static async boot(ground: Ground): Promise<Self> {
+    return new Self(ground, await wardKey(ground.seed));
+  }
+
+  private constructor(ground: Ground, key: WardKey) {
+    this.g = ground;
+    this.key = key;
+    this.pk = key.pk;
+    this.p = open(ground.memory); // the partition: the ward's own state, and every being's row
+    // Opening is itself a write: a memory nobody has written comes back with
+    // a version stamped on it and the ward's own tables under it. A ward that
+    // said nothing here would have every being of it kept and the head that
+    // says which version they are written under kept by nobody, so the next
+    // boot would read a partition of no version and refuse it.
+    this.#wrote(HEAD);
+    this.heirs = new Heirs(this.p, () => this.#wrote(HEAD));
+    this.door = makeDoor(
+      key,
+      this.heirs,
+      this.doors,
+      () => this.p.public,
+      (n) => ground.random(n),
+      () => this.#keep(),
+    ); // pointer one
+    this.#boot(this.pk, () => this); // the ward's ward is itself
+    // a restart is silent: every being in the cells is constructed again, unasked.
+    // A throw on a boot the owner asked for is that boot's error, and nothing
+    // half-lives. This boot nobody asked for, and there is nobody to hand an
+    // error to. Any constructor may throw, a default that is not a value, an
+    // author's mistake, a shape she does not recognise after an upgrade, and
+    // let through here it is one being taking down the ward and every other
+    // being in it, on a restart. She is absent instead: no door, so silence
+    // at the door, and her cells sit untouched, waiting for the run that can
+    // read them. Her row stays hers: nobody boots another class over it, the
+    // owner sees her as absent, and the owner may unboot her.
+    for (const [k, c] of Object.entries(this.p.beings)) {
+      const className = c.class;
+      if (k === this.pk || !className) continue;
+      try {
+        this.#boot(k, (stance) => this.g.instantiate(className, stance));
+      } catch {
+        /* she is not here this run. the ward is, and so is everyone else. */
+      }
+    }
+    // pointer two. the owner. the same answer every named asker gets, asker filled in as owner.
+    this.ask = async (method, args = {}) => {
+      try {
+        const out = await this.answer({ id: OWNER }, method, args as JsonObject);
+        // The same question the door asks, in the same place: after she has
+        // answered and before the owner holds the answer. Silence is what a
+        // failed ask says here, so a store that refused is silence, and the
+        // owner reads it as it reads every other ask that did not take.
+        if (!(await this.#keep().catch(() => false))) return silence;
+        return isSilence(out) || isWord(out) ? silence : out;
+      } catch {
+        return silence;
+      }
+    };
+  }
+
+  // ---- the ward as a being. asked only by its owners: the root, through
+  // the ask pointer, and its occupants, through the door, whom only the root
+  // can invite. A stranger cannot be a named asker here, because the door
+  // names nobody the ward did not bind.
+  async answer(asker: Asker, method?: string, args: JsonObject = {}): Promise<Reply> {
+    // Nobody is not an owner. The door names nobody the ward did not bind, so
+    // the only way here unnamed is a partition that says the ward is its own
+    // public being, which no owner ask will write. Silence, not an error
+    // object: an unnamed asker is a stranger, and a stranger hears one thing.
+    if (asker.id === undefined) return silence;
+    return ownerAnswer(
+      {
+        pk: this.pk,
+        doors: this.doors,
+        absent: () => this.#absent(),
+        publicKey: () => this.p.public,
+        instantiate: (className, key) => this.#instantiate(className, key),
+        unboot: (key) => this.#unboot(key),
+        setPublic: (key) => {
+          this.p.public = key;
+          this.#wrote(HEAD);
+        },
+      },
+      asker,
+      method,
+      args,
+    );
+  }
+
+  // ---- ward functions. on the object. no stance reaches them.
+
+  // The partition was written, and which row of it: a being by her key, or
+  // the head. The harbor is told, and nothing more: what it does with the
+  // word is its own, and the ward never learns. Every write says its row,
+  // because a harbor told only that something moved must keep all of it, and
+  // a being's row is the one part of a partition that grows without limit.
+  #wrote(row: string): void {
+    this.g.wrote?.(row);
+  }
+
+  // Whether what was written is kept, asked once at the end of an arrival
+  // and never during one. A harbor that keeps nothing was never going to
+  // refuse anything, so its silence here is yes: a ward driven with no store
+  // under it answers exactly as it did before a harbor could say no.
+  async #keep(): Promise<boolean> {
+    return this.g.keep ? await this.g.keep() : true;
+  }
+
+  // The rows no door holds this run: beings whose class threw at birth or
+  // is not the harbor's to give. Key to class.
+  #absent(): Record<string, string | null> {
+    const out: Record<string, string | null> = {};
+    for (const [k, c] of Object.entries(this.p.beings)) if (k !== this.pk && !this.doors.has(k)) put(out, k, c.class ?? null);
+    return out;
+  }
+
+  // A new being under a key nobody holds. A key with a row in the partition
+  // is booted, whether a door holds it this run or not: an absent being's
+  // row is hers, with every relation in it, and no class is booted over it.
+  // A throw at birth is that boot's refusal and nothing half-lives; the
+  // ward says which, since the owner hears objects.
+  #instantiate(className: string, key: string): Resident | 'threw' | null {
+    // The three refusals are read before the constructor runs, and the
+    // constructor can reach the stance and boot: a class that boots its own
+    // key from inside itself would pass all three, since neither its door nor
+    // its row exists yet, and the two objects would then share one row. A key
+    // being born is a key taken, for as long as the birth lasts.
+    if (typeof key !== 'string' || typeof className !== 'string' || !key || this.doors.has(key) || at(this.p.beings, key) || this.#birthing.has(key)) return null;
+    let door: Resident | null;
+    this.#birthing.add(key);
+    try {
+      door = this.#boot(key, (stance) => this.g.instantiate(className, stance));
+    } catch {
+      return 'threw';
+    } finally {
+      this.#birthing.delete(key);
+    }
+    if (!door) return null;
+    unguarded(door.cells).class = className; // so a restart finds her. the ward's key, written behind her guard
+    this.#wrote(key);
+    return door;
+  }
+
+  // The inverse of boot, and the only way a being leaves a ward. Her
+  // relations go first and by the same calls she would have used herself,
+  // so every occupant hears `removed` at the door from the keys it kept,
+  // rather than meeting a being who is simply not there any more. What is
+  // left after that is her cells and her bind table, and they go with her:
+  // a row naming a being no door holds would be read on the next restart
+  // and boot her again. An absent being leaves the same way: she has no
+  // stance to speak for her, so the ward closes her heirs itself.
+  #unboot(key: string): string[] | null {
+    if (key === this.pk) return null;
+    const door = this.doors.get(key);
+    const cells = door?.cells ?? at(this.p.beings, key);
+    if (!cells) return null;
+    const ids = (r: unknown) => (r !== null && typeof r === 'object' ? Object.keys(r) : []);
+    const occupants = ids(cells.occupants),
+      standings = ids(cells.standings);
+    if (door) {
+      for (const id of occupants) door.stance.occupants.remove(id);
+      for (const id of standings) door.stance.standings.remove(id);
+    } else {
+      const bind = at(this.p.bind, key);
+      for (const heir of Object.values(bind?.occupants ?? {})) this.heirs.close(heir);
+    }
+    // A ward whose public being is gone answers arrivals for no heir with
+    // silence, as a ward that never had one does.
+    if (this.p.public === key) this.p.public = null;
+    drop(this.p.beings, key);
+    drop(this.p.bind, key);
+    this.doors.delete(key);
+    this.#wrote(key); // she is gone, and her row goes with her
+    this.#wrote(HEAD); // her heirs were closed, and the public being may have been her
+    return [...occupants, ...standings];
+  }
+
+  // Nothing is written until there is somebody to write it for: a class the
+  // harbor does not know makes no being, and a boot that made nobody must
+  // leave the partition as it found it.
+  //
+  // `make` is who to build with the stance this raises. Two callers and two
+  // makers: the ground's `instantiate` for a being of the ward, and the ward
+  // itself, which is the first being in its own map and is already made.
+  #boot(key: string, make: (stance: Stance) => BeingLike | null): Resident | null {
+    const cells = guardCells(at(this.p.beings, key) ?? emptyCells(), () => this.#wrote(key));
+    const bind = at(this.p.bind, key) ?? emptyBind();
+    const stance: Stance = buildStance(
+      {
+        pk: this.pk,
+        // This stance, not merely this key: unboot and boot again under the
+        // same key makes a new being, and the old stance is not hers.
+        live: () => this.doors.get(key)?.stance === stance,
+        mintKey: (b) => this.#mintKey(b, key),
+        openHeir: (heir, being, id) => this.heirs.open(heir, being, id),
+        closeHeir: (heir) => this.heirs.close(heir),
+        send: (b, keys, method, args, wanted) => this.#send(b, keys, method, args, wanted, key),
+        // A throw at birth is null to her, not a throw in her method: she asked
+        // for a being and got none, and her own answer is still hers to give.
+        instantiate: (className, k) => {
+          const made = this.#instantiate(className, k);
+          return made && made !== 'threw' ? made.key : null;
+        },
+        // The two halves of a maker's way back, each the ward's own call: the
+        // being made mints an occupant for her maker, and a relation that
+        // never came about takes her out again.
+        relate: async (k, id) => (await this.doors.get(k)?.stance.occupants.invite(id)) ?? null,
+        unmake: (k) => void this.#unboot(k),
+        // What this device lends this ward's beings. The ward knocks and takes
+        // inside the harbor's own call and reads nothing in the value: which
+        // names there are, which ward may ask for one, and what becomes of one
+        // she did not take, is the harbor's and no word of the ward.
+        lend: async (name, take) => (await this.g.lend?.(name, take)) ?? false,
+        wrote: () => this.#wrote(key),
+      },
+      key,
+      cells,
+      bind,
+    );
+    const being = make(stance);
+    if (!being || typeof being.answer !== 'function') return null; // a being is anything with an answer, and nothing without one
+    put(this.p.beings, key, cells);
+    put(this.p.bind, key, bind);
+    const door: Resident = { key, cells, bind, stance, being };
+    this.doors.set(key, door);
+    this.#wrote(key);
+    return door;
+  }
+
+  async #mintKey(bind: Bind, row: string): Promise<{ seed: string; pk: string }> {
+    const k = await beingKey(this.g.random(32));
+    // The last few she minted, and no more. A relation rotates on every ask,
+    // so a list of all of them is a partition that grows for as long as she
+    // keeps talking and can never be written down. Nothing is read from this
+    // but the keys of the moment.
+    bind.minted.push(k.pk);
+    if (bind.minted.length > MINTED) bind.minted.splice(0, bind.minted.length - MINTED);
+    this.#wrote(row);
+    return k;
+  }
+
+  // One send for every door, the ward's own included. Mine: never leaves.
+  // Not mine: carry. Signs as the standing's current key, announces its
+  // next, seals to the far ward, opens the reply with the ephemeral secret,
+  // and rotates to the announced key once the far door has answered under
+  // the current one.
+  async #send(bind: Bind, keys: StandingKeys, method: string | undefined, args: JsonObject, wanted: Wanted | undefined, row: string): Promise<ReplyPayload | typeof silence | Word> {
+    // The harbor is told a call is in flight for as long as this one lasts,
+    // and told again when it ends. Everything this ward writes between the
+    // two is half of a relation: the count taken here, the key rotated when
+    // the reply opens, and whatever the being writes on either side of her
+    // own ask. A harbor may write those rows down; what it may not do is put
+    // the ward back to them.
+    const lower = this.g.calling?.();
+    try {
+      return await this.#sent(bind, keys, method, args, wanted, row);
+    } finally {
+      lower?.();
+    }
+  }
+
+  async #sent(bind: Bind, keys: StandingKeys, method: string | undefined, args: JsonObject, wanted: Wanted | undefined, row: string): Promise<ReplyPayload | typeof silence | Word> {
+    // What she asked for, held to what this ward allows. Asking for nothing is
+    // the default, and asking for more than the ceiling is the ceiling: budget
+    // is granted by a ward, never minted by a being.
+    const budget = allow(wanted);
+    const by = (await beingKey(unhex(keys.current))).pk;
+    // A public being is reached without a heir, and the door keeps nothing for
+    // whoever asked: no key it vouched for, so nothing to announce and nothing
+    // to rotate to. A standing on her signs with one key for life. Every other
+    // ask announces its next: there is no send that does not.
+    if (keys.next === null && keys.heir !== null) keys.next = (await this.#mintKey(bind, row)).seed;
+    const next = keys.next === null ? null : (await beingKey(unhex(keys.next))).pk;
+    // Her count for this relation, one higher every call and never reused. The
+    // far door honours each number once. One relation sends one at a time, so
+    // the numbers leave in the order they were taken.
+    const seq = (keys.seq += 1);
+    // Named here, before the bytes go out, and not at the end with the keys.
+    // The far door honours a number once, and it honours it before this side
+    // hears anything back: a reply that is lost, a wait that ran out, a road
+    // that took the bytes and said nothing, all end this call before the end
+    // of it is reached. A count named only there is a count a restart forgets
+    // while the door remembers, and she then speaks a number that door has
+    // already spent, which it refuses as the replay it cannot tell it from.
+    // So the rule is the send and not the reply: what she spoke under is
+    // written down because she spoke it.
+    this.#wrote(row);
+    // Args that will not go through the seal are args that never left. A
+    // being holds three answers and a throw is not one of them, so an ask
+    // that cannot be sealed is told what is true of it: no door was reached.
+    // One object of values, by the rule her cells keep and the far door
+    // reads: a Date would arrive as a string, a function would not arrive at
+    // all, a list or a string would be refused as a stranger's bytes, and
+    // she would never know the far being was asked something other than
+    // what she said.
+    if (args === null || typeof args !== 'object' || Array.isArray(args) || cellFault(args, 'args') !== null) return unreached();
+    let sealed;
+    try {
+      sealed = await sealAsk(keys.heir, { by, next, seq, time: budget.time, method, args }, unhex(keys.current), wardPadlock(keys.ward), this.g.random(32));
+    } catch {
+      return unreached();
+    }
+    const { bytes, ephemeral } = sealed;
+    // The wait is bounded here, and again around the lane in the stance. Two
+    // bounds and not one, because they end two different things: the stance's
+    // ends the wait a being is held in, and this one ends the occupancy of the
+    // relation's lane. A being holds three answers and a wait that does not
+    // end is none of them, and a lane nobody ever leaves is a relation the
+    // next ask never reaches. Only a bound on the wire breaks the second, and
+    // taking it out would leave one quiet far side holding the lane for good.
+    // What comes back late is not read.
+    //
+    // A wait that ran out is `late`, never unreached. Unreached promises
+    // nothing was delivered and is safe to retry; a bound that expired knows
+    // no such thing, because the far door may have heard and be working still.
+    //
+    // A harbor answers bytes or nothing. One that throws instead has answered
+    // nothing in a louder voice, and is read as nothing: no door was reached.
+    const carried = (keys.ward === this.pk ? this.door(new Uint8Array(bytes)).then((r) => r.bytes) : this.g.carry(keys.ward, bytes)).then(
+      (b) => b,
+      () => undefined,
+    );
+    const out = await within(budget.time, carried);
+    if (out === LATE) return word('late');
+    if (out === undefined) return unreached(); // nothing came back. no door was reached.
+    const reply = await openReply(out, ephemeral, wardSignPk(keys.ward));
+    if (!reply) return silence; // did not open, or not from that ward: not Quo's bytes
+    if ('object' in reply && keys.next !== null) {
+      keys.current = keys.next; // the far door holds `next` as announced. move to it.
+      keys.next = null;
+    }
+    this.#wrote(row); // the count moved, and the keys may have
+    return reply;
+  }
+}

package/index.js

@@ -1,17 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The name, and what stands under it. This package is the unscoped twin of
-// the `@nervur-org` scope: `import ... from 'nervur'` is the library, and
-// `npx nervur` is the dock's command. It pins the two exactly, because a
-// name that stands for the kit stands for one version of it.
-
-export * from '@nervur-org/nervur';
-
-/** The published packages, and what each one is. */
-export const PACKAGES = Object.freeze({
-  '@nervur-org/nervur': 'the library: harbor, ward and being, the first kit of Quo',
-  '@nervur-org/dock': 'what every estate on Quo needs and nobody writes twice',
-  '@nervur-org/ui': 'the kit: one token contract, one baseline, the primitives',
-});
-
-/** Where to read what the kit is. */
-export const HOMEPAGE = 'https://nervur.org';

package/nervur.js

@@ -1,5 +0,0 @@
-#!/usr/bin/env node
-// SPDX-License-Identifier: Apache-2.0
-// `nervur`: the dock's command under the kit's name. Every subcommand is the
-// dock's; this file only finds it.
-import '@nervur-org/dock/cli';