@quo-systems/quo 0.2.15 → 0.2.17

package/dist/ward/arithmetic.js

@@ -86,27 +86,97 @@ const key32 = (value, what) => {
     return value;
 };
 const pkcs8 = (prefix, value, what) => concat([prefix, key32(value, what)]);
-const secretKey = (alg, prefix, value, what, uses) => subtle().importKey('pkcs8', pkcs8(prefix, value, what), alg, true, uses);
-const publicKey = (alg, value, what, uses) => subtle().importKey('raw', key32(value, what), alg, true, uses);
-// Subtle exports the public half of a private key only through a JWK, where `x` is the 32 raw bytes in base64url.
-async function rawPublic(secret) {
-    const jwk = await subtle().exportKey('jwk', secret);
-    const binary = atob(jwk.x.replaceAll('-', '+').replaceAll('_', '/'));
-    const out = new Uint8Array(binary.length);
-    for (let at = 0; at < binary.length; at += 1)
-        out[at] = binary.charCodeAt(at);
-    return out;
+// Importing a key is the most expensive thing on the path of an ask, and most
+// of the imports are the same key again: a ward signs every reply with the one
+// key, opens every ask with the one padlock, and verifies a relation under the
+// key it verified it under last time. Measured over a round trip, fifteen of
+// the twenty-five imports were bytes already imported once.
+//
+// So an imported key is kept, by the bytes it was imported from. A CryptoKey
+// cannot be changed once it exists, so handing the same one out twice is
+// handing out what a second import would have built. Nothing here is a
+// decision a peer can see: two wards that cache differently, or not at all,
+// speak the same bytes.
+//
+// It is bounded, and that is not a detail. A relation mints a fresh key on
+// every ask, so a ward that talked all day would otherwise hold a key for
+// every ask it ever made. Past the bound the least recently used goes, which
+// is the key of a relation that has fallen quiet, and importing it again
+// costs what it cost the first time.
+//
+// The secret keys in here are the ones the partition already holds in this
+// process, as seeds. The cache is another shape of what the ward is already
+// standing on, and never a second place a secret comes from.
+const KEYS = 512;
+const imported = new Map();
+const keep = (id, make) => {
+    const had = imported.get(id);
+    if (had !== undefined) {
+        imported.delete(id); // and set again below: the most recently used goes last
+        imported.set(id, had);
+        return had;
+    }
+    const made = make();
+    // A key that would not import is not kept: the next call asks subtle again
+    // and hears the same refusal, rather than reading one this cache remembered.
+    // Node takes any thirty-two bytes as a public key and finds out at verify,
+    // so nothing here reaches this line; a terrain that checks the point at the
+    // import does, and a refusal it remembered would be a relation killed for
+    // good by one bad arrival.
+    made.catch(() => imported.delete(id));
+    imported.set(id, made);
+    // One in, at most one out: a map keeps what was put in the order it was put,
+    // so the first key it names is the one used longest ago.
+    if (imported.size > KEYS)
+        imported.delete(imported.keys().next().value);
+    return made;
+};
+// How many imported keys are held, and the bound they are held under. Nothing
+// in the ward reads either: they are here to be looked at, and for the suite
+// that holds the bound to what it says.
+export const heldKeys = () => ({ held: imported.size, bound: KEYS });
+const secretKey = (alg, prefix, value, what, uses) => {
+    const bytes = pkcs8(prefix, value, what);
+    return keep(`${alg.name}|${uses.join('+')}|${hex(bytes)}`, () => subtle().importKey('pkcs8', bytes, alg, true, uses));
+};
+const publicKey = (alg, value, what, uses) => {
+    const bytes = key32(value, what);
+    return keep(`${alg.name}|${uses.join('+')}|pk|${hex(bytes)}`, () => subtle().importKey('raw', bytes, alg, true, uses));
+};
+// Subtle exports the public half of a private key only through a JWK, where
+// `x` is the 32 raw bytes in base64url. The answer is a fact about the key and
+// never changes, so it is kept beside the key it was read from and goes when
+// the key does.
+const publics = new WeakMap();
+function rawPublic(secret) {
+    const had = publics.get(secret);
+    if (had !== undefined)
+        return had;
+    const read = (async () => {
+        const jwk = await subtle().exportKey('jwk', secret);
+        const binary = atob(jwk.x.replaceAll('-', '+').replaceAll('_', '/'));
+        const out = new Uint8Array(binary.length);
+        for (let at = 0; at < binary.length; at += 1)
+            out[at] = binary.charCodeAt(at);
+        return out;
+    })();
+    publics.set(secret, read);
+    return read;
 }
 export async function sha256(...parts) {
     return new Uint8Array(await subtle().digest('SHA-256', concat(parts)));
 }
+// Both halves are copies. The seed and the public key are kept behind the two
+// caches above, and a pair is handed to whoever asked for it: what she does
+// with the bytes in her hand is hers, and must not reach what the next caller
+// is given.
 export async function signingPair(seed) {
     const secret = await secretKey(ED, ED_SECRET, seed, 'seed', ['sign']);
-    return { secret: Uint8Array.from(seed), pk: await rawPublic(secret) };
+    return { secret: Uint8Array.from(seed), pk: Uint8Array.from(await rawPublic(secret)) };
 }
 export async function sealingPair(seed) {
     const secret = await secretKey(X, X_SECRET, seed, 'seed', ['deriveBits']);
-    return { secret: Uint8Array.from(seed), pk: await rawPublic(secret) };
+    return { secret: Uint8Array.from(seed), pk: Uint8Array.from(await rawPublic(secret)) };
 }
 export async function sign(message, secret) {
     const key = await secretKey(ED, ED_SECRET, secret, 'secret', ['sign']);

package/dist/ward/ground.d.ts

@@ -4,7 +4,7 @@ export type Ground = {
     seed: string | Uint8Array;
     memory: Record<string, unknown>;
     instantiate(className: string, stance: Stance): BeingLike | null;
-    wrote?: () => void;
+    wrote?: (row: string) => void;
     carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | undefined>;
     random(n: number): Uint8Array;
     lend?: Lend;

package/dist/ward/partition.d.ts

@@ -58,3 +58,7 @@ export declare const put: <T>(rec: Record<string, T>, key: string, value: T) =>
 export declare const drop: (rec: Record<string, unknown>, key: string) => void;
 export declare const emptyCells: () => Cells;
 export declare const emptyBind: () => Bind;
+export declare const HEAD = "";
+export declare const rowOf: (p: Partition, row: string) => Record<string, unknown> | undefined;
+export declare const rowsIn: (p: Record<string, unknown>) => string[];
+export declare const fromRows: (rows: Record<string, Record<string, unknown>>) => Record<string, unknown>;

package/dist/ward/partition.js

@@ -167,3 +167,56 @@ export const drop = (rec, key) => {
 };
 export const emptyCells = () => ({ standings: {}, occupants: {} });
 export const emptyBind = () => ({ standings: {}, occupants: {}, knocks: {}, answered: {}, minted: [] });
+// ---- the partition in rows, for a store that keeps it
+//
+// A ward hands a harbor one object, so a being who writes one cell has every
+// other being in her ward written down beside her. What a being holds is the
+// one thing here that grows without limit, so she is a row: her cells and her
+// bind table, under her key. Everything else is one head row, and every part
+// of it is bounded already, one record per occupant and two lists that drop
+// their oldest.
+//
+// The split is here, where the shape is, and not in the harbor, which keeps
+// what it is given and reads none of it. A store is handed the rows that
+// moved; what it does with that is its own, and one that writes every row is
+// as correct as one that writes the few.
+export const HEAD = ''; // the row that is not a being: no being's key is empty
+// One row's value: a being, or the head, which is everything the partition
+// holds that is not filed under a being. The head is read as what is left
+// rather than as a list of names, so a store keeps whatever it was handed and
+// hands the same thing back, and a field this file grows later needs no line
+// in a store to survive a round trip.
+//
+// Undefined where the key names nobody, which is a row the store drops.
+export const rowOf = (p, row) => {
+    const all = p;
+    if (row === HEAD)
+        return Object.fromEntries(Object.entries(all).filter(([k]) => k !== 'beings' && k !== 'bind'));
+    const cells = at(p.beings ?? {}, row);
+    return cells === undefined ? undefined : { cells, bind: at(p.bind ?? {}, row) ?? emptyBind() };
+};
+export const rowsIn = (p) => [HEAD, ...Object.keys(p.beings ?? {})];
+// The partition back from its rows. A head that is absent is a partition
+// nobody has written, and `open` makes an empty one of it.
+export const fromRows = (rows) => {
+    const out = { ...(rows[HEAD] ?? {}) };
+    const beings = {};
+    const bind = {};
+    let any = Object.keys(out).length > 0;
+    for (const [row, value] of Object.entries(rows)) {
+        if (row === HEAD)
+            continue;
+        put(beings, row, value.cells);
+        put(bind, row, value.bind);
+        any = true;
+    }
+    // Nothing kept is nothing handed back. Rows that say only that there are no
+    // rows must come back as the empty memory they are, because `open` reads an
+    // empty one as a ward's first breath and anything else as a partition
+    // somebody wrote, which must then say which version wrote it.
+    if (!any)
+        return {};
+    out.beings = beings;
+    out.bind = bind;
+    return out;
+};

package/dist/ward/seal.js

@@ -26,7 +26,7 @@ export const SIZE = 1024 * 1024;
 // designs and no separation at all: one secret would be doing two jobs with
 // nothing said about it, and a second kit would have to reproduce a
 // construction nobody named. HKDF-SHA-256 under a label is the separation
-// said out loud, and it is what `vectors/framing.json` pins.
+// said out loud, and it is what `protocol/vectors/framing.json` pins.
 //
 // Bytes are key material and text is not. A seed handed in as bytes of the
 // key length is taken as it stands, which is what a harbor mints; anything

package/dist/ward/ward.js

@@ -6,7 +6,7 @@
 // leaves, opens every one that arrives.
 import { silence, isSilence, unreached, isWord, word } from '../being/silence.js';
 import { OWNER } from '../being/types.js';
-import { at, drop, open, put, emptyBind, emptyCells, MINTED } from './partition.js';
+import { at, drop, open, put, emptyBind, emptyCells, HEAD, MINTED } from './partition.js';
 import { Heirs } from './heirs.js';
 import { makeDoor } from './door.js';
 import { buildStance } from './stance.js';
@@ -38,7 +38,13 @@ class Self {
         this.key = key;
         this.pk = key.pk;
         this.p = open(ground.memory); // the partition: the ward's own state, and every being's row
-        this.heirs = new Heirs(this.p, () => this.#wrote());
+        // Opening is itself a write: a memory nobody has written comes back with
+        // a version stamped on it and the ward's own tables under it. A ward that
+        // said nothing here would have every being of it kept and the head that
+        // says which version they are written under kept by nobody, so the next
+        // boot would read a partition of no version and refuse it.
+        this.#wrote(HEAD);
+        this.heirs = new Heirs(this.p, () => this.#wrote(HEAD));
         this.door = makeDoor(key, this.heirs, this.doors, () => this.p.public, (n) => ground.random(n)); // pointer one
         this.#boot(this.pk, () => this); // the ward's ward is itself
         // a restart is silent: every being in the cells is constructed again, unasked.
@@ -93,15 +99,18 @@ class Self {
             unboot: (key) => this.#unboot(key),
             setPublic: (key) => {
                 this.p.public = key;
-                this.#wrote();
+                this.#wrote(HEAD);
             },
         }, asker, method, args);
     }
     // ---- ward functions. on the object. no stance reaches them.
-    // The partition was written. The harbor is told, and nothing more: what it
-    // does with the word is its own, and the ward never learns.
-    #wrote() {
-        this.g.wrote?.();
+    // The partition was written, and which row of it: a being by her key, or
+    // the head. The harbor is told, and nothing more: what it does with the
+    // word is its own, and the ward never learns. Every write says its row,
+    // because a harbor told only that something moved must keep all of it, and
+    // a being's row is the one part of a partition that grows without limit.
+    #wrote(row) {
+        this.g.wrote?.(row);
     }
     // The rows no door holds this run: beings whose class threw at birth or
     // is not the harbor's to give. Key to class.
@@ -139,7 +148,7 @@ class Self {
         if (!door)
             return null;
         unguarded(door.cells).class = className; // so a restart finds her. the ward's key, written behind her guard
-        this.#wrote();
+        this.#wrote(key);
         return door;
     }
     // The inverse of boot, and the only way a being leaves a ward. Her
@@ -177,7 +186,8 @@ class Self {
         drop(this.p.beings, key);
         drop(this.p.bind, key);
         this.doors.delete(key);
-        this.#wrote();
+        this.#wrote(key); // she is gone, and her row goes with her
+        this.#wrote(HEAD); // her heirs were closed, and the public being may have been her
         return [...occupants, ...standings];
     }
     // Nothing is written until there is somebody to write it for: a class the
@@ -188,17 +198,17 @@ class Self {
     // makers: the ground's `instantiate` for a being of the ward, and the ward
     // itself, which is the first being in its own map and is already made.
     #boot(key, make) {
-        const cells = guardCells(at(this.p.beings, key) ?? emptyCells(), () => this.#wrote());
+        const cells = guardCells(at(this.p.beings, key) ?? emptyCells(), () => this.#wrote(key));
         const bind = at(this.p.bind, key) ?? emptyBind();
         const stance = buildStance({
             pk: this.pk,
             // This stance, not merely this key: unboot and boot again under the
             // same key makes a new being, and the old stance is not hers.
             live: () => this.doors.get(key)?.stance === stance,
-            mintKey: (b) => this.#mintKey(b),
+            mintKey: (b) => this.#mintKey(b, key),
             openHeir: (heir, being, id) => this.heirs.open(heir, being, id),
             closeHeir: (heir) => this.heirs.close(heir),
-            send: (b, keys, method, args, wanted) => this.#send(b, keys, method, args, wanted),
+            send: (b, keys, method, args, wanted) => this.#send(b, keys, method, args, wanted, key),
             // 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: (className, k) => {
@@ -215,7 +225,7 @@ class Self {
             // 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(),
+            wrote: () => this.#wrote(key),
         }, key, cells, bind);
         const being = make(stance);
         if (!being || typeof being.answer !== 'function')
@@ -224,10 +234,10 @@ class Self {
         put(this.p.bind, key, bind);
         const door = { key, cells, bind, stance, being };
         this.doors.set(key, door);
-        this.#wrote();
+        this.#wrote(key);
         return door;
     }
-    async #mintKey(bind) {
+    async #mintKey(bind, row) {
         const k = await beingKey(this.g.random(32));
         // The last few she minted, and no more. A relation rotates on every ask,
         // so a list of all of them is a partition that grows for as long as she
@@ -236,7 +246,7 @@ class Self {
         bind.minted.push(k.pk);
         if (bind.minted.length > MINTED)
             bind.minted.splice(0, bind.minted.length - MINTED);
-        this.#wrote();
+        this.#wrote(row);
         return k;
     }
     // One send for every door, the ward's own included. Mine: never leaves.
@@ -244,7 +254,7 @@ class Self {
     // 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, keys, method, args, wanted) {
+    async #send(bind, keys, method, args, wanted, row) {
         // 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.
@@ -255,7 +265,7 @@ class Self {
         // to rotate to. A standing on her signs with one key for life. Every other
         // ask announces its next: there is no send that does not.
         if (keys.next === null && keys.heir !== null)
-            keys.next = (await this.#mintKey(bind)).seed;
+            keys.next = (await this.#mintKey(bind, row)).seed;
         const next = keys.next === null ? null : (await beingKey(unhex(keys.next))).pk;
         // Her count for this relation, one higher every call and never reused. The
         // far door honours each number once. One relation sends one at a time, so
@@ -279,10 +289,14 @@ class Self {
             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
@@ -303,7 +317,7 @@ class Self {
             keys.current = keys.next; // the far door holds `next` as announced. move to it.
             keys.next = null;
         }
-        this.#wrote(); // the count moved, and the keys may have
+        this.#wrote(row); // the count moved, and the keys may have
         return reply;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quo-systems/quo",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "Quo: an object asks another object and gets an answer, without knowing where it is. Being, Ward, Harbor.",
   "keywords": [
     "quo",
@@ -35,13 +35,13 @@
       "types": "./dist/conformance/index.d.ts",
       "default": "./dist/conformance/index.js"
     },
-    "./vectors/*": "./vectors/*",
+    "./protocol/*": "./protocol/*",
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp ../../papers/SPEC.md SPEC.md && cp ../../papers/quo-kit.md quo-kit.md",
-    "test": "node --test \"test/*.test.ts\"",
-    "check:terrain": "node --test \"test/terrain/*.test.ts\"",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp ../../papers/SPEC.md protocol/SPEC.md && cp ../../papers/quo-kit.md quo-kit.md && cp ../../papers/GETTING_STARTED.md GETTING_STARTED.md",
+    "check": "node --test \"test/*.test.ts\"",
+    "deep": "node --test \"test/terrain/*.test.ts\"",
     "prepublishOnly": "test \"$QUO_GATED\" = 1 || { echo 'publish from the root, gated once: npm run release:quo' >&2; exit 1; }"
   },
   "publishConfig": {
@@ -50,9 +50,9 @@
   "files": [
     "dist",
     "src",
-    "vectors",
-    "SPEC.md",
+    "protocol",
     "quo-kit.md",
+    "GETTING_STARTED.md",
     "README.md",
     "LICENSE",
     "NOTICE"

package/{SPEC.md → protocol/SPEC.md}

@@ -710,6 +710,12 @@ spent, so bytes leave and the door's silence comes back: after take the
 invitation names the standing and nothing else, so it is exactly as alive as
 the standing is.
 
+A lane is released by the bound and by nothing else. An ask that never comes
+back holds its relation's lane, and every later ask on that relation waits
+behind it, so the bound ends an occupancy and not only a wait. A kit that
+bounds where a being is waiting, and not where the lane is held, has a
+relation that one quiet far side closes for good.
+
 ### The public being
 
 A ward may have one public being, and no more. She is an ordinary being,
@@ -898,7 +904,8 @@ the default would leave her only the narrowing half, and would give the ward
 no way to allow one long piece of work without making every ask that
 patient.
 
-The sender's wait has an end, and this is the one thing the ward times. The
+The sender's wait has an end, and time is the only thing the ward measures:
+no count of doors, no count of bytes, no count of tries. The
 bound covers the whole of an ask, from the moment she calls: a relation that
 comes back round on itself is stopped at its own lane, before a byte is
 sealed, and a bound that watched only the wire would never see it. This is
@@ -1045,9 +1052,14 @@ in pieces, by a being who knows how her own work divides.
 
 The hand to a kit in another language is two things, and they are of two
 kinds. `vectors/` is the byte-level hand: fixed inputs and outputs for
-everything a stranger can observe, the arithmetic, the ward pk, the digest,
-the signed body, the sealed shapes, the invitation, the knock, and the
-frames on a socket and the one request a door takes. A kit reproduces them
+everything a stranger can observe, in four areas. `arithmetic.json` is the
+primitives the seal rests on. `framing.json` is the ward pk, the digest, the
+signed body, the sealed shapes, the invitation and the knock.
+`wire.json` is the frames on a socket and the one request a door takes.
+`door.json` is the door's thirteen cases, each one an arrival: the bytes that
+come in, the bytes that go out, what those bytes open to where a hand holds
+the lid, and the partition's digest before and after, so `nothing written`
+is a value a kit checks and never a sentence it reads. A kit reproduces them
 or it is not this protocol. The conformance suite is the behavioural hand,
 and it is a checklist and not a harness: one ward is one runtime and one
 language, so the beings a suite is shown with run only in the ward its kit