@quo-systems/dock 0.2.3 → 0.2.4

package/harbor/files.ts

@@ -1,39 +1,101 @@
 // SPDX-License-Identifier: Apache-2.0
-// The store as a folder on disk, one folder per ward:
+// The store as a folder on disk, one folder per ward, in one of two forms.
+//
+// Plain, when the store has no key, what the droplets run:
 //
 //   <dir>/wards/<name>/seed             32 bytes, hex, mode 0600
 //   <dir>/wards/<name>/partition.json
 //   <dir>/wards/<name>/ward.json        the ward record
+//
+// Sealed, when the store holds a key, what a device's daemon runs with the
+// key from its Keychain:
+//
+//   <dir>/wards/<name>/ward.sealed      seed, partition and record as one
+//                                       JSON, sealed under the key, hex
+//
+// and in both:
+//
 //   <dir>/reach.json                    the directory's hints
 //
-// Every write of the partition goes through a temp file and a rename, and
-// writes are queued per ward so two calls never race on one file.
+// A ward is whole in either form, and a store that meets the other form
+// refuses it by name: a daemon started without its key, or with one against
+// a plain folder, fails loudly instead of booting on what it cannot read.
+// Sealing a plain folder is a deliberate command, never a boot's doing.
+// Every write of a ward goes through a temp file and a rename, and writes
+// are queued per ward so two calls never race on one file.
 import { mkdir, readFile, writeFile, rename, readdir, rm, chmod } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { arithmetic } from '@quo-systems/quo/ward';
 import type { Kept, Store, WardRecord } from '@quo-systems/quo/harbor';
+import { sealKey, seal, open } from './seal.ts';
 
 const { hex, unhex } = arithmetic;
+type Blob = { seed: string; partition: Record<string, unknown>; record: WardRecord };
 
 export class Files implements Store {
   readonly dir: string;
+  readonly #key?: Promise<CryptoKey>;
   readonly #queues = new Map<string, Promise<void>>();
-  constructor(dir: string) {
+  constructor(dir: string, key?: string) {
     this.dir = dir;
+    if (key) this.#key = sealKey(key);
   }
   #ward(name: string) {
     return join(this.dir, 'wards', name);
   }
+  get sealed(): boolean {
+    return this.#key !== undefined;
+  }
+  // The form a folder holds, checked against the form this store speaks.
+  #form(name: string): 'plain' | 'sealed' | undefined {
+    const wd = this.#ward(name);
+    const form = existsSync(join(wd, 'ward.sealed')) ? 'sealed' : existsSync(join(wd, 'seed')) ? 'plain' : undefined;
+    if (form === 'sealed' && !this.sealed) throw new Error(`ward ${name} in ${this.dir} is sealed and this harbor has no key`);
+    if (form === 'plain' && this.sealed) throw new Error(`ward ${name} in ${this.dir} is plain and this harbor holds a key`);
+    return form;
+  }
+  // One write at a time per ward, through a temp file and a rename.
+  #write(name: string, file: string, body: string): Promise<void> {
+    const next = (this.#queues.get(name) ?? Promise.resolve()).then(async () => {
+      const tmp = join(this.#ward(name), `${file}.tmp`);
+      await writeFile(tmp, body, { mode: 0o600 });
+      await rename(tmp, join(this.#ward(name), file));
+    });
+    this.#queues.set(name, next.catch(() => {}));
+    return next;
+  }
+  async #read(name: string): Promise<Blob> {
+    const blob = (await readFile(join(this.#ward(name), 'ward.sealed'), 'utf8')).trim();
+    return JSON.parse(new TextDecoder().decode(await open(await this.#key!, blob))) as Blob;
+  }
+  // A sealed ward is rewritten whole, so the read sits inside the queue
+  // with the write: two changes to one ward never lose each other's part.
+  #keep(name: string, change: (b: Blob | undefined) => Blob): Promise<void> {
+    const next = (this.#queues.get(name) ?? Promise.resolve()).then(async () => {
+      const wd = this.#ward(name);
+      const blob = change(existsSync(join(wd, 'ward.sealed')) ? await this.#read(name) : undefined);
+      const sealed = await seal(await this.#key!, new TextEncoder().encode(JSON.stringify(blob)));
+      await writeFile(join(wd, 'ward.sealed.tmp'), sealed + '\n', { mode: 0o600 });
+      await rename(join(wd, 'ward.sealed.tmp'), join(wd, 'ward.sealed'));
+    });
+    this.#queues.set(name, next.catch(() => {}));
+    return next;
+  }
 
   async list(): Promise<string[]> {
     const wards = join(this.dir, 'wards');
-    return existsSync(wards) ? (await readdir(wards)).filter((n) => existsSync(join(wards, n, 'seed'))) : [];
+    return existsSync(wards) ? (await readdir(wards)).filter((n) => existsSync(join(wards, n, 'seed')) || existsSync(join(wards, n, 'ward.sealed'))) : [];
   }
 
   async load(name: string): Promise<Kept | undefined> {
+    const form = this.#form(name);
+    if (!form) return undefined;
+    if (form === 'sealed') {
+      const b = await this.#read(name);
+      return { seed: unhex(b.seed), partition: b.partition, record: b.record };
+    }
     const wd = this.#ward(name);
-    if (!existsSync(join(wd, 'seed'))) return undefined;
     return {
       seed: unhex((await readFile(join(wd, 'seed'), 'utf8')).trim()),
       partition: JSON.parse(await readFile(join(wd, 'partition.json'), 'utf8')) as Record<string, unknown>,
@@ -42,30 +104,28 @@ export class Files implements Store {
   }
 
   async put(name: string, kept: Kept): Promise<void> {
+    if (this.#form(name)) throw new Error(`ward ${name} already exists in ${this.dir}`);
     const wd = this.#ward(name);
-    if (existsSync(join(wd, 'seed'))) throw new Error(`ward ${name} already exists in ${this.dir}`);
     await mkdir(wd, { recursive: true, mode: 0o700 });
+    if (this.sealed) return this.#keep(name, () => ({ seed: hex(kept.seed), partition: kept.partition, record: kept.record }));
     await writeFile(join(wd, 'seed'), hex(kept.seed), { mode: 0o600 });
     await chmod(join(wd, 'seed'), 0o600);
     await writeFile(join(wd, 'partition.json'), JSON.stringify(kept.partition) + '\n', { mode: 0o600 });
     await writeFile(join(wd, 'ward.json'), JSON.stringify(kept.record, null, 2) + '\n', { mode: 0o600 });
   }
 
-  save(name: string, partition: Record<string, unknown>): Promise<void> {
-    const wd = this.#ward(name);
-    if (!existsSync(join(wd, 'seed'))) return Promise.resolve(); // a name not kept is nothing
-    const next = (this.#queues.get(name) ?? Promise.resolve()).then(async () => {
-      const tmp = join(wd, 'partition.json.tmp');
-      await writeFile(tmp, JSON.stringify(partition) + '\n', { mode: 0o600 });
-      await rename(tmp, join(wd, 'partition.json'));
-    });
-    this.#queues.set(name, next.catch(() => {}));
-    return next;
+  async save(name: string, partition: Record<string, unknown>): Promise<void> {
+    const form = this.#form(name);
+    if (!form) return; // a name not kept is nothing
+    if (form === 'sealed') return this.#keep(name, (b) => ({ ...b!, partition }));
+    return this.#write(name, 'partition.json', JSON.stringify(partition) + '\n');
   }
 
   async record(name: string, record: WardRecord): Promise<void> {
-    if (!existsSync(join(this.#ward(name), 'seed'))) return;
-    await writeFile(join(this.#ward(name), 'ward.json'), JSON.stringify(record, null, 2) + '\n', { mode: 0o600 });
+    const form = this.#form(name);
+    if (!form) return;
+    if (form === 'sealed') return this.#keep(name, (b) => ({ ...b!, record }));
+    return this.#write(name, 'ward.json', JSON.stringify(record, null, 2) + '\n');
   }
 
   async take(name: string): Promise<Kept | undefined> {

package/harbor/quo-harbor.md

@@ -38,8 +38,9 @@ needs:
 
 | a ward is   | Mac, iPhone           | droplet                    | edge                    | browser tab            |
 | ----------- | --------------------- | -------------------------- | ----------------------- | ---------------------- |
-| seed        | Keychain              | `.env` or a secrets file   | the platform's secrets  | IndexedDB, per origin  |
-| partition   | app data, SQLite      | a file on disk             | Durable Object storage  | IndexedDB, per origin  |
+| seed        | a file, sealed        | `.env` or a secrets file   | the platform's secrets  | IndexedDB, per origin  |
+| partition   | a file, sealed        | a file on disk             | Durable Object storage  | IndexedDB, per origin  |
+| the key     | Keychain              | the environment, if any    | the platform's secrets  | none                   |
 | code        | the app bundle        | a folder                   | the deployed worker     | a bundle URL           |
 
 Envoys read their own secrets from the same secret store as the seed. A
@@ -60,14 +61,27 @@ it likes, so it may keep the secret branch apart from the data, by terrain:
 - **Split.** The bind branch goes to the secret store beside the seed, the
   rest to the data store. Fits a phone with a few relations; keychain items
   are small and a being with a thousand standings has a thousand key pairs.
-- **Wrapped.** The secret store holds one key per ward; the data store holds
-  the whole partition encrypted under it. Any size, one secret. The droplet
-  and edge answer, and it works on the phone too.
+- **Wrapped.** The secret store holds one key per harbor; the data store
+  holds each ward whole, seed, partition and record as one blob encrypted
+  under it. Any size, one secret. The droplet and edge answer, and it
+  works on the phone too.
 
 The ward never knows. It hands values and gets values back. A heir given away
 as an invitation is a live credential until it speaks, and on a device other
 apps share that is the argument for the secret store.
 
+Wrapped is what is built, and it is one piece, `seal.ts`: AES-GCM under a
+32-byte key, a fresh nonce each time, nonce and ciphertext together as hex,
+on WebCrypto so it runs wherever a store does. The key is the one secret a
+harbor reads from its terrain's secret store, named `QUO_SEED_KEY` on every
+terrain: a platform secret on the edge, the environment of a daemon on a
+device, handed to it from the Keychain by the app that spawned it. A
+droplet gives no key and its folder stays plain under its file modes. A
+store speaks one form, the one its key decides, and refuses a ward kept in
+the other by name, so a daemon started without its key, or with one
+against a plain folder, fails loudly and boots nothing. Sealing a plain
+folder is a deliberate operator command, never a boot's doing.
+
 ### Custody is a lease
 
 `packages/quo/SPEC.md` makes custody the harbor's vouch: two harbors over one
@@ -314,8 +328,10 @@ root as `/quo/`, with the trailing slash, which the door takes.
 The harbor core is the library's, `packages/quo/src/harbor/core.ts`, and so is
 the dialer, `packages/quo/src/harbor/dial.ts`; `packages/quo/SPEC.md` says what
 they are. Every harbor here extends the core and hands it three things: a
-**store**, the library's interface, with `files.ts` on a disk and `idb.ts` in a
-tab, each passing the library's store suite; a **loader**, the code half, a
+**store**, the library's interface, with `files.ts` on a disk, plain as three
+files per ward or sealed as one blob when the daemon holds `QUO_SEED_KEY`,
+and `idb.ts` in a tab, each passing the library's store suite, the files
+store in both forms; a **loader**, the code half, a
 module from a folder on a daemon and the bundle in a tab; and a **lease**, a pid
 file on disk and a web lock on the database name in a tab, so a second tab on
 one origin meets the lock and is a screen. The disk harbor, `disk.ts`, is the
@@ -352,13 +368,13 @@ second harbor over one database does not boot.
 is the harbor. The platform runs one instance of it at a time, which is
 the lease and the single writer every ward needs. Its storage is the
 store, `storage.ts`: one row per ward, seed, partition and record, with the
-seed sealed under a key from the platform's secrets, `QUO_SEED_KEY`, so the
-storage holds ciphertext and the secret store holds the one key, as the
-table above says. The deployed worker is the code, the built-in beings and
-whatever it hands in. It is a listener and never a dialer: reached by
-request at `<origin>/h/<name>/quo`, holding the sockets dialers open to it
-on the platform's own socket pair, the rendezvous for them, awake per
-request and kept awake by a held socket.
+seed sealed by `seal.ts` under a key from the platform's secrets,
+`QUO_SEED_KEY`, so the storage holds ciphertext and the secret store holds
+the one key, as the table above says. The deployed worker is the code, the
+built-in beings and whatever it hands in. It is a listener and never a
+dialer: reached by request at `<origin>/h/<name>/quo`, holding the sockets
+dialers open to it on the platform's own socket pair, the rendezvous for
+them, awake per request and kept awake by a held socket.
 
 Its owner door is a route, not a socket, because the platform has no local
 process: the root is whoever holds `QUO_ROOT`, a platform secret, and the
@@ -387,6 +403,30 @@ hold on every terrain; the listener half is the terrain's own, `ws` on
 Node and the socket pair on the edge, and stays where the terrain is. What
 the library takes, when it takes the reach, is the framing and the dialer.
 
+## The phone, as built
+
+`capacitor.ts` is the store on a phone, the wrapped form over Capacitor's
+Filesystem plugin and a secure-storage plugin: one key per harbor in the
+Keychain, marked this device only so it never travels in a backup, and one
+sealed file per ward, seed, partition and record as one blob, in the
+folder iCloud does not copy. The seal is `seal.ts`, the same piece the
+daemon and the edge use. Opening the store is where custody is decided,
+since a phone's backup is the one copy nobody makes on purpose: a key with
+no folder is a reinstall, and the stale key is deleted; a folder with no
+key is a restore to another device, and the unreadable files are deleted;
+either way the harbor starts fresh and there is never a twin. The app that
+holds the store is `packages/app/`, which the dock does not know.
+
+The proof is `packages/dock/test/terrain/ios.test.ts`, behind
+`npm run check:terrain`: the store suite, untouched, and the custody rule,
+run inside the real app in the iOS Simulator against a real Keychain and a
+real folder. The app is synced with the test's origin as its page, built
+with xcodebuild, installed fresh and launched with simctl; the page loads
+the bundled exercise, `native.ts`, runs it and posts the list back. Two
+things the plugins taught, held in the store: the secure store keeps JSON,
+so a value is read with the call that parses; and mkdir refuses a folder
+that exists, recursive or not.
+
 ## The link
 
 An invitation carries the ward pk of the world that minted it, and not where

package/harbor/seal.ts

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+// The seal: what a store does to a ward's bytes before they rest on a data
+// store, under one key the secret store holds. One piece with three users,
+// the edge under the platform's secret, the daemon under a key from its
+// environment, the phone under a key from the Keychain. AES-GCM under a
+// 32-byte key, a fresh nonce each time, nonce and ciphertext together as
+// hex. WebCrypto only, so it runs wherever a store does.
+import { arithmetic } from '@quo-systems/quo/ward';
+
+const { hex, unhex } = arithmetic;
+// Bytes as the platform's crypto wants them: over a plain ArrayBuffer.
+const plain = (b: Uint8Array): Uint8Array<ArrayBuffer> => new Uint8Array(b);
+
+export async function sealKey(secret: string): Promise<CryptoKey> {
+  if (!/^[0-9a-f]{64}$/.test(secret)) throw new Error('a seal key is 32 bytes as hex');
+  return crypto.subtle.importKey('raw', plain(unhex(secret)), 'AES-GCM', false, ['encrypt', 'decrypt']);
+}
+export async function seal(key: CryptoKey, bytes: Uint8Array): Promise<string> {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ct = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, plain(bytes)));
+  return hex(iv) + hex(ct);
+}
+export async function open(key: CryptoKey, sealed: string): Promise<Uint8Array> {
+  const b = plain(unhex(sealed));
+  return new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: b.subarray(0, 12) }, key, b.subarray(12)));
+}

package/human/html.ts

@@ -230,5 +230,7 @@ export function page(m: Model): string {
   const notes = bp && shown !== null && shown !== undefined && !(typeof shown === 'object' && !Array.isArray(shown) && !Object.keys(shown).length) ? `<aside class="notes">${view(shown as Json)}</aside>` : '';
   const pushes = m.pushes.length ? `<section class="pushes"><h2>pushes</h2><ol>${m.pushes.map((p) => `<li>${view(p)}</li>`).join('')}</ol></section>` : '';
   const mine = look(m.look);
-  return `<header${mine.style}>${m.look.logo ? `<img class="logo" alt="" src="${m.look.logo}">` : ''}<h1>${escape(title(bp, m.look))}</h1><p class="notice">${escape(m.notice)}</p></header>${notes}<main${mine.style}>${asks}</main>${pushes}`;
+  // a page carries its own title, so the header keeps only the notice; a being painted as forms is headed by her name
+  const head = m.tree ? '' : `${m.look.logo ? `<img class="logo" alt="" src="${m.look.logo}">` : ''}<h1>${escape(title(bp, m.look))}</h1>`;
+  return `<header${mine.style}>${head}<p class="notice">${escape(m.notice)}</p></header>${notes}<main${mine.style}>${asks}</main>${pushes}`;
 }

package/human/local.ts

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+// A being in the tab's own ward, as a subject the screen renders: a world's
+// code running on the device, booted from the bundle that world serves on
+// its origin. The side holds the object, as every side does, and speaks to
+// her door in-process under the tab's own asker: no standing, no relation,
+// since the local ward is the human's and she is on it. Her cells are in
+// the tab's store and migrate with the ward; her asks are the forms; her
+// page is computed from her cells at every digest, the same painter and the
+// same side as a far being's, so one grammar has two sources and no second
+// verb. A push never reaches her: nothing outside the tab holds her.
+import type { Answer, Blueprint, JsonObject } from '@quo-systems/quo';
+import type { Subject } from '../beings/side.ts';
+
+// The asker the tab speaks under to its own beings.
+export const TAB = 'tab';
+
+type Door = { answer(asker: { id: string }, method?: string, args?: JsonObject): Promise<unknown> };
+
+export function local(being: Door): Subject {
+  const me = { id: TAB };
+  return {
+    tools: async () => (await being.answer(me)) as Blueprint,
+    call: (name: string, args: JsonObject = {}): Promise<Answer> => being.answer(me, name, args) as Promise<Answer>,
+    ears: new Set(),
+  };
+}

package/human/quo-human.md

@@ -58,11 +58,51 @@ running there, from her cells, and painted by the same painter.
 - **The page is presentation.** `page` is asked once per digest, like
   `look`; it is never a form, never a tool, and a carrier never carries it.
   The user being answers one: her name as the title, who this device is as
-  an answer, her standings as sections, and the one thing a human does here
-  by hand, waking another device, as a form.
+  an answer, her standings as sections, and the two things a human does
+  here by hand, waking another device and calling her by a name, as forms.
+  A being does not know her own key, so her name is given: by the desk's
+  first hello at the root's setup, or by a device the root minted, through
+  her `name` ask, the trunk's rule.
 - **The door is the first page in the grammar**, painted with nobody behind
   it: no ask, no answer, no standing, only the mark, a word and a sentence.
 
+## The tab ward
+
+A world's code runs in the tab, as beings. The second source of the one
+grammar: a being booted in the tab's local ward for a world answers `page`
+from her cells, and the same side paints her with the same painter. No
+second verb, no framework, no script of the world's on the page: only
+classes, and the ward runs them.
+
+- **The world's code is a module the harbor folder holds**, `tab/index.ts`,
+  the twin of `classes/index.ts`: the classes meant for the tab, exported
+  by name. The web route bundles it as `beings.js` on the world's origin
+  and tells the page it exists; a folder with none has no such path. Code
+  crosses the origin, never a relation, and one origin is one world's code.
+- **The boot at join.** The tab loads the world's classes before its harbor
+  boots, since a being kept from the last visit is booted by her class
+  name. When a relation goes on screen, the tab boots one being of each
+  class under that relation's key, `r1-Notes`, the first time, and finds
+  her there after: her cells are in the ward, kept in the tab's store after
+  every ask and migrating with the ward. Two relations in one world are two
+  of each, since what she keeps is one person's.
+- **A subject with no standing.** The side holds her object and speaks to
+  her door in-process under the tab's own asker, `local.ts`, the way it
+  holds an avatar: no relation, no key rotation, since the local ward is
+  the human's and she is on it. Her describe is what she shows the tab, her
+  forms are her asks, and a push never reaches her, since nothing outside
+  the tab holds her.
+- **Her page follows every ask.** `page` is asked again after each call
+  and the answers it shows are run again with it, so a cell moved is a page
+  moved whether or not her describe moved. The describe, the look and the
+  read-only asks off the page stay once per digest. A far being pays the
+  same: her page is never more than one ask behind her.
+- **One section each.** Under the far being's page, each being of the world
+  has her own section and her own side; the shell's own heading is dropped
+  wherever a page carries its title. Slots that bind her page to a
+  standing she holds, and the shadow root that isolates a far page, are
+  the next part of the same design.
+
 ## How a screen is made
 
 Read with the trunk's "Carrying" and "The look", which this applies.
@@ -86,8 +126,9 @@ Read with the trunk's "Carrying" and "The look", which this applies.
   and acme sees the human, never the device. The same section appears on
   acme's own web, under the same look: one component, two relations.
 - **The page follows the digest.** The side asks the describe again after
-  every call and asks `look` and `page` once per digest; a digest that moved
-  is a page that moved. A read-only ask with nothing to type is run on open,
+  every call, asks `look` once per digest and `page` after every call; a
+  digest that moved is a page that moved, and so is a cell that moved
+  behind a page. A read-only ask with nothing to type is run on open,
   so a page can open with what it shows and not only with buttons. Every one
   of those asks rotates her keys, so the side saves after each, not only
   after a form: a relation brought back from a reload with a stale count is
@@ -143,7 +184,10 @@ Read with the trunk's "Carrying" and "The look", which this applies.
 
 ## The pieces
 
-Nine files under `packages/dock/human/`:
+Ten files under `packages/dock/human/`:
+
+- `local.ts` is a being of the world in the tab's own ward as a subject:
+  her door spoken to in-process under the tab's asker, no standing.
 
 - `tree.ts` is the page grammar and its painter, pure: `sanitiseTree`
   holds a value to the grammar or drops it, `answersIn` names what a tree
@@ -157,9 +201,10 @@ Nine files under `packages/dock/human/`:
 - `screen.ts` is the side: one avatar and one surface, where a surface can
   only show a page and hand back a submitted form. It keeps the model,
   speaks it as a page after every change, calls her when a form comes back,
-  re-asks her describe after every call, asks her look and her page once
-  per digest, and runs on open her read-only asks and the ones her page
-  shows the answers of. A push is appended and shown as it lands. A
+  re-asks her describe after every call, asks her look once per digest and
+  her page after every call, and runs her read-only asks once per digest
+  and the ones her page shows the answers of after every call. A push is
+  appended and shown as it lands. A
   describe that fails leaves the last page standing and says so in the
   notice.
 - `dom.ts` is the surface on an element, the one file that touches one.
@@ -182,8 +227,9 @@ Nine files under `packages/dock/human/`:
 
 Proven in `packages/dock/test/human.test.ts` on the memory harbor with a fake
 surface and no browser: the grammar held and painted, the user being's page
-with what her gate hides painted as nothing, the user being carrying a shop
-with a look, a guest
+with what her gate hides painted as nothing, a being of the world in the
+tab's ward paged from her cells and kept with them, the user being
+carrying a shop with a look, a guest
 at a door that is not a desk let in by a form, the link read, stripped and
 refused, and the worlds and relations on a harbor core over the memory
 store, two invitations into one world being two avatars; and in

package/human/screen.ts

@@ -49,7 +49,8 @@ export async function screenSide(avatar: Subject, surface: Surface, options: Opt
       model.notice = `not in: ${bp.error}`;
     } else {
       const d = await digest(bp as Blueprint);
-      if (d !== seen) {
+      const moved = d !== seen;
+      if (moved) {
         seen = d;
         model.blueprint = bp as Blueprint;
         for (const k of Object.keys(model.answers)) if (!(bp as Blueprint).asks.some((a) => a.name === k)) delete model.answers[k];
@@ -58,18 +59,23 @@ export async function screenSide(avatar: Subject, surface: Surface, options: Opt
           const l = await avatar.call('look');
           model.look = isSilence(l) || isWord(l) ? {} : sanitise(l as Json);
         } else model.look = {};
-        // her page, once per digest: a tree of values, or nothing and her asks are forms
-        if ((bp as Blueprint).asks.some((a) => a.name === 'page')) {
-          const t = await avatar.call('page');
-          model.tree = isSilence(t) || isWord(t) ? null : sanitiseTree(t as Json);
-        } else model.tree = null;
-        // a read-only ask that needs nothing typed, or one her page shows the answer of, is run on
-        // her behalf, so the page opens with what it shows
-        const wanted = new Set(model.tree ? answersIn(model.tree) : []);
-        for (const a of (bp as Blueprint).asks) {
-          const needs = ((a.input as { required?: string[] }).required ?? []).length > 0;
-          if ((hintFor(bp as Blueprint, model.look, a.name).readOnly || wanted.has(a.name)) && !needs && !(a.name in model.answers)) model.answers[a.name] = word(await avatar.call(a.name, {}));
-        }
+      }
+      // her page, after every ask: a tree of values from what she holds now, or nothing and her asks
+      // are forms. A cell moved is a page moved, and her describe need not have; so the answers the
+      // page shows are run again with it, and the page never stands more than one ask behind her
+      const shows = new Set(model.tree ? answersIn(model.tree) : []);
+      if ((bp as Blueprint).asks.some((a) => a.name === 'page')) {
+        const t = await avatar.call('page');
+        model.tree = isSilence(t) || isWord(t) ? null : sanitiseTree(t as Json);
+      } else model.tree = null;
+      const wanted = new Set(model.tree ? answersIn(model.tree) : []);
+      for (const n of shows) if (wanted.has(n)) delete model.answers[n];
+      // a read-only ask that needs nothing typed is run on her behalf once per digest, and one her page
+      // shows the answer of after every ask, so the page opens and stays with what it shows
+      for (const a of (bp as Blueprint).asks) {
+        const needs = ((a.input as { required?: string[] }).required ?? []).length > 0;
+        const run = wanted.has(a.name) || (moved && hintFor(bp as Blueprint, model.look, a.name).readOnly);
+        if (run && !needs && !(a.name in model.answers)) model.answers[a.name] = word(await avatar.call(a.name, {}));
       }
     }
     await after();

package/human/tab.ts

@@ -33,11 +33,14 @@ import { domSurface } from './dom.ts';
 import { guest } from './guest.ts';
 import { door } from './door.ts';
 import { world, relations, fresh, type Relation } from './worlds.ts';
+import { local } from './local.ts';
+import type { BeingClass } from '@quo-systems/quo';
 
 // What the page is told by the daemon that served it: the world's routes,
 // every ward on that harbor by name, its pk and whether a public being is
-// at its door, and which of them this page is, if it is one's.
-export type Config = { quo: string; web: string; wards: Record<string, { pk: string; public: boolean }>; ward?: string };
+// at its door, which of them this page is, if it is one's, and whether the
+// world serves code for the tab.
+export type Config = { quo: string; web: string; wards: Record<string, { pk: string; public: boolean }>; ward?: string; beings?: boolean };
 
 // What the tab remembers between pages, beside the harbor: the worlds it
 // has joined, by pk, where each lives and what it is called; which relation
@@ -85,7 +88,20 @@ export async function start(cfg: Config, root: HTMLElement = document.body): Pro
   const say = (s: string) => (status.textContent = s);
 
   // The harbor in the tab: one database per origin, one ward per world.
+  // The world's code first, when its origin serves any: the classes for
+  // the tab, handed to the harbor beside the built-in ones before any ward
+  // boots, since a being kept from the last visit is booted by class name.
+  // A world that serves none has no beings in the tab, and the page is the
+  // far being's alone.
   const harbor = new BrowserHarbor('quo');
+  const classes = cfg.beings
+    ? await import(`${cfg.web}/beings.js`).then((mod: Record<string, unknown>) => {
+        const out: Record<string, BeingClass> = {};
+        for (const [name, v] of Object.entries(mod)) if (typeof v === 'function' && 'prototype' in v) out[name] = v as BeingClass;
+        return out;
+      })
+    : {};
+  Object.assign(harbor.classes, classes);
   await harbor.boot();
   harbor.dial(cfg.quo);
 
@@ -138,16 +154,43 @@ export async function start(cfg: Config, root: HTMLElement = document.body): Pro
     }
   };
 
-  // In, as one relation: her page. Every call rotates her keys and a
-  // same-ward ask never crosses the harbor, so the side saves after each.
+  // The world's beings in the tab, for one relation: one of each class,
+  // booted under her key the first time and found there after, since their
+  // cells are in the ward and come back with it. Each is a subject of her
+  // own with her own side in her own section, so a note she keeps and a
+  // form she shows are hers, painted by the same painter as the far page.
+  const locals: { close(): Promise<void> }[] = [];
+  const boot = async (rel: Relation) => {
+    const beings = (ward.partition as { beings?: Record<string, unknown> }).beings ?? {};
+    for (const name of Object.keys(classes)) {
+      const key = `${rel.key}-${name}`;
+      if (!beings[key]) {
+        const out = (await ward.ask('boot', { key, class: name })) as { error?: string };
+        if (out.error) continue;
+        await ward.save();
+      }
+      const being = ward.being(key) as Parameters<typeof local>[0] | undefined;
+      if (!being) continue;
+      const section = el('section', '', { class: 'local', 'data-being': key });
+      screen.append(section);
+      locals.push(await screenSide(local(being), domSurface(section), { after: () => ward.save() }));
+    }
+  };
+
+  // In, as one relation: her page, then the world's beings for her. Every
+  // call rotates her keys and a same-ward ask never crosses the harbor, so
+  // the side saves after each.
   const inside = async (rel: Relation, notice: string, called: string) => {
     await side?.close();
+    for (const l of locals.splice(0)) await l.close();
     status.remove();
     root.querySelector('form.password')?.remove();
     screen.replaceChildren();
     current = rel;
     keep(AT(pk), rel.key);
-    const s = await screenSide(rel.avatar, domSurface(screen), { after: () => ward.save(), notice });
+    const mine = el('div', '', { class: 'far' });
+    screen.append(mine);
+    const s = await screenSide(rel.avatar, domSurface(mine), { after: () => ward.save(), notice });
     side = s;
     const bp = s.model.blueprint;
     const notesName = typeof (bp?.notes as JsonObject | null)?.name === 'string' ? ((bp!.notes as JsonObject).name as string) : '';
@@ -155,6 +198,7 @@ export async function start(cfg: Config, root: HTMLElement = document.body): Pro
     if (!names()[rel.key]) keep(NAMES(pk), { ...names(), [rel.key]: called });
     switcher();
     people();
+    await boot(rel);
   };
 
   // The way in, from any of the three: a fresh avatar joins, the ward is
@@ -177,6 +221,7 @@ export async function start(cfg: Config, root: HTMLElement = document.body): Pro
   // there, the door page: a link is the only way in, and nothing to type.
   const atDoor = async () => {
     await side?.close();
+    for (const l of locals.splice(0)) await l.close();
     side = null;
     current = null;
     screen.replaceChildren();