@quo-systems/dock 0.1.0

package/harbor/edge/edge.ts

@@ -0,0 +1,147 @@
+// 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
+//   POST <route>/root          { init: { ward, user } } | { ward?, method?, args? }, under the root secret
+import type { BeingClass } from '@quo-systems/quo';
+import { isSilence } from '@quo-systems/quo';
+import { User, Desk, Avatar } from '../../beings/index.ts';
+import { setup } from '../../beings/setup.ts';
+import { Harbor, Socket as Held, SUITE, type Line } from '@quo-systems/quo/harbor';
+import { DurableStorage, sealKey } from './storage.ts';
+import type { State, Env } from './platform.d.ts';
+
+export const BUILT_IN: Record<string, BeingClass> = { User, Desk, Avatar };
+const json = (status: number, v: unknown, headers: Record<string, string> = {}) => 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 {
+  readonly sockets = new Set<Held>();
+  readonly root: string | undefined;
+  #booted: Promise<void> | undefined;
+
+  static async open(state: State, env: Env, classes: Record<string, BeingClass> = {}): Promise<EdgeHarbor> {
+    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: DurableStorage, root: string | undefined, classes: Record<string, BeingClass>) {
+    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(): Promise<void> {
+    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: Request, path: string): Promise<Response> {
+    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 as unknown as BodyInit, { 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(): Response {
+    const pair = new WebSocketPair();
+    const server = pair[1];
+    server.accept();
+    const s: Held = new Held(
+      server as unknown as Line,
+      (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 }; 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 });
+      }
+      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,187 @@
+// 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 type { World, Handle, Census } from '@quo-systems/quo/conformance';
+import { Printer, Shop, Customer, Echo, Member } from '@quo-systems/quo/conformance';
+import type { BeingClass, Cells, Invitation, JsonObject } from '@quo-systems/quo';
+import { EdgeHarbor } from './edge.ts';
+import { DurableStorage, sealKey } from './storage.ts';
+import type { Hosted } from '@quo-systems/quo/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 };
+const CLASSES: Record<string, BeingClass> = { Printer, Shop, Customer, Echo, Member };
+
+// 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, CLASSES));
+  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: w.partition 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, 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) 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 = (w.partition 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 = w.partition 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
+      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]!);
+  }
+  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, 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: 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' } });
+}

package/harbor/edge/platform.d.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: Apache-2.0
+// The edge platform, as much of it as the harbor touches and no more. The
+// vendor's own type package declares every global a worker has, and it
+// collides with the DOM library this tree compiles against; these few
+// lines are what the edge harbor and worker actually call.
+export type Storage = {
+  get<T = unknown>(key: string): Promise<T | undefined>;
+  get<T = unknown>(keys: string[]): Promise<Map<string, T>>;
+  put(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  list<T = unknown>(options?: { prefix?: string }): Promise<Map<string, T>>;
+};
+export type State = { id: { toString(): string; name?: string }; storage: Storage };
+export type Stub = { fetch(input: string | Request, init?: RequestInit): Promise<Response> };
+export type Namespace = { idFromName(name: string): unknown; get(id: unknown): Stub };
+export type Env = { HARBOR: Namespace; QUO_SEED_KEY?: string; QUO_ROOT?: string; QUO_EXERCISE?: string };
+// The server end of a WebSocketPair: the standard surface plus accept.
+export type ServerSocket = { accept(): void; readyState: number; binaryType: string; send(data: string | Uint8Array): void; close(): void; addEventListener(type: string, fn: (e: never) => void): void };
+declare global {
+  // eslint-disable-next-line no-var
+  var WebSocketPair: new () => { 0: ServerSocket; 1: ServerSocket };
+  interface ResponseInit {
+    webSocket?: unknown;
+  }
+  interface Response {
+    readonly webSocket?: unknown;
+  }
+}

package/harbor/edge/storage.ts

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: Apache-2.0
+// The store as Durable Object storage: one object per harbor, its storage
+// holding one row per ward under `ward:<name>`, seed, partition and record,
+// and one row per hint under `hint:<pk>`. The seed is kept 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, which is what the
+// harbor document's table says the edge does. Values cross as JSON, as
+// they do into a file, because the ward hands the partition out through a
+// guard that structured clone refuses.
+import { arithmetic } from '@quo-systems/quo/ward';
+import { values, type Kept, type Store, type WardRecord } from '@quo-systems/quo/harbor';
+import type { Storage } from './platform.d.ts';
+
+type Row = { seed: string; partition: Record<string, unknown>; record: WardRecord };
+// Bytes as the platform's crypto wants them: over a plain ArrayBuffer.
+const plain = (b: Uint8Array): Uint8Array<ArrayBuffer> => new Uint8Array(b);
+const { hex, unhex } = arithmetic;
+
+// The seal on a seed: AES-GCM under the platform key, a fresh nonce each
+// time, nonce and ciphertext together as hex.
+export async function sealKey(secret: string): Promise<CryptoKey> {
+  if (!/^[0-9a-f]{64}$/.test(secret)) throw new Error('QUO_SEED_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, seed: Uint8Array): Promise<string> {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const ct = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, plain(seed)));
+  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)));
+}
+
+// `prefix` keeps more than one harbor apart in one object's storage: the
+// exercise does that, a deployment never does.
+export class DurableStorage implements Store {
+  readonly storage: Storage;
+  readonly key: CryptoKey;
+  readonly prefix: string;
+  constructor(storage: Storage, key: CryptoKey, prefix = '') {
+    this.storage = storage;
+    this.key = key;
+    this.prefix = prefix;
+  }
+  #k(kind: 'ward' | 'hint', name: string) {
+    return `${this.prefix}${kind}:${name}`;
+  }
+
+  async list(): Promise<string[]> {
+    const head = this.#k('ward', '');
+    return [...(await this.storage.list({ prefix: head })).keys()].map((k) => k.slice(head.length));
+  }
+  async load(name: string): Promise<Kept | undefined> {
+    const row = await this.storage.get<Row>(this.#k('ward', name));
+    return row && { seed: await open(this.key, row.seed), partition: values(row.partition), record: row.record };
+  }
+  async put(name: string, kept: Kept): Promise<void> {
+    if ((await this.storage.get(this.#k('ward', name))) !== undefined) throw new Error(`ward ${name} already exists here`);
+    await this.storage.put(this.#k('ward', name), { seed: await seal(this.key, kept.seed), partition: values(kept.partition), record: kept.record } satisfies Row);
+  }
+  async save(name: string, partition: Record<string, unknown>): Promise<void> {
+    const row = await this.storage.get<Row>(this.#k('ward', name));
+    if (row) await this.storage.put(this.#k('ward', name), { ...row, partition: values(partition) } satisfies Row);
+  }
+  async record(name: string, record: WardRecord): Promise<void> {
+    const row = await this.storage.get<Row>(this.#k('ward', name));
+    if (row) await this.storage.put(this.#k('ward', name), { ...row, record } satisfies Row);
+  }
+  async take(name: string): Promise<Kept | undefined> {
+    const kept = await this.load(name);
+    if (kept) await this.storage.delete(this.#k('ward', name));
+    return kept;
+  }
+  async hints(): Promise<Record<string, string>> {
+    const head = this.#k('hint', '');
+    return Object.fromEntries([...(await this.storage.list<string>({ prefix: head }))].map(([k, v]) => [k.slice(head.length), v]));
+  }
+  async hint(pk: string, url: string): Promise<void> {
+    await this.storage.put(this.#k('hint', pk), url);
+  }
+}

package/harbor/edge/worker.ts

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: Apache-2.0
+// The worker: the edge harbor deployed. One Durable Object class, `Quo`,
+// one instance per harbor name, and the worker routes by the first path
+// segment: `/h/<name>/...` goes to that harbor. A world's quo. route on the
+// edge is `<origin>/h/<name>/quo`, and its health `<origin>/h/<name>/health`.
+// `wrangler.toml` beside this file names the class and the secrets.
+//
+// One thing lives here for the terrain test alone: with `QUO_EXERCISE` set,
+// which no deployment sets, `/exercise` runs the library's conformance
+// suite inside the platform against two harbors in this one object, over
+// two prefixed views of its storage, reaching each other by request
+// through the worker under `/x/<sub>/quo`. One object cannot touch
+// another's storage, the platform says so, and so the two harbors share an
+// object the way two tabs share a page.
+import { EdgeHarbor } from './edge.ts';
+import { exercise } from './exercise.ts';
+import type { State, Env } from './platform.d.ts';
+
+export class Quo {
+  readonly state: State;
+  readonly env: Env;
+  #harbor: Promise<EdgeHarbor> | undefined;
+  constructor(state: State, env: Env) {
+    this.state = state;
+    this.env = env;
+  }
+  harbor(): Promise<EdgeHarbor> {
+    return (this.#harbor ??= EdgeHarbor.open(this.state, this.env));
+  }
+  async fetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    const m = /^\/h\/([\w.-]+)(\/.*)?$/.exec(url.pathname);
+    if (!m) return new Response(JSON.stringify({ error: 'no such route' }), { status: 404, headers: { 'content-type': 'application/json' } });
+    const path = m[2] ?? '/';
+    if (this.env.QUO_EXERCISE && (path === '/exercise' || path.startsWith('/x/'))) return exercise(request, `${url.origin}/h/${m[1]!}`, path, this.state, this.env);
+    return (await this.harbor()).fetch(request, path);
+  }
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    const m = /^\/h\/([\w.-]+)(\/.*)?$/.exec(url.pathname);
+    if (!m) return new Response(JSON.stringify({ error: 'a harbor is /h/<name>/...' }), { status: 404, headers: { 'content-type': 'application/json' } });
+    return env.HARBOR.get(env.HARBOR.idFromName(m[1]!)).fetch(request);
+  },
+};

package/harbor/edge/wrangler.toml

@@ -0,0 +1,21 @@
+# The edge harbor as a worker. Deploy from `dock/` with
+#   npx wrangler deploy --config harbor/edge/wrangler.toml
+# and set the two secrets once, never in this file:
+#   npx wrangler secret put QUO_SEED_KEY --config harbor/edge/wrangler.toml   32 bytes as hex
+#   npx wrangler secret put QUO_ROOT     --config harbor/edge/wrangler.toml   the root's bearer
+name = "quo-edge"
+main = "worker.ts"
+compatibility_date = "2026-09-01"
+# The lab's edge answers on the account's workers.dev subdomain; a custom
+# domain under lab.quo.systems wants a token with the zone's Workers Routes
+# permission, which the lab's token does not hold. A world's quo. route on
+# it is <origin>/h/main/quo.
+workers_dev = true
+
+[[durable_objects.bindings]]
+name = "HARBOR"
+class_name = "Quo"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["Quo"]

package/harbor/files.ts

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: Apache-2.0
+// The store as a folder on disk, one folder per ward:
+//
+//   <dir>/wards/<name>/seed             32 bytes, hex, mode 0600
+//   <dir>/wards/<name>/partition.json
+//   <dir>/wards/<name>/ward.json        the ward record
+//   <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.
+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';
+
+const { hex, unhex } = arithmetic;
+
+export class Files implements Store {
+  readonly dir: string;
+  readonly #queues = new Map<string, Promise<void>>();
+  constructor(dir: string) {
+    this.dir = dir;
+  }
+  #ward(name: string) {
+    return join(this.dir, 'wards', name);
+  }
+
+  async list(): Promise<string[]> {
+    const wards = join(this.dir, 'wards');
+    return existsSync(wards) ? (await readdir(wards)).filter((n) => existsSync(join(wards, n, 'seed'))) : [];
+  }
+
+  async load(name: string): Promise<Kept | undefined> {
+    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>,
+      record: JSON.parse(await readFile(join(wd, 'ward.json'), 'utf8')) as WardRecord,
+    };
+  }
+
+  async put(name: string, kept: Kept): Promise<void> {
+    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 });
+    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 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 });
+  }
+
+  async take(name: string): Promise<Kept | undefined> {
+    const kept = await this.load(name);
+    if (!kept) return undefined;
+    await this.#queues.get(name);
+    await rm(this.#ward(name), { recursive: true, force: true });
+    return kept;
+  }
+
+  async hints(): Promise<Record<string, string>> {
+    const p = join(this.dir, 'reach.json');
+    return existsSync(p) ? (JSON.parse(await readFile(p, 'utf8')) as Record<string, string>) : {};
+  }
+
+  async hint(pk: string, url: string): Promise<void> {
+    const all = await this.hints();
+    all[pk] = url;
+    await writeFile(join(this.dir, 'reach.json'), JSON.stringify(all, null, 2) + '\n', { mode: 0o600 });
+  }
+}