@quo-systems/quo 0.2.5 → 0.2.7

package/SPEC.md

@@ -121,8 +121,8 @@ in    the stance      at birth, once, for life
 out   her answer(asker, method?, args?) -> object | silence      the one method the ward calls
 ```
 
-The stance is her cells, her standings to ask, and the calls to invite,
-knock, take and remove. The ward builds it and hands it to the harbor's
+The stance is her cells, her standings to ask, the calls to invite,
+knock, take and remove, and boot. The ward builds it and hands it to the harbor's
 instantiate with a class name, and receives her. No method is the empty ask,
 and what she answers to it is her blueprint.
 
@@ -142,6 +142,8 @@ stance
   standings[id].ask(method?, args?, wanted?)           -> object | silence | word
   standings.remove(id)                                 -> nothing
 
+  boot(class, key)                                     -> key | null           a new being of her ward, by class name
+
   wanted = { time? }                                   what this one ask may spend, in milliseconds. optional,
                                                        and so is saying anything at all
 ```
@@ -164,6 +166,15 @@ Return table.
 | ask(m, a, w)        | object     | she answered                                                                                                 |
 |                     | silence    | she chose to say nothing, or bytes came back that are not Quo's                                              |
 |                     | word       | why not: removed, absent, repeated, threw, unreached, late, dropped                                          |
+| boot(class, key)    | key        | she exists from now, with fresh cells, and a restart finds her                                               |
+|                     | null       | the key is already booted, the harbor holds no such class, or the class threw at birth                       |
+
+A being may make, and only the owner reaches into another. Boot touches
+nobody: the being made has empty cells and no relation, hers included, until
+one is invited and taken like any other. What the owner has that she does
+not is every ask that reaches into a being from outside: public, invite and
+knock for her, remove, unboot. Who may ask her to boot is her gate, as who
+may ask her anything is.
 
 Ask, knock, invite and take are awaitable. Async where the language has it,
 blocking where it does not. Every ask she makes is a new call.
@@ -967,9 +978,10 @@ become one.
 The root is not an occupant. It holds no heir, no key, no invitation. The
 ward names every arrival on the ask `{ id: 'OWNER' }`, the third asker of the
 ward-to-being edge, and answers it as such; an owner at the door arrives as
-her id. What an owner can do is exactly what a being cannot: boot, mark the
-public being, place a relation into a being of the ward, take one out of
-her, and take her out of the ward. The root's asks carry no allowance of
+her id. What an owner can do is reach into a being from outside, which no
+being can: mark the public being, place a relation into a being of the
+ward, take one out of her, and take her out of the ward. Boot it shares
+with every being of the ward. The root's asks carry no allowance of
 their own. The ward is a being to her owner: the empty ask is her describe,
 and each ask in it carries a description and an input naming its fields, as
 a being's asks do, so that a side renders the owner's asks the way it
@@ -1044,9 +1056,10 @@ The ward:
 - Derives its pk from its seed and names itself outward by that and nothing
   else. Mints every other key from the ground's random, one per side of one
   relation.
-- Instantiates beings when the owner asks, by class name. It builds the
-  stance, names the class, and receives the object from the harbor's
-  instantiate call. It never sees a class body, its own included.
+- Instantiates beings when the owner or a being of the ward asks, by class
+  name. It builds the stance, names the class, and receives the object from
+  the harbor's instantiate call. It never sees a class body, its own
+  included.
 - Keeps, per being, the cells, the standings and the occupants, in the
   partition, and outside her cells the bind table. Never reads notes.
 - Mints a heir for every id a being mints, keeps its pk beside the id, and

package/dist/being/being.d.ts

@@ -16,6 +16,7 @@ export declare class Being {
     invite(id: string): Promise<Invitation | null>;
     knock(invitation: Invitation, method?: string, args?: JsonObject, wanted?: Wanted): Promise<Answer>;
     take(id: string, invitation: Invitation): Promise<string | null>;
+    boot(className: string, key: string): string | null;
     occupant(asker: Asker): OccupantRecord | undefined;
     describe(asker: Asker): Blueprint;
     answer(asker: Asker, method?: string, args?: JsonObject): Promise<Reply>;

package/dist/being/being.js

@@ -1,5 +1,5 @@
 // Names a subclass may not use for an ask, because they are the base's own.
-const RESERVED = new Set(['answer', 'describe', 'stance', 'cells', 'standings', 'occupants', 'occupant', 'invite', 'knock', 'take', 'constructor']);
+const RESERVED = new Set(['answer', 'describe', 'stance', 'cells', 'standings', 'occupants', 'occupant', 'invite', 'knock', 'take', 'boot', 'constructor']);
 export class Being {
     // Her cells' defaults. Merged in at birth, only where a key is missing, so
     // a restart keeps what she wrote.
@@ -38,6 +38,10 @@ export class Being {
     take(id, invitation) {
         return this.stance.standings.take(id, invitation);
     }
+    // A new being of her ward, by class name, under a key she chooses.
+    boot(className, key) {
+        return this.stance.boot(className, key);
+    }
     // The occupant record for whoever is at the door. Undefined at a public being.
     occupant(asker) {
         return asker.id === undefined ? undefined : this.cells.occupants[asker.id];

package/dist/being/types.d.ts

@@ -77,6 +77,7 @@ export type Stance = {
     readonly cells: Cells;
     readonly occupants: Occupants;
     readonly standings: Standings;
+    boot(className: string, key: string): string | null;
 };
 export interface BeingLike {
     answer(asker: Asker, method?: string, args?: JsonObject): Reply | Promise<Reply>;

package/dist/ward/stance.d.ts

@@ -10,6 +10,7 @@ export type Inside = {
     openHeir(heir: string, being: string, id: string): void;
     closeHeir(heir: string): void;
     send(bind: Bind, keys: StandingKeys, announce: boolean, method: string | undefined, args: JsonObject, wanted: Wanted | undefined): Promise<ReplyPayload | Silence | Word>;
+    instantiate(key: string, className: string): string | null;
 };
 export type SealedInvitation = {
     ward: string;

package/dist/ward/stance.js

@@ -234,6 +234,12 @@ export function buildStance(inside, key, cells, bind) {
     });
     return {
         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),
         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.

package/dist/ward/ward.js

@@ -135,6 +135,16 @@ class Self {
             openHeir: (heir, being, id) => this.heirs.open(heir, being, id),
             closeHeir: (heir) => this.heirs.close(heir),
             send: (b, keys, announce, method, args, wanted) => this.#send(b, keys, announce, method, args, wanted),
+            // 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: (k, className) => {
+                try {
+                    return this.#instantiate(k, className)?.key ?? null;
+                }
+                catch {
+                    return null;
+                }
+            },
         }, key, cells, bind);
         const being = classNameOrSelf === this ? this : this.g.instantiate(classNameOrSelf, stance);
         if (!being)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quo-systems/quo",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Quo: an object asks another object and gets an answer, without knowing where it is. Being, Ward, Harbor.",
   "keywords": [
     "quo",
@@ -39,7 +39,7 @@
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "test": "node --test \"test/*.test.ts\"",
     "check:terrain": "node --test \"test/terrain/*.test.ts\"",
-    "prepublishOnly": "cd ../.. && npm run check && npm run check:terrain"
+    "prepublishOnly": "test \"$QUO_GATED\" = 1 || { echo 'publish from the root, gated once: npm run release' >&2; exit 1; }"
   },
   "publishConfig": {
     "access": "public"

package/src/being/being.ts

@@ -16,7 +16,7 @@ export type AskSpec = {
 };
 
 // Names a subclass may not use for an ask, because they are the base's own.
-const RESERVED = new Set(['answer', 'describe', 'stance', 'cells', 'standings', 'occupants', 'occupant', 'invite', 'knock', 'take', 'constructor']);
+const RESERVED = new Set(['answer', 'describe', 'stance', 'cells', 'standings', 'occupants', 'occupant', 'invite', 'knock', 'take', 'boot', 'constructor']);
 
 export class Being {
   // Her cells' defaults. Merged in at birth, only where a key is missing, so
@@ -55,6 +55,10 @@ export class Being {
   take(id: string, invitation: Invitation): Promise<string | null> {
     return this.stance.standings.take(id, invitation);
   }
+  // A new being of her ward, by class name, under a key she chooses.
+  boot(className: string, key: string): string | null {
+    return this.stance.boot(className, key);
+  }
   // The occupant record for whoever is at the door. Undefined at a public being.
   occupant(asker: Asker): OccupantRecord | undefined {
     return asker.id === undefined ? undefined : this.cells.occupants[asker.id];

package/src/being/types.ts

@@ -89,6 +89,10 @@ export type Stance = {
   readonly cells: Cells;
   readonly occupants: Occupants;
   readonly standings: Standings;
+  // A new being of her ward, by class name, under a key she chooses. The key
+  // back, or null: the key is taken or the harbor holds no such class. A
+  // being may make; only the owner reaches into another.
+  boot(className: string, key: string): string | null;
 };
 
 // The raw shape of a being. Anything with these two is a being.

package/src/ward/stance.ts

@@ -18,6 +18,8 @@ export type Inside = {
   // 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>;
+  // a new being of this ward, as the owner's boot makes one. the key, or null.
+  instantiate(key: string, className: string): string | null;
 };
 
 // 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.
@@ -247,6 +249,12 @@ export function buildStance(inside: Inside, key: string, cells: Cells, bind: Bin
 
   return {
     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),
     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.

package/src/ward/ward.ts

@@ -145,6 +145,15 @@ class Self implements BeingLike {
         openHeir: (heir, being, id) => this.heirs.open(heir, being, id),
         closeHeir: (heir) => this.heirs.close(heir),
         send: (b, keys, announce, method, args, wanted) => this.#send(b, keys, announce, method, args, wanted),
+        // 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: (k, className) => {
+          try {
+            return this.#instantiate(k, className)?.key ?? null;
+          } catch {
+            return null;
+          }
+        },
       },
       key,
       cells,