@quo-systems/quo 0.2.14 → 0.2.16

package/src/ward/stance.ts

@@ -1,14 +1,14 @@
 // 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, isWord, word, wordOf } from '../being/silence.ts';
+import { silence, isSilence, isWord, unreached, word, wordOf } from '../being/silence.ts';
 import { digest } from '../being/digest.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, prune, type Bind, type StandingKeys } from './partition.ts';
 import { allow, within, LATE } from './allowance.ts';
 import { isHex, isWardPk, type ReplyPayload } from './seal.ts';
-import { cellFault } from './cells.ts';
+import { cellFault, unkeepable } from './cells.ts';
 
 // What the stance needs from its ward, and no more.
 export type Inside = {
@@ -29,6 +29,11 @@ export type Inside = {
   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>;
+  // an invitation to one of the harbor's own beings, by the harbor's name for
+  // it, handed to the taker and never returned. false where this box lends
+  // nothing of that name to this ward, or where the taker did not take it, in
+  // which case the harbor has already removed what it minted.
+  lend(name: string, take: (invitation: Invitation) => Promise<boolean>): Promise<boolean>;
   // 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.
@@ -43,9 +48,22 @@ export type SealedInvitation = { ward: string; heir?: string; secret?: string };
 // is the call, whatever record sits under that name. One namespace means one
 // list: these are refused at invite and at take, beside the ward's own words.
 const CALLS = ['knock', 'take', 'remove'];
-const reserved = (id: string): boolean => RESERVED_IDS.includes(id) || CALLS.includes(id);
 
 export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bind): Stance {
+  // A word the ward refuses at every mint and every take. The two the
+  // protocol names, and the ones this kit adds because its own spelling took
+  // them: the calls a standing already answers to, and a name no partition
+  // can hold. That last one is refused here rather than by the cells guard,
+  // because the guard throws and this table promises a null.
+  // A method is a word or it is nothing at all. The seal writes a payload as
+  // JSON, which drops a key whose value it cannot write, so a symbol or a
+  // function here would leave as an ask with no method: the empty ask. She
+  // would have asked for work, been handed a blueprint, and spent a number on
+  // it. Nothing that cannot be sent is sent, and what never left is unreached,
+  // which is the one answer that says asking again is safe. This is the same
+  // rule args are already held to.
+  const named = (method: unknown): boolean => method === undefined || typeof method === 'string';
+  const reserved = (id: string): boolean => RESERVED_IDS.includes(id) || CALLS.includes(id) || unkeepable(id);
   // The name of one relation, as her side files it. A relation is a ward and
   // a heir, never a heir alone: the heir pk is outer, it rides in the clear on
   // every lid, and anyone who reads one can quote it back inside an invitation
@@ -224,6 +242,7 @@ 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 (gone()) return word('dropped');
+      if (!named(method)) return unreached();
       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
@@ -283,6 +302,7 @@ 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> => {
       if (gone()) return Promise.resolve(word('dropped') as Answer);
+      if (!named(method)) return Promise.resolve(unreached() 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);
@@ -349,6 +369,12 @@ export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bin
       // it keeps the pk beside the id and nothing else. the invitation IS the key.
       invite: async (id: string, notes?: JsonObject): Promise<Invitation | null> => {
         if (gone() || reserved(id) || at(cells.occupants, id) || at(cells.standings, id)) return null;
+        // Notes are values, like everything else the partition keeps, and a
+        // spread copies one level: an object inside them would stay the
+        // caller's, a handle into her cells that writes past the guard and
+        // never says `wrote`, so what a restart brought back would not be
+        // what she read. Held to the rule and copied whole, or no invitation.
+        if (notes !== undefined && cellFault(notes, 'notes') !== null) 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
@@ -357,7 +383,7 @@ export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bin
         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 } : {} });
+        put(cells.occupants, id, { id, notes: notes ? (JSON.parse(JSON.stringify(notes)) as JsonObject) : {} });
         inside.openHeir(k.pk, key, id);
         put(bind.occupants, id, k.pk);
         inside.wrote();
@@ -373,5 +399,35 @@ export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bin
       },
     },
     standings,
+    // A standing at one of the things this device can do. The same three
+    // moves her boot makes, with the harbor's root doing the inviting instead
+    // of a being of this ward: ask the ground for the name, knock with what
+    // comes back, take it under the id she gave. She is handed the id.
+    //
+    // The invitation never reaches her, and that is the difference between
+    // this relation and every other she holds. Her own invitations are hers
+    // to give away, because giving one away is giving away her own relation.
+    // This one is the device's, minted for this ward alone, and a value she
+    // could copy is a capability she could hand to anyone. A being who wants
+    // to lend her device access to another does it in the open, by an ask of
+    // her own that forwards to this standing, where her gate reads who is
+    // asking and she can stop.
+    lend: async (name: string, id: string): Promise<string | null> => {
+      if (gone() || typeof name !== 'string' || typeof id !== 'string') return null;
+      if (reserved(id) || at(cells.standings, id) || at(cells.occupants, id)) return null;
+      // Her half runs inside the harbor's call, so a knock that was refused
+      // and a take that lost the id both end with the harbor removing what it
+      // minted. Nothing half-lives here either.
+      const took = await inside.lend(name, async (inv) => {
+        // Read again: the ground was awaited, and a line of hers in between
+        // may have taken the id. Nothing is written for a relation she cannot
+        // hold, and the invitation goes back unspent.
+        if (gone() || reserved(id) || at(cells.standings, id) || at(cells.occupants, id)) return false;
+        const out = await calls.knock(inv);
+        if (isSilence(out) || isWord(out)) return false;
+        return (await calls.take(id, inv)) === id;
+      });
+      return took ? id : null;
+    },
   };
 }

package/src/ward/ward.ts

@@ -198,7 +198,7 @@ class Self implements BeingLike {
   #boot(key: string, make: (stance: Stance) => BeingLike | null): Resident | null {
     const cells = guardCells(at(this.p.beings, key) ?? emptyCells(), () => this.#wrote());
     const bind = at(this.p.bind, key) ?? emptyBind();
-    const stance = buildStance(
+    const stance: Stance = buildStance(
       {
         pk: this.pk,
         // This stance, not merely this key: unboot and boot again under the
@@ -219,6 +219,11 @@ class Self implements BeingLike {
         // 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,
@@ -284,10 +289,14 @@ class Self implements BeingLike {
       return unreached();
     }
     const { bytes, ephemeral } = sealed;
-    // The wait is bounded, and this is the one thing the ward times. A being
-    // holds three answers and a wait that does not end is none of them: a
-    // 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.
+    // 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