@quo-systems/quo 0.2.9 → 0.2.11

package/src/ward/stance.ts

@@ -1,25 +1,38 @@
 // SPDX-License-Identifier: Apache-2.0
 // The one stance builder. Used for every being the ward boots. Nothing
 // outer is in what she holds: ids in, values out, keys in the bind table.
-import { silence, isSilence, isUnreached, isWord, word } from '../being/silence.ts';
+import { silence, isSilence, isWord, word, wordOf } from '../being/silence.ts';
 import { digest } from '../being/digest.ts';
-import { RESERVED_IDS } from '../being/types.ts';
+import { RESERVED_IDS, isBlueprint } from '../being/types.ts';
 import type { Answer, Cells, Invitation, JsonObject, Silence, Stance, Standing, Standings, Wanted, Word } from '../being/types.ts';
-import { at, put, drop, type Bind, type StandingKeys } from './partition.ts';
+import { at, put, drop, prune, type Bind, type StandingKeys } from './partition.ts';
 import { allow, within, LATE } from './allowance.ts';
-import { isWardPk, type ReplyPayload } from './seal.ts';
+import { isHex, isWardPk, type ReplyPayload } from './seal.ts';
+import { cellFault } from './cells.ts';
 
 // What the stance needs from its ward, and no more.
 export type Inside = {
   pk: string;
+  // Is the being this stance was built for still one of the ward's? Unboot
+  // takes her door and her rows, but a class whose code is still running
+  // holds the stance closure, and everything in it still points at live
+  // objects. Read before every call, so a being taken out reaches nothing.
+  live(): boolean;
   mintKey(bind: Bind): Promise<{ seed: string; pk: string }>; // a fresh signing key, recorded as minted
   openHeir(heir: string, being: string, id: string): void;
   closeHeir(heir: string): void;
   // one send for every destination. the far door's reply, silence, or unreached.
-  // signs as keys.current, announces keys.next (minting one if asked), and rotates keys on an answer.
-  send(bind: Bind, keys: StandingKeys, announce: boolean, method: string | undefined, args: JsonObject, wanted: Wanted | undefined): Promise<ReplyPayload | Silence | Word>;
+  // signs as keys.current, mints and announces keys.next where the relation has
+  // a heir to rotate on, and rotates keys on an answer.
+  send(bind: Bind, keys: StandingKeys, method: string | undefined, args: JsonObject, wanted: Wanted | undefined): Promise<ReplyPayload | Silence | Word>;
   // a new being of this ward, as the owner's boot makes one. the key, or null.
-  instantiate(key: string, className: string): string | null;
+  instantiate(className: string, key: string): string | null;
+  // mint an occupant on a being of this ward, for the being who made her.
+  relate(key: string, id: string): Promise<Invitation | null>;
+  // take a being of this ward out again, with every relation she holds.
+  unmake(key: string): void;
+  // the bind table was written: a record put, dropped or moved on.
+  wrote(): void;
 };
 
 // An invitation as it travels: the far ward's pk, the heir pk, the heir's secret seed. Or just the ward, for its public being.
@@ -45,7 +58,7 @@ export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bin
     const i = inv as SealedInvitation;
     if (!i || typeof i !== 'object' || !isWardPk(i.ward)) return false;
     if (i.heir === undefined) return i.secret === undefined;
-    return typeof i.heir === 'string' && typeof i.secret === 'string' && /^[0-9a-f]{64}$/.test(i.heir) && /^[0-9a-f]{64}$/.test(i.secret);
+    return isHex(i.heir) && isHex(i.secret);
   };
 
   // One relation, one ask at a time. The rotation is a conversation: a send
@@ -72,9 +85,9 @@ export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bin
   // Every ask a being makes, bounded. The bound is outside the lane on
   // purpose: an ask that waits its turn behind a relation that comes back
   // round never reaches a send, and a bound that only watched the wire would
-  // never see it hang. A bound that ran out is silence, never unreached:
-  // unreached promises nothing was delivered and is safe to ask again, and a
-  // wait that gave up knows no such thing.
+  // never see it hang. A bound that ran out is the word late, never
+  // unreached: unreached promises nothing was delivered and is safe to ask
+  // again, and a wait that gave up knows no such thing.
   //
   // The bell rings before the work is reached, too: an ask that was still
   // waiting its turn when the wait ran out is never sent. Sent then, it would
@@ -89,53 +102,96 @@ export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bin
     return out === LATE ? word('late') : out;
   };
 
-  const send = async (keys: StandingKeys, method: string | undefined, args: JsonObject, wanted: Wanted | undefined, rec?: Cells['standings'][string]): Promise<Answer> => {
-    const r = await inside.send(bind, keys, true, method, args, wanted);
-    if (isSilence(r) || isWord(r)) return r;
-    if ('silence' in r) return silence;
-    if ('quo' in r) return word(r.quo); // the far door's word for her, sealed to her lid
-    if (rec && method !== undefined && r.seen !== null) rec.seen = r.seen; // the digest rode along
-    return r.object;
+  // What one send came back as, read in one place for every path that sends.
+  // A reply that opened and was signed by the far ward is the door speaking,
+  // whatever it said: an object, its silence, or a word. Bytes that were not
+  // Quo's, late and unreached are not the door speaking, and say nothing
+  // about whether it heard.
+  type Read = { answer: Answer; door: boolean; seen: string | null };
+  const read = (r: ReplyPayload | Silence | Word): Read => {
+    if (isSilence(r) || isWord(r)) return { answer: r, door: false, seen: null };
+    if ('silence' in r) return { answer: silence, door: true, seen: null };
+    if ('quo' in r) return { answer: word(r.quo), door: true, seen: null }; // the far door's word for her, sealed to her lid
+    return { answer: r.object, door: true, seen: r.seen };
   };
+  // Whether the door spent the heir this send spoke under. An object, the
+  // door's silence and threw all mean it was honoured. A refusal word wrote
+  // nothing and says so. Anything that is not the door speaking says nothing.
+  const honoured = (r: Read): boolean => r.door && !(isWord(r.answer) && wordOf(r.answer) !== 'threw');
+  const answered = (r: Read): boolean => r.door && !isSilence(r.answer) && !isWord(r.answer);
 
-  const knocking = async (inv: SealedInvitation, method: string | undefined, args: JsonObject, wanted: Wanted | undefined): Promise<Answer> => {
+  // The ask is bounded twice with one budget, once around the lane and once
+  // around the wire, and the two bells are microseconds apart. A reply that
+  // lands between them is a reply she was already told was late: its keys are
+  // rotated, since the far door rotated too and nothing may un-rotate that,
+  // but nothing of it is written into her cells. What she was handed is the
+  // last word on what she saw.
+  const send = async (keys: StandingKeys, method: string | undefined, args: JsonObject, wanted: Wanted | undefined, rec?: Cells['standings'][string], live: () => boolean = () => true): Promise<Answer> => {
+    const r = read(await inside.send(bind, keys, method, args, wanted));
+    if (rec && method !== undefined && r.seen !== null && live()) rec.seen = r.seen; // the digest rode along
+    return r.answer;
+  };
+
+  const knocking = async (inv: SealedInvitation, method: string | undefined, args: JsonObject, wanted: Wanted | undefined, live: () => boolean = () => true): Promise<Answer> => {
     const name = nameOf(inv);
+    // Taken while this knock waited its turn: the relation lives in the
+    // standing now and speaks on its lane, under its keys and its count.
+    const taken = takenAs(name);
+    if (taken !== undefined) {
+      const keys = at(bind.standings, taken);
+      if (!keys) return word('dropped');
+      return lane(`ask:${taken}`, () => asking(taken, keys, at(cells.standings, taken), method, args, wanted, live));
+    }
     // her own key for this relation, minted once: rotation two. reused if she knocks again.
     const k = (bind.knocks[name] ??= { current: (await inside.mintKey(bind)).seed, next: null, spoke: false, sent: false, seq: 0 });
-    // the first knock on a heir speaks as the heir, the key the inviter handed out, and announces her own.
-    // once bytes have come back, the heir is spent whatever they said, and her own key speaks.
-    // She sent once as the heir and nothing came back. Either the door heard,
-    // spent the heir and rotated to the key she announced, or nothing arrived
-    // and the heir still stands. Only the far door knows, and it will not say.
+    prune(bind.knocks, bind.answered); // this one is the newest, so it stays and the oldest never answered goes
+    // The first knock on a heir speaks as the heir, the key the inviter
+    // handed out, and announces her own. Once the door has honoured it the
+    // heir is spent, whatever she then said, and her own key speaks; a heir
+    // spent once stays spent.
+    //
+    // She sent once as the heir and the door did not speak: nothing came
+    // back, or bytes that were not Quo's, or the wait ran out. Either the
+    // door heard, spent the heir and rotated to the key she announced, or
+    // nothing arrived and the heir still stands. Only the far door knows,
+    // and it will not say.
     //
     // So she asks, and the asking tells her. Under her own key: if the door
-    // heard, that key is the one it admits, and she is answered. If it did
-    // not, the key means nothing there, the ask is refused, and a refusal at
-    // that door writes nothing — the heir is untouched and still speaks. Then
-    // she knocks as the heir, as she would have. One extra round trip in the
-    // one case where a reply was lost, and the relation is not stranded.
+    // heard, that key is the one it admits, and she is answered, or told the
+    // door's word. If it did not, the key means nothing there, the ask is
+    // refused, and a refusal at that door writes nothing: the heir is
+    // untouched and still speaks. Then she knocks as the heir, as she would
+    // have. One extra round trip in the one case where a reply was lost, and
+    // the relation is not stranded.
     //
     // No stranger gains anything by it: whoever holds the invitation could
     // always knock as the heir, and her own key is admitted only where the
     // door already bound it to her.
     if (inv.heir !== undefined && !k.spoke && k.sent) {
       const own: StandingKeys = { ward: inv.ward, heir: inv.heir, current: k.current, next: k.next, seq: k.seq };
-      const r = await inside.send(bind, own, true, method, args, wanted);
+      const r = read(await inside.send(bind, own, method, args, wanted));
       k.seq = own.seq;
       k.current = own.current;
       k.next = own.next;
-      if (isUnreached(r)) return r; // still nothing. she knows no more than before.
-      if (!isSilence(r) && !isWord(r) && 'object' in r) {
-        k.spoke = true; // it was heard the first time, and this is the answer
-        bind.answered[name] = true;
-        return r.object;
+      inside.wrote();
+      if (!r.door) {
+        // Nothing the door said. Unreached and late are hers to hear now; bytes
+        // that were not Quo's leave her where she was, and the heir is tried.
+        if (!isSilence(r.answer)) return r.answer;
+      } else if (!isSilence(r.answer)) {
+        // The door spoke to her own key, so it heard the first knock: this is
+        // the answer, or the door's word for her. Its silence alone cannot be
+        // told from a refusal, so silence is followed by the knock as the heir,
+        // which the door then refuses if it had heard, and she hears silence.
+        k.spoke = true;
+        if (answered(r)) bind.answered[name] = true;
+        return r.answer;
       }
-      // Refused. The door never heard her, so the heir is still hers to spend.
     }
 
     const first = inv.heir !== undefined && !k.spoke;
     const keys: StandingKeys = first ? { ward: inv.ward, heir: inv.heir!, current: inv.secret!, next: k.current, seq: k.seq } : { ward: inv.ward, heir: inv.heir ?? null, current: k.current, next: k.next, seq: k.seq };
-    const r = await inside.send(bind, keys, true, method, args, wanted);
+    const r = read(await inside.send(bind, keys, method, args, wanted));
     k.sent = true; // bytes went out. whether they arrived is the far door's to know.
     // The number she spoke under, and the key she announced, kept whoever
     // answered and kept when nobody did. A reply lost on the way back is a
@@ -146,16 +202,10 @@ export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bin
       k.current = keys.current;
       k.next = keys.next;
     }
-    if (isUnreached(r)) return r; // nothing came back. she does not know whether it was heard.
-    // The heir is spent once the door honoured it, whatever she then said: an
-    // object, silence, or that she threw. A refusal wrote nothing, and says
-    // so by its word, so the heir still speaks and the next knock is as it.
-    k.spoke = !(!isSilence(r) && !isWord(r) && 'quo' in r && r.quo !== 'threw');
-    if (isSilence(r) || isWord(r)) return r;
-    if ('silence' in r) return silence;
-    if ('quo' in r) return word(r.quo);
-    bind.answered[name] = true;
-    return r.object;
+    if (honoured(r)) k.spoke = true;
+    if (answered(r)) bind.answered[name] = true;
+    inside.wrote();
+    return r.answer;
   };
 
   // The id she took this relation under, if she took it. One relation is one
@@ -164,16 +214,24 @@ export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bin
   const keyName = (k: StandingKeys) => (k.heir === null ? `public:${k.ward}` : `${k.ward}:${k.heir}`);
   const takenAs = (name: string): string | undefined => Object.keys(bind.standings).find((id) => keyName(bind.standings[id]) === name);
 
+  // A being the ward has taken out reaches nothing through the stance she
+  // still holds. Her relations went with her, so every one of them reads as
+  // dropped, and nothing she asks for is made: a heir written here would name
+  // a being no door holds, and an id minted here would be handed to whoever
+  // is booted under her key next.
+  const gone = () => !inside.live();
+
   const calls = {
     knock: async (inv: Invitation, method?: string, args: JsonObject = {}, wanted?: Wanted): Promise<Answer> => {
+      if (gone()) return word('dropped');
       if (!valid(inv)) return word('invitation'); // S1. nothing is sent
       // She may knock again, and after take that knock is an ask: the relation
       // has one home, so it answers on the standing's lane, under the
       // standing's keys and its count. A second lane here would speak for the
       // same relation, and the two would refuse each other.
       const id = takenAs(nameOf(inv));
-      if (id !== undefined) return bounded(wanted, (live) => lane(`ask:${id}`, () => (live() ? asking(id, bind.standings[id], cells.standings[id], method, args, wanted) : Promise.resolve(word('late')))));
-      return bounded(wanted, (live) => lane(`knock:${nameOf(inv)}`, () => (live() ? knocking(inv, method, args, wanted) : Promise.resolve(word('late')))));
+      if (id !== undefined) return standingAt(id).ask(method, args, wanted);
+      return bounded(wanted, (live) => lane(`knock:${nameOf(inv)}`, () => (live() ? knocking(inv, method, args, wanted, live) : Promise.resolve(word('late')))));
     },
     // Take consumes. Until now the relation lived in the knock record, under
     // the ward and the heir; from now it lives in the standing, under her id.
@@ -193,7 +251,7 @@ export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bin
     // ask on it is refused. The relation she took correctly would be dead
     // because a second knock on the same invitation was careless.
     take: async (id: string, inv: Invitation): Promise<string | null> => {
-      if (!valid(inv)) return null;
+      if (gone() || !valid(inv)) return null;
       const name = nameOf(inv);
       return lane(`knock:${name}`, () => {
         if (!bind.answered[name]) return Promise.resolve(null);
@@ -206,12 +264,15 @@ export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bin
         put(cells.standings, id, { id, digest: null, blueprint: null, seen: null });
         delete bind.knocks[name];
         delete bind.answered[name];
+        inside.wrote();
         return Promise.resolve(id);
       });
     },
     remove: (id: string): void => {
+      if (gone()) return;
       drop(cells.standings, id);
       drop(bind.standings, id);
+      inside.wrote();
     },
   };
 
@@ -221,20 +282,31 @@ export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bin
     // issued while the standing stood is answered even if she drops it in
     // the next line. Waiting for the lane is not a reason to lose it.
     ask: (method?: string, args: JsonObject = {}, wanted?: Wanted): Promise<Answer> => {
+      if (gone()) return Promise.resolve(word('dropped') as Answer);
       const keys = at(bind.standings, id);
       if (!keys) return Promise.resolve(word('dropped') as Answer); // S2. she dropped it between one line and the next
       const rec = at(cells.standings, id);
-      return bounded(wanted, (live) => lane(`ask:${id}`, () => (live() ? asking(id, keys, rec, method, args, wanted) : Promise.resolve(word('late')))));
+      return bounded(wanted, (live) => lane(`ask:${id}`, () => (live() ? asking(id, keys, rec, method, args, wanted, live) : Promise.resolve(word('late')))));
     },
   });
 
-  const asking = async (id: string, keys: StandingKeys, rec: Cells['standings'][string] | undefined, method: string | undefined, args: JsonObject, wanted: Wanted | undefined): Promise<Answer> => {
-    const out = await send(keys, method, args, wanted, rec);
+  // The record an ask writes into is the one it was issued on. A standing
+  // dropped and re-taken under the same id while the ask was in flight is
+  // another relation, and the blueprint that came back is not hers.
+  const asking = async (id: string, keys: StandingKeys, rec: Cells['standings'][string] | undefined, method: string | undefined, args: JsonObject, wanted: Wanted | undefined, live: () => boolean = () => true): Promise<Answer> => {
+    const out = await send(keys, method, args, wanted, rec, live);
     if (method === undefined && !isSilence(out) && !isWord(out)) {
-      const here = at(cells.standings, id);
-      if (here) {
-        here.blueprint = out as never;
-        here.digest = here.seen = await digest(out);
+      // A blueprint her cells cannot keep, nested past the bound or carrying
+      // a key no harbor writes, is not Quo's bytes: silence, and nothing written.
+      if (cellFault(out, 'blueprint') !== null) return silence;
+      if (rec && live() && at(cells.standings, id) === rec) {
+        // Read as a blueprint before it is kept as one. A far describe is
+        // somebody else's code and may answer anything; what is not a
+        // blueprint is not written as one, and she holds no blueprint for
+        // that relation rather than one a side would walk and break on. The
+        // answer itself is hers either way: it is returned below, unread.
+        rec.blueprint = isBlueprint(out) ? out : null;
+        rec.digest = rec.seen = await digest(out);
       }
     }
     return out;
@@ -251,26 +323,53 @@ export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bin
     cells,
     // A being may make. The ward refuses what it refuses the owner: a key
     // already booted, a class the harbor does not hold, and a throw at birth
-    // leaves the partition as it was. Reaching into the being made is not
-    // offered here: that is the owner's, and she has no relation to her
-    // until one is invited and taken like any other.
-    boot: (className: string, key: string): string | null => inside.instantiate(key, className),
+    // leaves the partition as it was. Reaching into another is still the
+    // owner's alone: what a maker may have is a relation to what she made,
+    // by naming an id, and it is made the way every relation is. The being
+    // made mints an occupant for her maker under the maker's own key, so she
+    // knows who made her by that name and by nothing else; her maker knocks,
+    // takes it under the id she gave, and holds one standing like any other.
+    // Nothing half-lives: a relation that could not be made unmakes the
+    // being, who is a moment old and known to nobody.
+    boot: async (className: string, made: string, id?: string): Promise<string | null> => {
+      if (gone()) return null;
+      if (id !== undefined && (reserved(id) || at(cells.standings, id) || at(cells.occupants, id))) return null;
+      const born = inside.instantiate(className, made);
+      if (born === null || id === undefined) return born;
+      const inv = await inside.relate(born, key);
+      if (inv) {
+        const out = await calls.knock(inv);
+        if (!isSilence(out) && !isWord(out) && (await calls.take(id, inv)) === id) return born;
+      }
+      inside.unmake(born);
+      return null;
+    },
     occupants: {
       // rotation one: the ward mints the occupant's first key and gives the secret away.
       // it keeps the pk beside the id and nothing else. the invitation IS the key.
-      invite: async (id: string): Promise<Invitation | null> => {
-        if (reserved(id) || at(cells.occupants, id) || at(cells.standings, id)) return null;
-        put(cells.occupants, id, { id, notes: {} });
+      invite: async (id: string, notes?: JsonObject): Promise<Invitation | null> => {
+        if (gone() || reserved(id) || at(cells.occupants, id) || at(cells.standings, id)) return null;
+        // The key first, and nothing written until it exists: a record put
+        // before the mint would be a record a remove in the meantime drops
+        // with no heir to close, and the heir opened after it would name an
+        // id nobody holds, for a later invite under that id to resurrect.
         const k = await inside.mintKey(bind);
+        if (reserved(id) || at(cells.occupants, id) || at(cells.standings, id)) return null; // taken while the key was minted
+        // The notes are the terms the inviter minted under, hers to read on her
+        // gate. She may write more later; nobody outside ever writes them.
+        put(cells.occupants, id, { id, notes: notes ? { ...notes } : {} });
         inside.openHeir(k.pk, key, id);
         put(bind.occupants, id, k.pk);
+        inside.wrote();
         return { ward: inside.pk, heir: k.pk, secret: k.seed };
       },
       remove: (id: string): void => {
+        if (gone()) return;
         drop(cells.occupants, id);
         const heir = at(bind.occupants, id);
         drop(bind.occupants, id);
         if (heir) inside.closeHeir(heir); // the heir dies with the id
+        inside.wrote();
       },
     },
     standings,