@nervur-org/dock 0.3.0

package/harbor/edge/edge.ts

@@ -0,0 +1,407 @@
+// SPDX-License-Identifier: Apache-2.0
+// The edge harbor: the core over one Durable Object. The object is the
+// harbor, and the platform is its lease: one instance of it runs at a time,
+// which is the single writer every ward needs. The store is the object's
+// storage with the seed sealed under a platform secret; the code is the
+// deployed worker, the built-in beings plus whatever the worker hands in.
+// It is a listener and never a dialer: reached by request at its route,
+// holding the sockets dialers open to it, the rendezvous for them. It wakes
+// per request, and a held socket keeps it awake.
+//
+// Its owner door is a route, not a socket: the platform has no local
+// process, so the root is whoever holds `QUO_ROOT`, a platform secret, and
+// the root's asks arrive as one POST under it. That is the device's own
+// rule on this terrain, as file permissions are on a disk. The first thing
+// a root does is invite an owner on the ward's pk, and from then on the
+// edge is piloted from elsewhere over a standing, like any ward.
+//
+//   POST <route>/quo/<pk>      one sealed ask to a pk held here, or on a socket here
+//   GET  <route>/quo  upgrade  a dialer's held socket, its pks bound at announce
+//   GET  <route>/health        the wards, the directory, the sockets
+//   GET  <route>/web/...       the worlds' pages, the same route the daemon serves
+//   <route>/api/...            the program side, the same route the daemon serves
+//   <route>/mcp/...            the model side, the dance and the endpoint
+//   GET  <route>/.well-known/  the dance's discovery, for a caller at this prefix
+//   POST <route>/root          { init: { ward, user } } | { ward?, method?, args? }, under the root secret
+//   POST <route>/root          { settings } merged and answered, { wear } a design file put or taken
+//
+// What the sides here are given is `given.ts`: the bundles and classes the
+// deploy carries, the settings the root's door writes, and the design rows
+// those pages are painted with. It also holds what this terrain lends, since
+// a worker stands a box ward like every other terrain: the box's state has
+// one home everywhere, and what differs is which faculties that ward lends.
+import type { BeingClass } from '@nervur-org/nervur';
+import { isSilence } from '@nervur-org/nervur';
+import { User, Desk, Avatar, Clock } from '../../beings/index.ts';
+import { setup } from '../../beings/setup.ts';
+import { Harbor, Socket as Held } from '@nervur-org/nervur/harbor';
+import { quoRoute } from '../quo.ts';
+import { webRoute, type Folder } from '../../human/web.ts';
+import { DOCK, TIMER, Console, facultyOf, settled, stand } from '../../dock/index.ts';
+import { Alarm, alarmsIn } from './alarm.ts';
+import { Grants, GRANTS } from '../../dock/grants.ts';
+import { find, letIn } from '../../beings/join.ts';
+import { apiRoute } from '../../api/route.ts';
+import { mcpRoute, type Routes } from '../../mcp/route.ts';
+import { McpHttp } from '../../mcp/http.ts';
+import { Exchange } from '../../mcp/allow.ts';
+import type { Invitation } from '@nervur-org/nervur';
+import { DurableStorage, danceInStorage, folderInStorage, settingsInStorage, wearInStorage } from './storage.ts';
+import { LENT, type Deployed, type Given, type Settings, type SettingsStore } from './given.ts';
+import { sealKey } from '../seal.ts';
+import type { State, Env, Storage } from './platform.d.ts';
+
+// The beings a deployed worker carries. The Clock is among them because this
+// terrain lends a timer: a box that lends one and holds no class that can ask
+// for a wake lends a name nobody there could use.
+export const BUILT_IN: Record<string, BeingClass> = { User, Desk, Avatar, Clock };
+const json = (status: number, v: unknown, headers: Record<string, string> = {}) => new Response(JSON.stringify(v), { status, headers: { 'content-type': 'application/json', ...headers } });
+
+export class EdgeHarbor extends Harbor {
+  readonly sockets = new Set<Held>();
+  readonly root: string | undefined;
+  // What the deploy carried, held from the worker's first line.
+  readonly deployed: Deployed;
+  // The rows: the settings a root writes, and the design a world wears.
+  readonly settings: SettingsStore;
+  readonly folder: Folder;
+  readonly wear: ReturnType<typeof wearInStorage>;
+  // The model side's dance, one key in the same object: clients, pending
+  // requests and codes, all of them living minutes.
+  readonly dance: ReturnType<typeof danceInStorage>;
+  // The object's storage, unprefixed and unsealed: the alarm is the object's
+  // own and is no row.
+  readonly #storage: Storage;
+  #booted: Promise<void> | undefined;
+  // The MCP endpoint, one per instance: a session is a client's connection
+  // and belongs to the harbor, not to the request that opened it.
+  #mcp: McpHttp | undefined;
+
+  // A deployed worker: the box ward stands and lends what this terrain can
+  // answer. The exercise builds harbors with the constructor instead and
+  // says nothing, so it stands no ward of its own, as a command on a disk
+  // folder stands none.
+  static async open(state: State, env: Env, deployed: Deployed = {}): Promise<EdgeHarbor> {
+    if (!env.QUO_SEED_KEY) throw new Error('no QUO_SEED_KEY: a seed is never kept plain on the edge');
+    const harbor = new EdgeHarbor(new DurableStorage(state.storage, await sealKey(env.QUO_SEED_KEY)), env.QUO_ROOT, deployed);
+    harbor.lent = LENT;
+    return harbor;
+  }
+
+  constructor(store: DurableStorage, root: string | undefined, deployed: Deployed = {}) {
+    // The faculty classes this terrain can stand, beside the beings: the box
+    // ward's own front desk and the grants its routes honour. They are named
+    // here and not left to the deploy, because `lent` names classes and a
+    // name the loader cannot find is a ward that would not boot.
+    super(store, async () => ({ ...BUILT_IN, Console, Grants, Alarm, ...deployed.classes }));
+    this.root = root;
+    this.deployed = deployed;
+    this.#storage = store.storage;
+    // The rows live beside the wards in the same object, under the same
+    // prefix, so an exercise standing two harbors in one object gives each
+    // its own settings and its own design.
+    this.settings = settingsInStorage(store.storage, store.prefix);
+    this.folder = folderInStorage(store.storage, store.prefix);
+    this.wear = wearInStorage(store.storage, store.prefix);
+    this.dance = danceInStorage(store.storage, store.prefix);
+  }
+
+  // The whole of what a side is handed, read at every request: the deploy's
+  // half never changes and the rows are worn while the worker runs.
+  async given(): Promise<Given> {
+    return { ...this.deployed, settings: await this.settings.load(), folder: this.folder };
+  }
+
+  // What this box lends, by name. Set before the first request and read at
+  // the boot; a harbor that says nothing stands no ward of its own and lends
+  // nothing. `given.ts` holds the list a deployed worker uses and why it is
+  // that list.
+  lent: Record<string, string> | undefined;
+
+  // 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(): Promise<void> {
+    return (this.#booted ??= this.boot());
+  }
+
+  // The box's own ward first, because a being born in any other ward lends
+  // from her first line and a ground that could not reach it yet would leave
+  // her holding nothing until her next birth. Then every ward the object
+  // keeps, then the beings who took what the box lends: a box is up when
+  // they have landed.
+  override async boot(): Promise<void> {
+    if (this.lent) {
+      this.lend = await stand(this, this.lent);
+      // A token issued is a cell written, and the cells are the dock ward's
+      // partition like every faculty's: there is no second place on this
+      // terrain for the box to keep its state.
+      const grants = facultyOf<Grants>(this, GRANTS);
+      if (grants) grants.persist = () => this.wards.get(DOCK)?.save() ?? Promise.resolve();
+      // The clock here is the object's alarm, and only the object may set its
+      // own, so the timer is handed the two calls the same way.
+      const timer = facultyOf<Alarm>(this, TIMER);
+      if (timer) timer.alarms = alarmsIn(this.#storage);
+    }
+    await super.boot();
+    await settled();
+  }
+
+  // The alarm went off: no request, no route and nobody asking, which is the
+  // whole point of it. The box ward is up by now, so the round runs and the
+  // timer arms for whatever the Clocks say they are next due at.
+  //
+  // The wards are written here because no ask returned to write them: a wake
+  // went through a Clock's own door and wrote her fires, and the harbor never
+  // saw it. A box whose alarm fired and whose partition was not written would
+  // fire the same minute again on its next wake.
+  async rang(): Promise<void> {
+    const timer = facultyOf<Alarm>(this, TIMER);
+    if (!timer) return;
+    try {
+      await timer.rang();
+    } finally {
+      await timer.setting;
+      for (const w of this.wards.values()) await w.save();
+    }
+  }
+
+  // The box's grants, for the routes that honour a bearer. Undefined is a
+  // harbor that stands no box ward, which is the exercise and nothing a
+  // deploy does.
+  get grants(): Grants | undefined {
+    return facultyOf<Grants>(this, GRANTS);
+  }
+
+  // The web side, built per request because its whole configuration is rows
+  // a root writes while the worker runs. It is the same `webRoute` the daemon
+  // mounts, handed the same things by a terrain that has no disk: the bundles
+  // from the deploy, the design out of storage, the origins out of the
+  // settings, and the worker's own address when no root has named one.
+  //
+  // A deployment carrying no bundles serves no page at all, and says so
+  // rather than serving one that loads nothing.
+  //
+  // The credential exchange's allow page shares this prefix, as it does on
+  // the daemon: the worlds' pages first, then the page where a human hands
+  // an invitation and the model side's dance finishes.
+  async web(request: Request, path: string, base: string): Promise<Response> {
+    const given = await this.given();
+    if (!given.code) return json(404, { error: 'this deployment carries no page code' });
+    const at = await this.routes(base);
+    const route = webRoute(this, { at, code: given.code, folder: given.folder, apps: given.settings.apps ?? null, bell: given.settings.bell ?? null });
+    const rest = path.slice('/web'.length);
+    const page = await route(request, rest);
+    if (page) return page;
+    const exchange = await this.exchange(base);
+    return (await exchange?.handle(request, rest)) ?? new Response('no such page', { status: 404, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+  }
+
+  // Where the four routes answer, as the world outside sees them: what a root
+  // named, and the worker's own address under this harbor's prefix for every
+  // one it did not.
+  async routes(base: string): Promise<Routes & { quo: string; api: string }> {
+    const r = (await this.settings.load()).routes;
+    return { quo: r?.quo ?? `${base}/quo`, web: r?.web ?? `${base}/web`, mcp: r?.mcp ?? `${base}/mcp`, api: r?.api ?? `${base}/api` };
+  }
+
+  // Which ward a caller who names none is at. On a disk it is the mark an
+  // operator wrote in the folder; here it is the one world this object holds,
+  // and an object holding several says nothing rather than guessing, exactly
+  // as a folder with several wards and no mark does. The box's own ward is
+  // furniture and never a candidate.
+  here(): string {
+    const worlds = [...this.wards.keys()].filter((n) => n !== DOCK);
+    return worlds.length === 1 ? worlds[0] : '';
+  }
+
+  // What a route asks of a ward here: her avatar as she stands, and her way
+  // in with an invitation. Both are `beings/join.ts`, the same two the daemon
+  // hands its own routes.
+  #resolve = async (identity: string, ward: string) => {
+    const hosted = this.wards.get(ward);
+    return hosted ? find(hosted, identity) : { error: 'no such world' };
+  };
+  #join = async (identity: string, invitation: Invitation, ward: string) => {
+    const hosted = this.wards.get(ward);
+    if (!hosted) return { error: 'no such world' };
+    const r = await letIn(hosted, identity, invitation);
+    return r.error ? { error: r.error } : {};
+  };
+  // The worlds a client may be let into: every ward here but the box's own.
+  #worlds = () =>
+    [...this.wards]
+      .filter(([ward]) => ward !== DOCK)
+      .map(([ward, h]) => ({ ward, pk: h.pk, user: h.record.user }));
+
+  // The program side. The same `apiRoute` the daemon mounts, on the grants of
+  // this box's own ward: a request with no bearer is the stranger every route
+  // knows, and one with a bearer this box granted is an occupant.
+  async api(request: Request, path: string, base: string): Promise<Response> {
+    const grants = this.grants;
+    if (!grants) return json(503, { error: 'this box stands no ward of its own, so it grants nothing' });
+    const at = await this.routes(base);
+    const route = apiRoute({ wards: this.wards, here: () => this.here() }, { grants, resolve: this.#resolve, join: this.#join, web: at.web });
+    return (await route(request, path.slice('/api'.length))) ?? json(404, { error: 'no such route' });
+  }
+
+  // The model side: the OAuth dance, kept in this object's own storage, and
+  // the MCP endpoint beside it. The endpoint's sessions live on this harbor
+  // and not on the request, because a session is a client's connection and
+  // outlives the fetch that opened it; the platform keeps the object awake
+  // while one is held and a client that comes back to a woken instance
+  // reconnects, which is what a reconnect is for.
+  async mcp(request: Request, path: string, base: string): Promise<Response> {
+    const grants = this.grants;
+    if (!grants) return json(503, { error: 'this box stands no ward of its own, so it grants nothing' });
+    const endpoint = (this.#mcp ??= new McpHttp(this.#resolve, async () => {
+      for (const h of this.wards.values()) await h.save();
+    }));
+    endpoint.gone = (identity, ward) => grants.revoke(identity, ward); // removal at the ward ends the grant at the box
+    const route = await mcpRoute(this.dance, await this.routes(base), endpoint, grants);
+    const rest = path.slice('/mcp'.length);
+    return (await route.handler(request, rest)) ?? json(404, { error: 'no such route' });
+  }
+
+  // The dance's discovery under this prefix, for a caller that reaches the
+  // harbor at a path rather than at an origin of its own.
+  async wellKnown(request: Request, path: string, base: string): Promise<Response> {
+    const grants = this.grants;
+    if (!grants) return json(404, { error: 'no such route' });
+    const route = await mcpRoute(this.dance, await this.routes(base), null, grants);
+    return (await route.wellKnown(request, path.slice('/.well-known'.length))) ?? json(404, { error: 'no such route' });
+  }
+
+  // The exchange, for the allow page on the web side: the dance it finishes
+  // is the same one the model side keeps.
+  async exchange(base: string): Promise<Exchange | undefined> {
+    const grants = this.grants;
+    if (!grants) return undefined;
+    const route = await mcpRoute(this.dance, await this.routes(base), null, grants);
+    return new Exchange({ oauth: route.oauth, worlds: this.#worlds, join: this.#join });
+  }
+
+  // The worker hands the request here with the path after the harbor's
+  // prefix, and with that prefix as an address, since a page tells a tab
+  // where to dial: `/quo/<pk>`, `/quo`, `/health`, `/root`, `/web`.
+  // Every door of this object, and one thing after all of them: the arming.
+  // A schedule kept at any of them moves the moment the box is armed for, an
+  // arming here is a write to the object's storage, and the ask that caused
+  // it cannot answer for it. So the response waits for the write, because a
+  // box that answered "kept" and was put to sleep before its alarm landed is
+  // a schedule nothing would fire.
+  async fetch(request: Request, path: string, base: string): Promise<Response> {
+    await this.ready();
+    const out = await this.#route(request, path, base);
+    await facultyOf<Alarm>(this, TIMER)?.setting;
+    return out;
+  }
+
+  async #route(request: Request, path: string, base: string): Promise<Response> {
+    if (path === '/health') return json(200, this.health(), { 'access-control-allow-origin': '*' });
+    if (path === '/root') return this.rootAsk(request);
+    if (path === '/web' || path.startsWith('/web/')) return this.web(request, path, base);
+    if (path === '/api' || path.startsWith('/api/')) return this.api(request, path, base);
+    if (path === '/mcp' || path.startsWith('/mcp/')) return this.mcp(request, path, base);
+    if (path.startsWith('/.well-known/')) return this.wellKnown(request, path, base);
+    // The sealed bytes are the same route the daemon mounts; the upgrade is
+    // this terrain's own listener half, a socket pair held by the object.
+    if (path === '/quo' || path.startsWith('/quo/')) {
+      if ((path === '/quo' || path === '/quo/') && request.headers.get('upgrade')?.toLowerCase() === 'websocket') return this.upgrade();
+      return (await quoRoute(this)(request, path.slice('/quo'.length))) ?? json(404, { error: 'no such route' });
+    }
+    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,
+      // How many saves this object's storage refused, per ward. A refusal is
+      // already the answer of the ask that caused it, so nobody is waiting to
+      // be told; this is the other half, which is an operator asking the box
+      // how it is and being told about the one fault a healthy-looking box
+      // can carry for hours. Zero wards refused is an empty object, and the
+      // shape does not move.
+      faults: Object.fromEntries([...this.faults]),
+    };
+  }
+
+  // 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(): Response {
+    const pair = new WebSocketPair();
+    const server = pair[1];
+    server.accept();
+    const s: Held = 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: Request): Promise<Response> {
+    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: { init?: { ward?: unknown; user?: unknown }; settings?: Partial<Settings>; wear?: Record<string, unknown>; ward?: unknown; method?: unknown; args?: unknown } = {};
+    try {
+      body = (await request.json()) as typeof body;
+    } 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 });
+      }
+      // The settings, merged over what is kept and answered whole, so a root
+      // that writes one field sees the rest and a root that writes nothing
+      // reads the row. This is how a box is configured after it is deployed:
+      // the origins the proxy serves, the apps table and the bell key.
+      if (body.settings) {
+        const settings = { ...(await this.settings.load()), ...body.settings };
+        await this.settings.save(settings);
+        return json(200, { settings });
+      }
+      // One design file put there, or taken away with null, and the names now
+      // worn. A world wears a design only when it holds `tokens.css`.
+      if (body.wear) {
+        for (const [file, text] of Object.entries(body.wear)) {
+          if (!/^[\w.-]+$/.test(file) && !/^fonts\/[\w.-]+$/.test(file)) return json(400, { error: `not a design file: ${file}` });
+          await this.wear.put(file, typeof text === 'string' ? text : null);
+        }
+        return json(200, { worn: await this.wear.worn() });
+      }
+      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 ?? {}) as Record<string, unknown>);
+      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: string, b: string): boolean {
+  let out = 0;
+  for (let i = 0; i < a.length; i++) out |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return out === 0;
+}

package/harbor/edge/exercise.ts

@@ -0,0 +1,241 @@
+// 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 '@nervur-org/nervur/conformance';
+import { request as byRequest } from '@nervur-org/nervur/harbor';
+import type { World, Handle, Census } from '@nervur-org/nervur/conformance';
+import { Printer, Shop, Customer, Echo, Member } from '@nervur-org/nervur/conformance';
+import type { BeingClass, Cells, Invitation, JsonObject } from '@nervur-org/nervur';
+import { EdgeHarbor } from './edge.ts';
+import { DurableStorage } from './storage.ts';
+import { ROW_CEILING } from './given.ts';
+import { told } from '@nervur-org/nervur';
+import { sealKey } from '../seal.ts';
+import type { Hosted } from '@nervur-org/nervur/harbor';
+import type { State, Env } from './platform.d.ts';
+
+export type Result = { name: string; skip?: string; error?: string };
+const assert = {
+  equal(a: unknown, b: unknown, m: string) {
+    if (a !== b) throw new Error(`${m}: ${JSON.stringify(a)} is not ${JSON.stringify(b)}`);
+  },
+  deepEqual(a: unknown, b: unknown, m = 'not equal') {
+    if (JSON.stringify(a) !== JSON.stringify(b)) throw new Error(`${m}: ${JSON.stringify(a)} is not ${JSON.stringify(b)}`);
+  },
+};
+type Partition = { beings: Record<string, Cells>; bind: Record<string, { standings: Record<string, { ward: string; heir: string | null; seq: number; current: string | null; next: string | null }>; occupants: Record<string, string>; knocks: Record<string, { current: string | null; next: string | null }>; answered: Record<string, unknown>; minted: string[] }>; heirs: Record<string, { being: string; id: string; current: string; announced: string | null; fresh: boolean; mark: number; spent: number[] }>; public: string | null };
+// The suite's own classes, and no bundles: the exercise mounts no side and
+// serves no page, so this deployment names no code.
+const DEPLOYED = { classes: { Printer, Shop, Customer, Echo, Member } satisfies Record<string, BeingClass> };
+
+// The harbors the exercise made, by sub name, for the router below.
+const subs = new Map<string, EdgeHarbor>();
+
+async function pair(state: State, env: Env, run: number): Promise<{ harbors: EdgeHarbor[]; names: string[] }> {
+  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, DEPLOYED));
+  for (const [i, h] of harbors.entries()) {
+    await h.ready();
+    subs.set(names[i], h);
+  }
+  return { harbors, names };
+}
+
+function probe(base: string, state: State, env: Env): () => Promise<World> {
+  let n = 0;
+  return async () => {
+    const p = await pair(state, env, n++);
+    const wardOf = new Map<string, string>();
+    const where = new Map<string, number>();
+    let k = 0;
+    const at = (name: string) => {
+      const h = p.harbors[where.get(name)!];
+      const w = h.wards.get(name)!;
+      return { h, w, p: h.partitionOf(name) as unknown as Partition };
+    };
+    // the far harbor learns the pk by a hint: the link's reach hint, this world's route
+    const learn = (i: number, w: Hosted) => p.harbors[1 - i].hint(w.pk, `${base}/x/${p.names[i]}/quo`);
+    return {
+      oneWard: false,
+      async boot<B>(key: string, Class: BeingClass, cells: JsonObject = {}, { isPublic = false } = {}): Promise<Handle<B>> {
+        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 }), { booted: key });
+        if (isPublic) assert.deepEqual(await w.ask('public', { key }), { public: 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) as B;
+          },
+          minted: { has: (pk: string) => at(name).p.bind[key].minted.includes(pk) },
+          forgeKnock: (inv: Invitation) => void ((at(name).p.bind[key].knocks as Record<string, unknown>)[`${inv.ward}:${inv.heir}`] = { current: 'ab'.repeat(32), next: null, spoke: true, sent: true, seq: 0 }),
+          set down(v: boolean) {
+            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: Invitation) {
+        for (const h of p.harbors)
+          for (const w of h.wards.values())
+            if (w.pk === inv.ward) {
+              const r = (h.partitionOf(w.name) as unknown as Partition).heirs[inv.heir!];
+              return r && { current: r.current, announced: r.announced, fresh: r.fresh };
+            }
+        return undefined;
+      },
+      census(): Census {
+        const c: Census = { wards: {}, binds: {}, cells: {} };
+        for (const h of p.harbors)
+          for (const w of h.wards.values()) {
+            const pt = h.partitionOf(w.name) as unknown as 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 is string => 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
+      owner(key: string) {
+        return (method?: string, args?: JsonObject) => at(wardOf.get(key)!).w.ask(method, args);
+      },
+      async migrate(key: string): Promise<void> {
+        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: Request, base: string, path: string, state: State, env: Env): Promise<Response> {
+  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], `${base}/x/${sub[1]}`);
+  }
+  const queued: { name: string; skip: string | false; fn: () => Promise<void> | void }[] = [];
+  const test = (name: string, opts: { skip?: string | false }, fn: () => Promise<void> | void) => {
+    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, DEPLOYED);
+      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, canLend: false, canRestart: false, test });
+
+  // The ceiling, on the terrain that has one. A being whose row is past it is
+  // refused by the store before the platform is asked, the arrival that wrote
+  // the row is a failed ask at the door, and she is left standing at what the
+  // object keeps rather than at what she was answered.
+  // The ceiling here is small, so what crosses the door is a few kilobytes:
+  // a row of the platform's real size costs a great deal to carry and proves
+  // the same refusal. That the number a deployment runs under is the
+  // platform's own is the line below it, which asks the store directly.
+  test('[edge] a row past the object s ceiling is refused, the arrival that wrote it fails at the door, and she stands at what is kept', {}, async () => {
+    const key = await sealKey(env.QUO_SEED_KEY ?? '');
+    const small = 8_000;
+    const h = new EdgeHarbor(new DurableStorage(state.storage, key, `c:${Date.now()}:`, small), undefined, DEPLOYED);
+    await h.ready();
+    const w = await h.create(`ceiling-${Date.now()}`);
+    for (const [k, c] of [
+      ['P', 'Printer'],
+      ['A', 'Customer'],
+    ])
+      assert.deepEqual(await w.ask('boot', { key: k, class: c }), { booted: k });
+    const printer = w.being('P') as unknown as Printer;
+    const alice = w.being('A') as unknown as Customer;
+    const inv = (await printer.invite('a'))!;
+    assert.deepEqual(await alice.knock(inv, 'print', { doc: 'one' }), { printed: 'one' });
+
+    const out = await alice.knock(inv, 'print', { doc: 'x'.repeat(small * 2) });
+    assert.equal(told(out), 'threw', 'a row the object will not keep is a failed ask at the door');
+    const jobs = (printer.cells.jobs as { doc: unknown }[]).map((j) => j.doc);
+    assert.deepEqual(jobs, ['one'], 'she stands at what is kept, and not at what she was answered');
+    assert.deepEqual(await alice.knock(inv, 'print', { doc: 'two' }), { printed: 'two' }, 'and a small write after it is kept');
+
+    // The number a deployment runs under, asked of the store itself: this is
+    // the platform's published ceiling and nothing this suite chose.
+    const store = new DurableStorage(state.storage, key, `c2:${Date.now()}:`);
+    const kept = { seed: new Uint8Array(32).fill(3), partition: {}, record: { pk: '', code: 'x', user: '' } };
+    await store.put('big', kept);
+    const over = { beings: { B: { fat: 'x'.repeat(ROW_CEILING) } }, bind: { B: {} } };
+    let refused = false;
+    try {
+      await store.save('big', over, ['B']);
+    } catch {
+      refused = true;
+    }
+    assert.equal(refused, true, 'a row past the platform s own ceiling is refused by the store');
+  });
+  const results: Result[] = [];
+  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 as Error)?.stack ?? e) });
+    }
+  }
+  return new Response(JSON.stringify({ results }), { headers: { 'content-type': 'application/json' } });
+}