@quo-systems/quo 0.2.9 → 0.2.11

package/dist/ward/stance.js

@@ -1,12 +1,13 @@
 // 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.js';
+import { silence, isSilence, isWord, word, wordOf } from '../being/silence.js';
 import { digest } from '../being/digest.js';
-import { RESERVED_IDS } from '../being/types.js';
-import { at, put, drop } from './partition.js';
+import { RESERVED_IDS, isBlueprint } from '../being/types.js';
+import { at, put, drop, prune } from './partition.js';
 import { allow, within, LATE } from './allowance.js';
-import { isWardPk } from './seal.js';
+import { isHex, isWardPk } from './seal.js';
+import { cellFault } from './cells.js';
 // The three calls on `standings` share the object with the ids she takes, so
 // a standing named after one of them would be unreachable: `standings.knock`
 // is the call, whatever record sits under that name. One namespace means one
@@ -28,7 +29,7 @@ export function buildStance(inside, key, cells, bind) {
             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
     // reads the key that speaks now, announces the next, and moves to it once
@@ -51,9 +52,9 @@ export function buildStance(inside, key, cells, bind) {
     // 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
@@ -67,56 +68,95 @@ export function buildStance(inside, key, cells, bind) {
         });
         return out === LATE ? word('late') : out;
     };
-    const send = async (keys, method, args, wanted, rec) => {
-        const r = await inside.send(bind, keys, true, method, args, wanted);
+    const read = (r) => {
         if (isSilence(r) || isWord(r))
-            return r;
+            return { answer: r, door: false, seen: null };
         if ('silence' in r)
-            return silence;
+            return { answer: silence, door: true, seen: null };
         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)
+            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) => r.door && !(isWord(r.answer) && wordOf(r.answer) !== 'threw');
+    const answered = (r) => r.door && !isSilence(r.answer) && !isWord(r.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, method, args, wanted, rec, live = () => true) => {
+        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.object;
+        return r.answer;
     };
-    const knocking = async (inv, method, args, wanted) => {
+    const knocking = async (inv, method, args, wanted, live = () => true) => {
         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 = { 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 = 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
@@ -127,28 +167,28 @@ export function buildStance(inside, key, cells, bind) {
             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
     // ward and one heir whichever door it is reached by, so the standing and the
     // invitation answer to the same name.
     const keyName = (k) => (k.heir === null ? `public:${k.ward}` : `${k.ward}:${k.heir}`);
     const takenAs = (name) => 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, method, args = {}, wanted) => {
+            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
@@ -157,8 +197,8 @@ export function buildStance(inside, key, cells, bind) {
             // 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')))));
+                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.
@@ -178,7 +218,7 @@ export function buildStance(inside, key, cells, bind) {
         // 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, inv) => {
-            if (!valid(inv))
+            if (gone() || !valid(inv))
                 return null;
             const name = nameOf(inv);
             return lane(`knock:${name}`, () => {
@@ -194,12 +234,16 @@ export function buildStance(inside, key, cells, bind) {
                 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) => {
+            if (gone())
+                return;
             drop(cells.standings, id);
             drop(bind.standings, id);
+            inside.wrote();
         },
     };
     const standingAt = (id) => ({
@@ -208,20 +252,33 @@ export function buildStance(inside, key, cells, bind) {
         // 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, args = {}, wanted) => {
+            if (gone())
+                return Promise.resolve(word('dropped'));
             const keys = at(bind.standings, id);
             if (!keys)
                 return Promise.resolve(word('dropped')); // 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, keys, rec, method, args, wanted) => {
-        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, keys, rec, method, args, wanted, live = () => true) => {
+        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;
-                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;
@@ -236,28 +293,61 @@ export function buildStance(inside, key, cells, bind) {
         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, key) => 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, made, id) => {
+            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) => {
-                if (reserved(id) || at(cells.occupants, id) || at(cells.standings, id))
+            invite: async (id, notes) => {
+                if (gone() || reserved(id) || at(cells.occupants, id) || at(cells.standings, id))
                     return null;
-                put(cells.occupants, id, { id, notes: {} });
+                // 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) => {
+                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,

package/dist/ward/ward.d.ts

@@ -1,2 +1,12 @@
+import type { Cells, Stance } from '../being/types.ts';
 import type { Ground, WardPointers } from './ground.ts';
+import { type Bind } from './partition.ts';
+import { type Door } from './door.ts';
+export type Resident = Door & {
+    bind: Bind;
+    stance: Stance;
+    cells: Cells & {
+        class?: string;
+    };
+};
 export declare function Ward(ground: Ground): Promise<WardPointers>;