@quo-systems/quo 0.1.0 → 0.2.0

package/src/ward/stance.ts

@@ -1,10 +1,10 @@
 // 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 } from '../being/silence.ts';
+import { silence, isSilence, isUnreached, isWord, word } from '../being/silence.ts';
 import { digest } from '../being/digest.ts';
 import { RESERVED_IDS } from '../being/types.ts';
-import type { Answer, Cells, Invitation, JsonObject, Silence, Stance, Standing, Standings, Unreached, Wanted } 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 { allow, within, LATE } from './allowance.ts';
 import { isWardPk, type ReplyPayload } from './seal.ts';
@@ -17,7 +17,7 @@ export type Inside = {
   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 | Unreached>;
+  send(bind: Bind, keys: StandingKeys, announce: boolean, method: string | undefined, args: JsonObject, wanted: Wanted | undefined): Promise<ReplyPayload | Silence | Word>;
 };
 
 // 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.
@@ -84,13 +84,14 @@ export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bin
     const out = await within(allow(wanted).time, work(() => !late), () => {
       late = true;
     });
-    return out === LATE ? silence : out;
+    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) || isUnreached(r)) return r;
+    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;
   };
@@ -122,7 +123,7 @@ export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bin
       k.current = own.current;
       k.next = own.next;
       if (isUnreached(r)) return r; // still nothing. she knows no more than before.
-      if (!isSilence(r) && !('silence' in r)) {
+      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;
@@ -144,8 +145,13 @@ export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bin
       k.next = keys.next;
     }
     if (isUnreached(r)) return r; // nothing came back. she does not know whether it was heard.
-    k.spoke = true;
-    if (isSilence(r) || 'silence' in r) return silence;
+    // 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;
   };
@@ -158,14 +164,14 @@ export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bin
 
   const calls = {
     knock: async (inv: Invitation, method?: string, args: JsonObject = {}, wanted?: Wanted): Promise<Answer> => {
-      if (!valid(inv)) return silence;
+      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(silence))));
-      return bounded(wanted, (live) => lane(`knock:${nameOf(inv)}`, () => (live() ? knocking(inv, method, args, wanted) : Promise.resolve(silence))));
+      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')))));
     },
     // 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.
@@ -214,15 +220,15 @@ export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bin
     // the next line. Waiting for the lane is not a reason to lose it.
     ask: (method?: string, args: JsonObject = {}, wanted?: Wanted): Promise<Answer> => {
       const keys = at(bind.standings, id);
-      if (!keys) return Promise.resolve(silence as Answer); // she dropped it between one line and the next
+      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(silence))));
+      return bounded(wanted, (live) => lane(`ask:${id}`, () => (live() ? asking(id, keys, rec, method, args, wanted) : 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);
-    if (method === undefined && !isSilence(out) && !isUnreached(out)) {
+    if (method === undefined && !isSilence(out) && !isWord(out)) {
       const here = at(cells.standings, id);
       if (here) {
         here.blueprint = out as never;

package/src/ward/ward.ts

@@ -4,9 +4,9 @@
 // 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, isUnreached } from '../being/silence.ts';
+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 } 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, open, put, emptyBind, emptyCells, type Bind, type Partition, type StandingKeys } from './partition.ts';
 import { Heirs } from './heirs.ts';
@@ -72,7 +72,7 @@ class Self implements BeingLike {
     this.ask = async (method, args = {}) => {
       try {
         const out = await this.answer({ id: OWNER }, method, args as JsonObject);
-        return isSilence(out) || isUnreached(out) ? silence : out;
+        return isSilence(out) || isWord(out) ? silence : out;
       } catch {
         return silence;
       }
@@ -151,7 +151,7 @@ class Self implements BeingLike {
   // 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, announce: boolean, method: string | undefined, args: JsonObject, wanted?: Wanted): Promise<ReplyPayload | typeof silence | ReturnType<typeof unreached>> {
+  async #send(bind: Bind, keys: StandingKeys, announce: boolean, method: string | undefined, args: JsonObject, wanted?: Wanted): 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.
@@ -185,22 +185,22 @@ class Self implements BeingLike {
     // relation that comes back round holds a lane the answer needs, and only a
     // bound on the wait can break that. What comes back late is not read.
     //
-    // A wait that ran out is silence, never unreached. Unreached promises
+    // 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)) : this.g.carry(keys.ward, bytes)).then(
+    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 silence;
+    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
-    if (!('silence' in reply) && keys.next !== null) {
+    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;
     }

package/vectors/framing.json

@@ -2,7 +2,7 @@
   "corpus": "@quo-systems/quo",
   "encoding": "hex",
   "area": "framing",
-  "note": "The formats a second kit must reproduce byte for byte: the ward pk, the digest, the signed ask body, the sealed ask, the sealed reply, the invitation and the knock. Every random input is fixed here, so every output is fixed. The ask body is JSON.stringify of the payload, which is not canonical: these vectors pin the key order sealAsk writes, to, by, next, seq, time, method, args; hops is in no vector, because nothing sets it. A kit that emits another order still interoperates, because a door verifies the bytes it received, but it will not reproduce these vectors. An invitation is JSON too, ward, heir, secret, and a heir secret is the seed of a being key. A knock is an ask whose by is the heir pk, signed with the heir secret, whose next is the knocker's own key, and whose to is the heir; its answer is an ordinary reply, and the heir is spent by it. The ward here is the one from the ward pk vector, and the heir secret is the first entropy it draws, so the invitation it mints and the knock its door binds are these bytes.",
+  "note": "The formats a second kit must reproduce byte for byte: the ward pk, the digest, the signed ask body, the sealed ask, the sealed reply, the invitation and the knock. Every random input is fixed here, so every output is fixed. The ask body is JSON.stringify of the payload, which is not canonical: these vectors pin the key order sealAsk writes, to, by, next, seq, time, method, args; hops is in no vector, because nothing sets it. A kit that emits another order still interoperates, because a door verifies the bytes it received, but it will not reproduce these vectors. An invitation is JSON too, ward, heir, secret, and a heir secret is the seed of a being key. A knock is an ask whose by is the heir pk, signed with the heir secret, whose next is the knocker's own key, and whose to is the heir; its answer is an ordinary reply, and the heir is spent by it. A reply is one of three shapes: an object with its digest, silence, or the ward's word to a key the door has bound, { quo: word }, where word is one of removed, absent, unannounced, repeated, threw. The ward here is the one from the ward pk vector, and the heir secret is the first entropy it draws, so the invitation it mints and the knock its door binds are these bytes.",
   "vectors": [
     {
       "name": "a ward pk from a fixed seed",
@@ -53,6 +53,12 @@
       "replySeed": "4444444444444444444444444444444444444444444444444444444444444444",
       "bytes": "ff2ee45601ec1b67310c7790404585ae697331eee1c1f8cf2419731c1fff3e6b76ec93e97a657e002d9135a7394f3ec33bcd723c9d8947909f4cc659d8dfeed743f5b64bfa87b4ac79074219c1032037de444400b509f31559331b7995f9dfbadbe7fb0f6d46db2257db70f248b7739b3baa2ca79b07b66b29ea680faf79340f2309163c9e3c65fcdb33297c419d1cd8517647"
     },
+    {
+      "name": "a sealed word reply: the ward's word to a key it has bound",
+      "reply": "{\"quo\":\"removed\"}",
+      "replySeed": "4444444444444444444444444444444444444444444444444444444444444444",
+      "bytes": "ff2ee45601ec1b67310c7790404585ae697331eee1c1f8cf2419731c1fff3e6b76ec8dfe7f2227567dce23ea274378db64eb74efed5c91135d62d89db62db7d8ffbd54cf3e82e3272d0b26d59130020755b442a16340798d3eec60bc3a3875020da9276d5e72d712ac3dad7ef287d3c153a0588bf4951b9d3540b1142bd54875a3"
+    },
     {
       "name": "an invitation for a heir: the ward pk, the heir pk, the heir secret, and nothing else",
       "wardSeed": "1111111111111111111111111111111111111111111111111111111111111111",