@quo-systems/dock 0.1.0

package/dist/cli/quo.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// `quo`: the one command of the estate. Thin on purpose: each subcommand
+// picks a folder, reaches the daemon or the disk, and hands off. Logic that
+// appears here was missing from a being or a side, and moves there.
+//
+//   quo init   [--dir D] [--ward W]          mint a seed, boot a ward over a disk store, write both
+//   quo serve  [--dir D] [--http PORT] [--dial URL]  the daemon: harbor from disk, the two sockets, the HTTP door on loopback, a socket held to URL
+//   quo census [--dir D] [--ward W] [--via S]        the empty ask: pk and every being
+//   quo boot   [--dir D] [--ward W] [--via S] <json> { key, class, public? }
+//   quo invite [--dir D] [--ward W] [--via S] <json> { being, id }
+//   quo knock  [--dir D] [--ward W] [--via S] <json> { being | { boot, key }, id, invitation, method?, args?, wanted? }
+//   quo remove [--dir D] [--ward W] [--via S] <json> { being, id }: a relation out of a being; on the ward pk, an owner
+//   quo side   [--dir D] [--ward W] --as NAME  an avatar over stdio for a local MCP client; NAME is the client identity
+//   quo run    [--dir D] [--ward W] --as NAME --url URL --model NAME [--turns N]  a human at a terminal talking to a model through an avatar: a line in, the model's final text out
+//   quo pilot  [--dir D] [--ward W] [--via S]        the owner pilot over stdio: census, boot, invite, knock, remove
+//   quo reach  [--dir D] <pk> <url>          a hint for the harbor's directory: that ward pk lives at that quo. route
+//
+// D defaults to $QUO_DIR, then ~/.quo. W defaults to main. init takes
+// --user NAME for the user being, defaulting to the device's user. run
+// takes the model's base URL as --url or $QUO_MODEL_URL, its name as
+// --model or $QUO_MODEL, a bearer from $QUO_MODEL_KEY, read here and never
+// kept, and --turns as the ceiling of model calls in one turn. S is a
+// standing the user being holds at another ward, one the root there invited
+// as an owner: with --via, the owner asks go to that ward's door, sealed,
+// and the answers are its. Without it they are the root's, on the pointer.
+import { homedir, userInfo } from 'node:os';
+import { join } from 'node:path';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { DiskHarbor } from '../harbor/disk.js';
+import { serve } from './daemon.js';
+import { ask, side, reach } from './client.js';
+import { pilotSide } from '../mcp/pilot.js';
+const OWNER_ASKS = new Set(['boot', 'invite', 'knock', 'remove']);
+function parse(argv) {
+    const flags = {};
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? '';
+        if (a.startsWith('--'))
+            flags[a.slice(2)] = argv[++i] ?? '';
+        else
+            rest.push(a);
+    }
+    const [cmd, json, more] = rest;
+    return { cmd, json, more, flags, dir: flags.dir ?? process.env.QUO_DIR ?? join(homedir(), '.quo'), ward: flags.ward ?? 'main', via: flags.via };
+}
+const print = (v) => console.log(JSON.stringify(v, null, 2));
+async function main(argv) {
+    const { cmd, json, more, flags, dir, ward, via } = parse(argv);
+    if (cmd === 'init') {
+        print(await DiskHarbor.init(dir, ward, flags.user ?? userInfo().username));
+        return 0;
+    }
+    if (cmd === 'side' || cmd === 'run') {
+        if (!flags.as) {
+            console.error(`quo ${cmd} needs --as NAME`);
+            return 2;
+        }
+        let run;
+        if (cmd === 'run') {
+            const url = flags.url ?? process.env.QUO_MODEL_URL;
+            const model = flags.model ?? process.env.QUO_MODEL;
+            if (!url || !model) {
+                console.error('quo run needs --url URL and --model NAME, or QUO_MODEL_URL and QUO_MODEL');
+                return 2;
+            }
+            const key = process.env.QUO_MODEL_KEY;
+            const turns = flags.turns !== undefined ? Number(flags.turns) : undefined;
+            if (turns !== undefined && !(Number.isInteger(turns) && turns > 0)) {
+                console.error('--turns is a positive integer');
+                return 2;
+            }
+            run = { url, model, ...(key ? { key } : {}), ...(turns !== undefined ? { turns } : {}) };
+        }
+        await side(dir, flags.as, ward, run); // stdio to the daemon, until one end closes
+        return -1;
+    }
+    if (cmd === 'pilot') {
+        await ask(dir, undefined, {}, ward); // no daemon is a clear word now, not at the first tool call
+        const serving = await pilotSide(dir, ward, new StdioServerTransport(), (line) => console.error(`pilot ${line}`), via);
+        process.stdin.once('end', () => void serving.close().then(() => process.exit(0)));
+        return -1;
+    }
+    if (cmd === 'serve') {
+        const port = flags.http ?? process.env.QUO_HTTP;
+        const s = await serve(dir, { ...(port !== undefined ? { http: { port: Number(port) } } : {}), ...(flags.dial ? { dial: [flags.dial] } : {}) });
+        print({ dir: s.harbor.dir, sock: s.sock, side: s.side, http: s.http ? `http://${s.http.host}:${s.http.port}` : null, dial: s.quo.dialers.map((d) => d.url), wards: Object.fromEntries([...s.harbor.wards].map(([n, h]) => [n, h.pk])) });
+        const stop = () => void s.close().then(() => process.exit(0));
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        return -1; // stays up
+    }
+    if (cmd === 'reach') {
+        if (!json || !more) {
+            console.error('quo reach needs <pk> <url>');
+            return 2;
+        }
+        const out = await reach(dir, json, more);
+        print('error' in out ? { error: out.error } : out.result);
+        return 'error' in out ? 1 : 0;
+    }
+    if (cmd === 'census' || (cmd !== undefined && OWNER_ASKS.has(cmd))) {
+        const args = json ? JSON.parse(json) : {};
+        const out = await ask(dir, cmd === 'census' ? undefined : cmd, args, ward, via);
+        print('error' in out ? { error: out.error } : out.result);
+        // an error object the ward answered is an ordinary answer, and still a
+        // non-zero exit, so a script can tell a boot that happened from one that did not.
+        const failed = 'error' in out || (typeof out.result === 'object' && out.result !== null && 'error' in out.result);
+        return failed ? 1 : 0;
+    }
+    console.error('usage: quo init|serve|census|boot|invite|knock|remove|side|run|pilot|reach [--dir D] [--ward W] [--via S] [--as NAME] [--url URL --model NAME] [--dial URL] [json]');
+    return 2;
+}
+main(process.argv.slice(2)).then((code) => {
+    if (code >= 0)
+        process.exit(code);
+}, (e) => {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+});

package/dist/harbor/browser.d.ts

@@ -0,0 +1,13 @@
+import type { BeingClass } from '@quo-systems/quo';
+import { Harbor, type Dialer } from '@quo-systems/quo/harbor';
+import { Idb } from './idb.ts';
+export declare const BUILT_IN: Record<string, BeingClass>;
+export declare class BrowserHarbor extends Harbor {
+    #private;
+    readonly db: Idb;
+    readonly dialers: Dialer[];
+    constructor(name?: string, classes?: Record<string, BeingClass>);
+    boot(): Promise<void>;
+    dial(url: string): Dialer;
+    close(): Promise<void>;
+}

package/dist/harbor/browser.js

@@ -0,0 +1,50 @@
+import { User, Desk, Avatar } from '../beings/index.js';
+import { Harbor, dial } from '@quo-systems/quo/harbor';
+import { Idb } from './idb.js';
+export const BUILT_IN = { User, Desk, Avatar };
+export class BrowserHarbor extends Harbor {
+    db;
+    dialers = [];
+    #release;
+    constructor(name = 'quo', classes = {}) {
+        const db = new Idb(name);
+        super(db, async () => ({ ...BUILT_IN, ...classes }));
+        this.db = db;
+    }
+    // Take the lock and boot every ward kept here. A lock already held is
+    // another tab's harbor over this seed, and this one refuses to boot.
+    async boot() {
+        await this.#lease();
+        await super.boot();
+    }
+    // Hold one socket to a world's quo. route.
+    dial(url) {
+        const d = dial(this, url);
+        this.dialers.push(d);
+        return d;
+    }
+    async close() {
+        for (const d of this.dialers.splice(0))
+            d.close();
+        this.db.close();
+        this.#release?.();
+        this.#release = undefined;
+    }
+    async #lease() {
+        const locks = globalThis.navigator?.locks;
+        if (!locks)
+            return; // no web locks on this terrain: nothing vouches, as in the memory harbor
+        const granted = await new Promise((ok) => {
+            void locks.request(`quo:${this.db.name}`, { ifAvailable: true }, (lock) => {
+                if (!lock) {
+                    ok(false);
+                    return;
+                }
+                ok(true);
+                return new Promise((release) => (this.#release = release)); // held until close
+            });
+        });
+        if (!granted)
+            throw new Error(`harbor ${this.db.name} is held by another tab`);
+    }
+}

package/dist/harbor/disk.d.ts

@@ -0,0 +1,19 @@
+import type { BeingClass } from '@quo-systems/quo';
+import { Harbor, type Hosted } from '@quo-systems/quo/harbor';
+export type { Hosted, Bound } from '@quo-systems/quo/harbor';
+export type { WardRecord } from '@quo-systems/quo/harbor';
+export declare const BUILT_IN: Record<string, BeingClass>;
+export declare class DiskHarbor extends Harbor {
+    #private;
+    readonly dir: string;
+    constructor(dir: string);
+    static init(dir: string, name?: string, user?: string): Promise<{
+        dir: string;
+        name: string;
+        pk: string;
+        user: string;
+    }>;
+    boot(): Promise<void>;
+    close(): Promise<void>;
+    adoptFolder(name: string): Promise<Hosted>;
+}

package/dist/harbor/disk.js

@@ -0,0 +1,126 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// SPDX-License-Identifier: Apache-2.0
+// The node daemon's harbor: the core over a folder on disk. The store is
+// `files.ts`, one folder per ward; the class bodies come from a module the
+// ward record names, loaded from the folder; the lease is a pid file. The
+// estate's own beings, the user being, the front desk and the avatar, are
+// held by every harbor here: they are what every side needs, and a folder's
+// class source adds to them.
+//
+//   <dir>/
+//     lease                 pid of the one process that holds this harbor
+//     classes/index.ts      the default class source, a module exporting classes
+//     wards/<name>/         seed, partition.json, ward.json: see files.ts
+//     reach.json            the directory's hints
+import { mkdir, readFile, writeFile, unlink, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve, isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import process from 'node:process';
+import { User, Desk, Avatar } from '../beings/index.js';
+import { setup } from '../beings/setup.js';
+import { Harbor, DEFAULT_CODE } from '@quo-systems/quo/harbor';
+import { Files } from './files.js';
+export const BUILT_IN = { User, Desk, Avatar };
+// Folders held by a harbor in this process. The lease file names a pid, and
+// a second harbor in the same pid would pass that check while still being a
+// second ward with one pk.
+const HELD = new Set();
+// The class source is a module. Every export that is a class is a class the
+// harbor holds, under its export name. The harbor never sees a body: it
+// constructs when a ward names a class, and never chooses one.
+async function loadClasses(path) {
+    if (!existsSync(path))
+        return {};
+    // Keyed by the file's own time, so a source that changed on disk is read
+    // again and a harbor boots on what it pins, not on what it once loaded.
+    const { mtimeMs } = await stat(path);
+    const mod = (await import(__rewriteRelativeImportExtension(`${pathToFileURL(path).href}?v=${mtimeMs}`)));
+    const out = {};
+    for (const [name, v] of Object.entries(mod))
+        if (typeof v === 'function' && 'prototype' in v)
+            out[name] = v;
+    return out;
+}
+export class DiskHarbor extends Harbor {
+    dir;
+    #held = false;
+    constructor(dir) {
+        const abs = resolve(dir);
+        super(new Files(abs), async (rec) => ({ ...BUILT_IN, ...(await loadClasses(isAbsolute(rec.code) ? rec.code : join(abs, rec.code))) }));
+        this.dir = abs;
+    }
+    // Create a harbor folder with one ward, and the root's setup in it: the
+    // front desk, public, and one user being, with the desk holding a standing
+    // to her placed by the root's knock. Boots the ward once, with no lease, to
+    // do that and to learn its pk, and writes the record. Refuses a folder that
+    // has one.
+    static async init(dir, name = 'main', user = 'me') {
+        const h = new DiskHarbor(dir);
+        if (existsSync(join(h.dir, 'wards', name, 'seed')))
+            throw new Error(`ward ${name} already exists in ${h.dir}`);
+        await mkdir(join(h.dir, 'classes'), { recursive: true });
+        const classes = join(h.dir, DEFAULT_CODE);
+        if (!existsSync(classes))
+            await writeFile(classes, '// The classes this harbor holds beside the built-in ones. Export each one by name.\nexport {};\n');
+        const hosted = await h.create(name, user);
+        await setup(hosted, user);
+        return { dir: h.dir, name, pk: hosted.pk, user };
+    }
+    // Take the lease and boot every ward in the folder. The lease is the
+    // harbor's vouch made a store property: two processes over one seed are two
+    // wards with one pk, so a held lease refuses the boot.
+    async boot() {
+        await this.#lease();
+        await super.boot();
+    }
+    async close() {
+        if (!this.#held)
+            return;
+        await unlink(join(this.dir, 'lease')).catch(() => { });
+        HELD.delete(this.dir);
+        this.#held = false;
+    }
+    // Boot a ward whose folder was placed here by hand.
+    async adoptFolder(name) {
+        const kept = await this.store.load(name);
+        if (!kept)
+            throw new Error(`no ward ${name} in ${this.dir}`);
+        return this.host(name, kept);
+    }
+    async #lease() {
+        if (HELD.has(this.dir))
+            throw new Error(`harbor ${this.dir} is held by pid ${process.pid}`);
+        const path = join(this.dir, 'lease');
+        if (existsSync(path)) {
+            const pid = Number(await readFile(path, 'utf8'));
+            let alive = pid !== process.pid; // our own pid with no entry in HELD is a lease we left behind
+            if (alive) {
+                try {
+                    process.kill(pid, 0);
+                }
+                catch (e) {
+                    alive = e.code === 'EPERM'; // EPERM: somebody is home, and not us. anything else: a corpse
+                }
+            }
+            if (alive)
+                throw new Error(`harbor ${this.dir} is held by pid ${pid}`);
+            await unlink(path).catch(() => { }); // the corpse, so the write below can be exclusive
+        }
+        try {
+            await writeFile(path, String(process.pid), { flag: 'wx', mode: 0o600 });
+        }
+        catch {
+            throw new Error(`harbor ${this.dir} is held: another daemon took the lease first`);
+        }
+        HELD.add(this.dir);
+        this.#held = true;
+    }
+}

package/dist/harbor/edge/edge.d.ts

@@ -0,0 +1,26 @@
+import type { BeingClass } from '@quo-systems/quo';
+import { Harbor, Socket as Held } from '@quo-systems/quo/harbor';
+import { DurableStorage } from './storage.ts';
+import type { State, Env } from './platform.d.ts';
+export declare const BUILT_IN: Record<string, BeingClass>;
+export declare class EdgeHarbor extends Harbor {
+    #private;
+    readonly sockets: Set<Held>;
+    readonly root: string | undefined;
+    static open(state: State, env: Env, classes?: Record<string, BeingClass>): Promise<EdgeHarbor>;
+    constructor(store: DurableStorage, root: string | undefined, classes: Record<string, BeingClass>);
+    ready(): Promise<void>;
+    fetch(request: Request, path: string): Promise<Response>;
+    health(): {
+        ok: boolean;
+        wards: {
+            [k: string]: string;
+        };
+        reaches: {
+            [k: string]: string;
+        };
+        sockets: number;
+    };
+    upgrade(): Response;
+    rootAsk(request: Request): Promise<Response>;
+}

package/dist/harbor/edge/edge.js

@@ -0,0 +1,123 @@
+import { isSilence } from '@quo-systems/quo';
+import { User, Desk, Avatar } from '../../beings/index.js';
+import { setup } from '../../beings/setup.js';
+import { Harbor, Socket as Held, SUITE } from '@quo-systems/quo/harbor';
+import { DurableStorage, sealKey } from './storage.js';
+export const BUILT_IN = { User, Desk, Avatar };
+const json = (status, v, headers = {}) => new Response(JSON.stringify(v), { status, headers: { 'content-type': 'application/json', ...headers } });
+const open = { 'access-control-allow-origin': '*', 'access-control-allow-methods': 'POST, OPTIONS', 'access-control-allow-headers': 'content-type, quo-suite' };
+export class EdgeHarbor extends Harbor {
+    sockets = new Set();
+    root;
+    #booted;
+    static async open(state, env, classes = {}) {
+        if (!env.QUO_SEED_KEY)
+            throw new Error('no QUO_SEED_KEY: a seed is never kept plain on the edge');
+        return new EdgeHarbor(new DurableStorage(state.storage, await sealKey(env.QUO_SEED_KEY)), env.QUO_ROOT, classes);
+    }
+    constructor(store, root, classes) {
+        super(store, async () => ({ ...BUILT_IN, ...classes }));
+        this.root = root;
+    }
+    // Once per instance, on the first request: the platform may have woken a
+    // fresh instance, and every ward boots from storage before anything is
+    // answered.
+    ready() {
+        return (this.#booted ??= this.boot());
+    }
+    // The worker hands the request here with the path after the harbor's
+    // prefix: `/quo/<pk>`, `/quo`, `/health`, `/root`.
+    async fetch(request, path) {
+        await this.ready();
+        if (path === '/health')
+            return json(200, this.health(), { 'access-control-allow-origin': '*' });
+        if (path === '/root')
+            return this.rootAsk(request);
+        if (path === '/quo' || path === '/quo/') {
+            if (request.headers.get('upgrade')?.toLowerCase() === 'websocket')
+                return this.upgrade();
+            return json(404, { error: 'POST /quo/<pk>' }, open);
+        }
+        if (path.startsWith('/quo/')) {
+            if (request.method === 'OPTIONS')
+                return new Response(null, { status: 204, headers: open });
+            const pk = path.slice(5);
+            if (request.method !== 'POST' || !/^[0-9a-f]{128}$/.test(pk))
+                return json(404, { error: 'POST /quo/<pk>' }, open);
+            // The wire suite, read before anything is carried: a caller speaking
+            // another one is answered nothing delivered, as the daemon's door does.
+            const suite = request.headers.get('quo-suite');
+            if (suite !== null && suite !== String(SUITE))
+                return json(404, { error: `this door speaks wire suite ${SUITE}` }, open);
+            const back = await this.deliver(pk, new Uint8Array(await request.arrayBuffer()));
+            if (back === undefined)
+                return json(404, { error: 'no reach for that pk' }, open);
+            return new Response(back, { status: 200, headers: { 'content-type': 'application/octet-stream', ...open } });
+        }
+        return json(404, { error: 'no such route' });
+    }
+    health() {
+        return {
+            ok: true,
+            wards: Object.fromEntries([...this.wards].map(([n, h]) => [n, h.pk])),
+            reaches: Object.fromEntries([...this.reaches].map(([pk, b]) => [pk, b.held ? 'held' : 'reach'])),
+            sockets: this.sockets.size,
+        };
+    }
+    // A dialer's socket: the server end of a pair, held here, its pks bound
+    // at announce and unbound at close. The platform keeps the object awake
+    // while the socket is open.
+    upgrade() {
+        const pair = new WebSocketPair();
+        const server = pair[1];
+        server.accept();
+        const s = new Held(server, (pk, bytes) => this.deliver(pk, bytes), (far) => void this.bind(far, s, true), () => {
+            this.unbind(s);
+            this.sockets.delete(s);
+        });
+        this.sockets.add(s);
+        s.announce([...this.doors.keys()]);
+        return new Response(null, { status: 101, webSocket: pair[0] });
+    }
+    // The root's door. Under the secret only; without one configured the
+    // edge has no root at all, and every owner it will ever have was invited
+    // by a root that existed when it did.
+    async rootAsk(request) {
+        const bearer = request.headers.get('authorization')?.replace(/^Bearer\s+/i, '') ?? '';
+        if (request.method !== 'POST' || !this.root || bearer.length !== this.root.length || !same(bearer, this.root))
+            return json(401, { error: 'the root holds the secret' });
+        let body = {};
+        try {
+            body = (await request.json());
+        }
+        catch {
+            return json(400, { error: 'a root ask is JSON' });
+        }
+        try {
+            if (body.init) {
+                const name = typeof body.init.ward === 'string' ? body.init.ward : 'main';
+                const user = typeof body.init.user === 'string' ? body.init.user : 'me';
+                if (this.wards.has(name))
+                    return json(409, { error: `ward ${name} already exists here` });
+                const hosted = await this.create(name, user);
+                await setup(hosted, user);
+                return json(200, { name, pk: hosted.pk, user });
+            }
+            const hosted = this.wards.get(typeof body.ward === 'string' ? body.ward : 'main');
+            if (!hosted)
+                return json(404, { error: 'no such ward' });
+            const out = await hosted.ask(typeof body.method === 'string' ? body.method : undefined, (body.args ?? {}));
+            return json(200, { result: isSilence(out) ? { silence: true } : out });
+        }
+        catch (e) {
+            return json(500, { error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+}
+// Constant time, as far as a comparison in a worker can be.
+function same(a, b) {
+    let out = 0;
+    for (let i = 0; i < a.length; i++)
+        out |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return out === 0;
+}

package/dist/harbor/edge/exercise.d.ts

@@ -0,0 +1,7 @@
+import type { State, Env } from './platform.d.ts';
+export type Result = {
+    name: string;
+    skip?: string;
+    error?: string;
+};
+export declare function exercise(request: Request, base: string, path: string, state: State, env: Env): Promise<Response>;

package/dist/harbor/edge/exercise.js

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: Apache-2.0
+// What the edge terrain runs, inside the platform: the library's
+// conformance suite against two edge harbors in one object, each over its
+// own prefixed view of the object's storage, reaching each other by request
+// through the worker's own origin under `/x/<sub>/quo`, so every relation
+// crosses the route. Down is the reach refused on both; migrate lifts seed,
+// partition and record out of one view into the other and boots there. It
+// reports rather than throws, so the worker hands the list back and Node
+// asserts on it. Only with `QUO_EXERCISE` set, which a deployment never sets.
+import { conform, conformStore, conformReach } from '@quo-systems/quo/conformance';
+import { request as byRequest } from '@quo-systems/quo/harbor';
+import { Printer, Shop, Customer, Echo, Member } from '@quo-systems/quo/conformance';
+import { EdgeHarbor } from './edge.js';
+import { DurableStorage, sealKey } from './storage.js';
+const assert = {
+    equal(a, b, m) {
+        if (a !== b)
+            throw new Error(`${m}: ${JSON.stringify(a)} is not ${JSON.stringify(b)}`);
+    },
+    deepEqual(a, b, m = 'not equal') {
+        if (JSON.stringify(a) !== JSON.stringify(b))
+            throw new Error(`${m}: ${JSON.stringify(a)} is not ${JSON.stringify(b)}`);
+    },
+};
+const CLASSES = { Printer, Shop, Customer, Echo, Member };
+// The harbors the exercise made, by sub name, for the router below.
+const subs = new Map();
+async function pair(state, env, run) {
+    const key = await sealKey(env.QUO_SEED_KEY ?? '');
+    const names = [`a-${run}-${Date.now()}`, `b-${run}-${Date.now()}`];
+    const harbors = names.map((n) => new EdgeHarbor(new DurableStorage(state.storage, key, `x:${n}:`), undefined, CLASSES));
+    for (const [i, h] of harbors.entries()) {
+        await h.ready();
+        subs.set(names[i], h);
+    }
+    return { harbors, names };
+}
+function probe(base, state, env) {
+    let n = 0;
+    return async () => {
+        const p = await pair(state, env, n++);
+        const wardOf = new Map();
+        const where = new Map();
+        let k = 0;
+        const at = (name) => {
+            const h = p.harbors[where.get(name)];
+            const w = h.wards.get(name);
+            return { h, w, p: w.partition };
+        };
+        // the far harbor learns the pk by a hint: the link's reach hint, this world's route
+        const learn = (i, w) => p.harbors[1 - i].hint(w.pk, `${base}/x/${p.names[i]}/quo`);
+        return {
+            oneWard: false,
+            async boot(key, Class, cells = {}, { isPublic = false } = {}) {
+                for (const h of p.harbors)
+                    h.classes[Class.name] = Class;
+                const name = `W-${key}`;
+                const i = where.get(name) ?? k++ % 2;
+                const h = p.harbors[i];
+                const w = h.wards.get(name) ?? (await h.create(name));
+                if (!where.has(name)) {
+                    where.set(name, i);
+                    learn(i, w);
+                }
+                wardOf.set(key, name);
+                assert.deepEqual(await w.ask('boot', { key, class: Class.name, public: isPublic }), { booted: key });
+                if (Object.keys(cells).length)
+                    Object.assign(at(name).p.beings[key], cells);
+                return {
+                    pk: w.pk,
+                    get cells() {
+                        return at(name).p.beings[key];
+                    },
+                    get being() {
+                        return at(name).w.being(key);
+                    },
+                    minted: { has: (pk) => at(name).p.bind[key].minted.includes(pk) },
+                    forgeKnock: (inv) => void (at(name).p.bind[key].knocks[`${inv.ward}:${inv.heir}`] = { current: 'ab'.repeat(32), next: null, spoke: true, sent: true, seq: 0 }),
+                    set down(v) {
+                        for (const each of p.harbors) {
+                            if (v)
+                                each.down.add(at(name).w.pk);
+                            else
+                                each.down.delete(at(name).w.pk);
+                        }
+                    },
+                    get down() {
+                        return p.harbors[0].down.has(at(name).w.pk);
+                    },
+                };
+            },
+            heir(inv) {
+                for (const h of p.harbors)
+                    for (const w of h.wards.values())
+                        if (w.pk === inv.ward) {
+                            const r = w.partition.heirs[inv.heir];
+                            return r && { current: r.current, announced: r.announced, fresh: r.fresh };
+                        }
+                return undefined;
+            },
+            census() {
+                const c = { wards: {}, binds: {}, cells: {} };
+                for (const h of p.harbors)
+                    for (const w of h.wards.values()) {
+                        const pt = w.partition;
+                        c.wards[w.pk] = { beings: Object.keys(pt.beings), public: pt.public, heirs: Object.fromEntries(Object.entries(pt.heirs).map(([pk, r]) => [pk, { being: r.being, id: r.id, current: r.current, announced: r.announced, fresh: r.fresh, mark: r.mark, spent: [...r.spent] }])) };
+                        for (const [key, b] of Object.entries(pt.bind)) {
+                            c.binds[key] = {
+                                ward: w.pk,
+                                standings: Object.fromEntries(Object.entries(b.standings).map(([id, s]) => [id, { ward: s.ward, heir: s.heir, seq: s.seq }])),
+                                occupants: { ...b.occupants },
+                                knocks: Object.keys(b.knocks),
+                                answered: Object.keys(b.answered),
+                                minted: [...b.minted],
+                                secrets: [...Object.values(b.standings).flatMap((s) => [s.current, s.next]), ...Object.values(b.knocks).flatMap((s) => [s.current, s.next])].filter((x) => x !== null),
+                            };
+                            c.cells[key] = pt.beings[key];
+                        }
+                    }
+                return c;
+            },
+            // seed, partition and record lifted out of one object's storage into
+            // the other's, same seed, same pk; the old copy gone before the new boots
+            async migrate(key) {
+                const name = wardOf.get(key);
+                const from = where.get(name), to = 1 - from;
+                const pk = p.harbors[from].wards.get(name).pk;
+                const kept = (await p.harbors[from].drop(name));
+                const w = await p.harbors[to].adopt(name, kept);
+                assert.equal(w.pk, pk, 'a ward that moved harbor changed its pk');
+                where.set(name, to);
+                p.harbors[from].reaches.delete(pk);
+                learn(to, w);
+            },
+        };
+    };
+}
+// `/exercise` runs the suite; `/x/<sub>/quo/<pk>` is a sub-harbor's route,
+// which is how the two reach each other through the worker.
+export async function exercise(request, base, path, state, env) {
+    const sub = /^\/x\/([\w.-]+)(\/.*)$/.exec(path);
+    if (sub) {
+        const h = subs.get(sub[1]);
+        if (!h)
+            return new Response(JSON.stringify({ error: 'no such harbor' }), { status: 404, headers: { 'content-type': 'application/json' } });
+        return h.fetch(request, sub[2]);
+    }
+    const queued = [];
+    const test = (name, opts, fn) => {
+        queued.push({ name, skip: opts.skip ?? false, fn });
+    };
+    const key = await sealKey(env.QUO_SEED_KEY ?? '');
+    let views = 0;
+    conformStore('durable storage', async () => new DurableStorage(state.storage, key, `s:${views++}:${Date.now()}:`), { test });
+    let lines = 0;
+    conformReach('request, through the worker', async () => {
+        const name = `r-${lines++}-${Date.now()}`;
+        const h = new EdgeHarbor(new DurableStorage(state.storage, key, `x:${name}:`), undefined, CLASSES);
+        await h.ready();
+        subs.set(name, h);
+        return { reach: byRequest(`${base}/x/${name}/quo`), hold: async (pk, door) => void h.doors.set(pk, async (b) => ({ bytes: await door(b), heard: true })), drop: async () => void subs.delete(name) };
+    }, { test });
+    conform('edge, two harbors in one object by request', probe(base, state, env), { canDown: true, test });
+    const results = [];
+    for (const { name, skip, fn } of queued) {
+        if (skip) {
+            results.push({ name, skip });
+            continue;
+        }
+        try {
+            await fn();
+            results.push({ name });
+        }
+        catch (e) {
+            results.push({ name, error: String(e?.stack ?? e) });
+        }
+    }
+    return new Response(JSON.stringify({ results }), { headers: { 'content-type': 'application/json' } });
+}