@quo-systems/quo 0.1.0

package/src/conformance/store.ts

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: Apache-2.0
+// The store conformance suite: what every store must show, written against
+// the interface alone. A store is handed in as a maker of fresh ones: an
+// empty folder, a database nobody opened, a view of storage under a prefix
+// nobody used. Nothing here knows how a store keeps anything; it asks for
+// what it put and expects it back, as the harbor will.
+import { assert } from './assert.ts';
+import type { Kept, Store } from '../harbor/store.ts';
+import type { Runner } from './index.ts';
+
+const seed = (b: number) => new Uint8Array(32).fill(b);
+const kept = (b: number, extra: Record<string, unknown> = {}): Kept => ({ seed: seed(b), partition: { beings: {}, ...extra }, record: { pk: '', code: 'classes/index.ts', user: 'me' } });
+
+export function conformStore(label: string, make: () => Promise<Store>, { test }: { test: Runner }) {
+  const t = (name: string, fn: () => Promise<void>) => test(`[${label}] ${name}`, {}, fn);
+
+  t('a fresh store keeps nothing', async () => {
+    const s = await make();
+    assert.deepEqual(await s.list(), []);
+    assert.equal(await s.load('main'), undefined);
+    assert.equal(await s.take('main'), undefined);
+    assert.deepEqual(await s.hints(), {});
+  });
+
+  t('put, then load: seed, partition and record come back as they went in', async () => {
+    const s = await make();
+    await s.put('main', kept(7, { n: 1, deep: { list: [1, 'two', null], flag: true } }));
+    assert.deepEqual(await s.list(), ['main']);
+    const back = await s.load('main');
+    assert.ok(back);
+    assert.deepEqual(back.seed, seed(7));
+    assert.deepEqual(back.partition, { beings: {}, n: 1, deep: { list: [1, 'two', null], flag: true } });
+    assert.deepEqual(back.record, { pk: '', code: 'classes/index.ts', user: 'me' });
+  });
+
+  t('a name already kept is refused, and what was kept stands', async () => {
+    const s = await make();
+    await s.put('main', kept(1));
+    let refused = false;
+    try {
+      await s.put('main', kept(2));
+    } catch {
+      refused = true;
+    }
+    assert.ok(refused, 'a second put under one name must throw');
+    assert.deepEqual((await s.load('main'))!.seed, seed(1));
+  });
+
+  t('save replaces the partition and touches nothing else', async () => {
+    const s = await make();
+    await s.put('main', kept(3));
+    await s.save('main', { beings: { a: { x: 1 } }, bind: {} });
+    const back = (await s.load('main'))!;
+    assert.deepEqual(back.partition, { beings: { a: { x: 1 } }, bind: {} });
+    assert.deepEqual(back.seed, seed(3));
+    assert.deepEqual(back.record, kept(3).record);
+  });
+
+  t('record replaces the record and touches nothing else', async () => {
+    const s = await make();
+    await s.put('main', kept(4, { n: 9 }));
+    await s.record('main', { pk: 'ab'.repeat(64), code: 'elsewhere.ts', user: 'her' });
+    const back = (await s.load('main'))!;
+    assert.deepEqual(back.record, { pk: 'ab'.repeat(64), code: 'elsewhere.ts', user: 'her' });
+    assert.deepEqual(back.partition, { beings: {}, n: 9 });
+  });
+
+  t('save and record on a name not kept are nothing', async () => {
+    const s = await make();
+    await s.save('ghost', { beings: {} });
+    await s.record('ghost', { pk: '', code: '', user: '' });
+    assert.deepEqual(await s.list(), []);
+  });
+
+  t('the partition handed back is values, not the object that was put', async () => {
+    const s = await make();
+    const k = kept(5, { n: 1 });
+    await s.put('main', k);
+    (k.partition as { n: number }).n = 2;
+    assert.deepEqual((await s.load('main'))!.partition, { beings: {}, n: 1 });
+    const a = (await s.load('main'))!;
+    (a.partition as { n: number }).n = 3;
+    assert.deepEqual((await s.load('main'))!.partition, { beings: {}, n: 1 });
+  });
+
+  t('take hands the ward out and forgets it; the name is free again', async () => {
+    const s = await make();
+    await s.put('main', kept(6, { n: 6 }));
+    await s.put('other', kept(8));
+    const out = await s.take('main');
+    assert.ok(out);
+    assert.deepEqual(out.seed, seed(6));
+    assert.deepEqual(out.partition, { beings: {}, n: 6 });
+    assert.equal(await s.load('main'), undefined);
+    assert.deepEqual(await s.list(), ['other']);
+    await s.put('main', kept(9));
+    assert.deepEqual((await s.load('main'))!.seed, seed(9));
+  });
+
+  t('hints are kept by pk and the last one wins', async () => {
+    const s = await make();
+    const pk = 'cd'.repeat(64);
+    await s.hint(pk, 'https://quo.acme.com/quo');
+    await s.hint('ef'.repeat(64), 'http://127.0.0.1:1/quo');
+    assert.deepEqual(await s.hints(), { [pk]: 'https://quo.acme.com/quo', ['ef'.repeat(64)]: 'http://127.0.0.1:1/quo' });
+    await s.hint(pk, 'https://quo.other.com/quo');
+    assert.equal((await s.hints())[pk], 'https://quo.other.com/quo');
+  });
+}

package/src/harbor/core.ts

@@ -0,0 +1,178 @@
+// SPDX-License-Identifier: Apache-2.0
+// The harbor core: what every harbor on a device is. It boots wards from a
+// store, keeps the map of ward pk to door for its own wards and pk to reach
+// for foreign ones, carries bytes to a pk, and hands bytes from the wire to
+// one door. It names no terrain: the store, the class loader and the lease
+// are the terrain's, handed in or laid over it. A disk harbor is this plus
+// files and a pid; a browser harbor is this plus IndexedDB and a lock; an
+// edge harbor is this over an object's storage. None of them is in this
+// tree, and every one of them passes the conformance suite untouched.
+//
+// The directory is filled three ways, in this order: the harbor's own
+// doors; a socket a dialer holds to it, bound at announce and unbound at
+// close; a hint from a link. And one fallback: a dialer with nothing in its
+// directory for a pk sends down the socket it holds, because the listener
+// it dialed is the rendezvous and may hold that pk on another socket. Bytes
+// that arrive from the wire go to an own door or a held socket and never
+// onward by request or by fallback; that one rule is the rendezvous.
+import { Ward } from '../ward/ward.ts';
+import type { Ground, WardPointers } from '../ward/ground.ts';
+import type { BeingClass, BeingLike } from '../being/types.ts';
+import { request, type Reach } from './reach.ts';
+import type { Kept, Store, WardRecord } from './store.ts';
+
+export type Hosted = WardPointers & { pk: string; name: string; record: WardRecord; partition: Record<string, unknown>; being(key: string): BeingLike | undefined; save(): Promise<void> };
+// A reach in the directory, and whether this harbor holds it as a socket a
+// dialer opened: only those, and its own doors, take bytes from the wire.
+export type Bound = { reach: Reach; held: boolean };
+// How the code half arrives: the classes a record's `code` names, loaded by
+// the terrain. The browser has a bundle and no files; a daemon has a folder.
+export type Loader = (record: WardRecord) => Promise<Record<string, BeingClass>>;
+
+export const DEFAULT_CODE = 'classes/index.ts';
+
+export class Harbor {
+  readonly store: Store;
+  readonly loader: Loader;
+  readonly wards = new Map<string, Hosted>(); // name -> pointers
+  readonly doors = new Map<string, WardPointers['door']>(); // ward pk -> door
+  readonly reaches = new Map<string, Bound>(); // the directory: foreign ward pk -> reach
+  readonly down = new Set<string>(); // pks this harbor will not reach right now: weather, for a test
+  readonly classes: Record<string, BeingClass> = {}; // classes handed in-process, beside the loader's
+  // The dialers' sockets, in the order they were dialed: where a pk nobody
+  // here knows is sent, because the listener a harbor dialed is a rendezvous
+  // and may hold that pk for someone else. It is a list because a harbor may
+  // dial more than one, and a rendezvous is a listener and nothing more, so
+  // there is never only one of them. A pk is tried down the list until one
+  // carries it: with a single slot, a harbor holding two lines answered
+  // unreached for a pk the other line could have reached.
+  readonly fallbacks: Reach[] = [];
+
+  constructor(store: Store, loader: Loader = async () => ({})) {
+    this.store = store;
+    this.loader = loader;
+  }
+
+  // Boot every ward the store keeps, and learn the hints.
+  async boot(): Promise<void> {
+    for (const name of await this.store.list()) {
+      const kept = await this.store.load(name);
+      if (kept) await this.host(name, kept);
+    }
+    for (const [pk, url] of Object.entries(await this.store.hints())) this.hint(pk, url);
+  }
+
+  // ---- the directory
+
+  async carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | undefined> {
+    if (this.down.has(pk)) return undefined;
+    const door = this.doors.get(pk);
+    if (door) return new Uint8Array(await door(bytes));
+    const bound = this.reaches.get(pk);
+    if (bound) return bound.reach.carry(pk, bytes);
+    for (const reach of this.fallbacks) {
+      const back = await reach.carry(pk, bytes);
+      if (back !== undefined) return back;
+    }
+    return undefined; // nobody here knows it, and no listener we dialed holds it
+  }
+
+  async deliver(pk: string, bytes: Uint8Array): Promise<Uint8Array | undefined> {
+    if (this.down.has(pk)) return undefined;
+    const door = this.doors.get(pk);
+    if (door) return new Uint8Array(await door(bytes));
+    const bound = this.reaches.get(pk);
+    return bound?.held ? bound.reach.carry(pk, bytes) : undefined;
+  }
+
+  hint(pk: string, url: string): void {
+    if (this.reaches.get(pk)?.held) return; // a socket in hand beats a hint
+    this.reaches.set(pk, { reach: request(url), held: false });
+  }
+
+  async remember(pk: string, url: string): Promise<void> {
+    this.hint(pk, url);
+    await this.store.hint(pk, url);
+  }
+
+  bind(pks: string[], reach: Reach, held: boolean): void {
+    for (const pk of pks) if (!this.doors.has(pk)) this.reaches.set(pk, { reach, held });
+  }
+  unbind(reach: Reach): void {
+    for (const [pk, b] of this.reaches) if (b.reach === reach) this.reaches.delete(pk);
+  }
+
+  // ---- wards
+
+  // Mint a seed and boot an empty ward under a name: a world born here.
+  async create(name: string, user = '', code = DEFAULT_CODE): Promise<Hosted> {
+    const kept: Kept = { seed: globalThis.crypto.getRandomValues(new Uint8Array(32)), partition: {}, record: { pk: '', code, user } };
+    await this.store.put(name, kept);
+    const hosted = await this.host(name, kept);
+    await this.store.record(name, hosted.record);
+    return hosted;
+  }
+
+  // Stop serving a ward and take it out of the store: what was kept comes
+  // back, for another harbor to put. The partition is written first, because
+  // a being driven in-process changes it without passing a door.
+  async drop(name: string): Promise<Kept | undefined> {
+    const h = this.wards.get(name);
+    if (h) {
+      await h.save();
+      this.wards.delete(name);
+      this.doors.delete(h.pk);
+    }
+    return this.store.take(name);
+  }
+
+  // Put what another harbor dropped, and boot it: same seed, same pk.
+  async adopt(name: string, kept: Kept): Promise<Hosted> {
+    await this.store.put(name, kept);
+    return this.host(name, kept);
+  }
+
+  // A ward from what the store keeps: the ground, once, and two pointers.
+  async host(name: string, kept: Kept): Promise<Hosted> {
+    const { seed, partition: memory } = kept;
+    const classes = await this.loader(kept.record);
+    const objects = new Map<object, BeingLike>(); // cells -> the object instantiate made. a side's hand, never the ward's
+    const ground: Ground = {
+      seed,
+      memory,
+      instantiate: (className, stance) => {
+        const C = classes[className] ?? this.classes[className];
+        if (!C) return null;
+        const obj = new C(stance);
+        objects.set(stance.cells, obj);
+        return obj;
+      },
+      carry: (pk, bytes) => this.carry(pk, new Uint8Array(bytes)),
+      random: (n) => globalThis.crypto.getRandomValues(new Uint8Array(n)),
+    };
+    const w = await Ward(ground);
+    const save = () => this.store.save(name, memory);
+    const after =
+      <A extends unknown[], R>(f: (...a: A) => Promise<R>) =>
+      async (...a: A): Promise<R> => {
+        try {
+          return await f(...a);
+        } finally {
+          await save();
+        }
+      };
+    const door = after(w.door);
+    const ask = after(w.ask);
+    const bp = (await w.ask()) as { notes: { pk: string } }; // learned by asking, as anyone learns anything
+    const beings = memory.beings as Record<string, object> | undefined;
+    const being = (key: string) => {
+      const cells = beings?.[key];
+      return cells ? objects.get(cells) : undefined;
+    };
+    const hosted: Hosted = { door, ask, pk: bp.notes.pk, name, record: { ...kept.record, pk: bp.notes.pk }, partition: memory, being, save };
+    this.wards.set(name, hosted);
+    this.doors.set(hosted.pk, door);
+    await save();
+    return hosted;
+  }
+}

package/src/harbor/dial.ts

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: Apache-2.0
+// A harbor as a dialer: one held socket to a listener's quo. route, its own
+// pks announced, the listener's bound, and a reconnect with backoff from a
+// second to thirty when the line drops. Seed, partition and keys are here;
+// only the reach comes and goes. While the socket is open it is also the
+// harbor's fallback: a pk nobody here knows is sent to the listener, which
+// is the rendezvous, and it is the fallback from the moment it is dialed,
+// because a ward asks the instant it boots and a socket's carry waits for
+// the handshake itself. Terrain-free: a daemon on a Mac and a tab dial alike,
+// on the WebSocket every terrain has.
+import type { Harbor } from './core.ts';
+import { REFUSED, Socket, type Line } from './reach.ts';
+
+export type Dialer = { url: string; socket: Socket | null; close(): void };
+
+export function dial(harbor: Harbor, url: string): Dialer {
+  const d: Dialer = { url, socket: null, close: () => {} };
+  let stopped = false,
+    wait = 1000,
+    timer: ReturnType<typeof setTimeout> | undefined;
+  const connect = () => {
+    if (stopped) return;
+    const line = new WebSocket(url.replace(/\/$/, '').replace(/^http/, 'ws')) as unknown as Line;
+    const s: Socket = new Socket(
+      line,
+      (pk, bytes) => harbor.deliver(pk, bytes),
+      (far) => {
+        // A line that opened is not a line that works. The wait goes back to
+        // a second here, where the far side has answered and been taken, and
+        // not at the handshake: a listener that opens and then refuses every
+        // time would otherwise be dialed at a fixed two seconds for good.
+        wait = 1000;
+        harbor.bind(far, s, false); // the listener's pks: reached through this socket, not held for others
+      },
+      (why) => {
+        harbor.unbind(s);
+        if (d.socket === s) d.socket = null;
+        const at = harbor.fallbacks.indexOf(s);
+        if (at !== -1) harbor.fallbacks.splice(at, 1); // this line only: another dialer's stays
+        // A suite this listener will not speak is not a line that dropped. It
+        // will not become speakable by asking again sooner, so the wait goes
+        // straight to the ceiling and stays there until it changes its mind.
+        if (why.code === REFUSED) wait = 30000;
+        if (!stopped) timer = setTimeout(connect, wait);
+        wait = Math.min(wait * 2, 30000);
+      },
+    );
+    harbor.fallbacks.push(s); // from the moment it is dialed: an ask made before the handshake waits on the socket, and is not unreached
+    line.addEventListener('open', () => {
+      d.socket = s;
+      s.announce([...harbor.doors.keys()]);
+    });
+  };
+  d.close = () => {
+    stopped = true;
+    clearTimeout(timer);
+    d.socket?.close();
+  };
+  connect();
+  return d;
+}

package/src/harbor/index.ts

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
+// @quo-systems/quo/harbor — the Ground contract and the harbors. The only
+// place in the package that may know a wire, and it knows one on the
+// standard surface alone: fetch and WebSocket. MemoryHarbor knows none: it
+// is one process talking to itself, where every ward assertion is made.
+export { MemoryHarbor, type Booted, type WardFactory } from './memory.ts';
+export { Harbor, DEFAULT_CODE, type Hosted, type Bound, type Loader } from './core.ts';
+export { dial, type Dialer } from './dial.ts';
+export { MemoryStore, values, type Store, type Kept, type WardRecord } from './store.ts';
+export { request, Socket, SUITE, REFUSED, type Reach, type Carry, type Line, type Announce } from './reach.ts';
+export type { Ground, WardPointers } from '../ward/ground.ts';

package/src/harbor/memory.ts

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: Apache-2.0
+// A memory harbor. One process, no wire. Owns what a device owns: the code
+// half, the memory half, the routing. Boots a ward by passing ONE object and
+// keeping TWO pointers. Routes one ward pk to one door. Knows no being,
+// reads no partition, opens no byte. Several memory harbors may be linked,
+// which stands in for a wire, and cut, which stands in for weather.
+import type { BeingClass, Stance } from '../being/types.ts';
+import type { Ground, WardPointers } from '../ward/ground.ts';
+import { hex } from '../ward/arithmetic.ts';
+
+export type Booted = WardPointers & { pk: string };
+export type WardFactory = (ground: Ground) => Promise<WardPointers>;
+
+export class MemoryHarbor {
+  readonly doors = new Map<string, WardPointers['door']>(); // ward pk -> door
+  readonly down = new Set<string>(); // ward pks this harbor cannot reach right now
+  readonly wire: string[] = []; // every byte string that ever crossed, as hex. for inspection
+  readonly peers = new Set<MemoryHarbor>();
+  cut = false;
+  readonly partitions = new Map<string, Record<string, unknown>>(); // seed -> memory. the harbor keeps it and reads nothing
+  readonly wards = new Map<string, Booted>(); // seed -> pointers
+  readonly objects = new Map<object, unknown>(); // cells -> being object. what instantiate constructed. a hand for tests, never the ward's
+
+  // the directory: its own doors, else a peer it is linked to. Quo says nothing about how.
+  async route(farPk: string, bytes: Uint8Array): Promise<Uint8Array | undefined> {
+    if (this.down.has(farPk)) return undefined;
+    const door = this.doors.get(farPk);
+    if (door) return door(bytes);
+    const peer = [...this.peers].find((h) => h.doors.has(farPk) && !h.down.has(farPk));
+    if (!peer || this.cut) return undefined; // nothing. the harbor has no word silence
+    return peer.route(farPk, bytes);
+  }
+
+  link(harbor: MemoryHarbor): void {
+    this.peers.add(harbor);
+    harbor.peers.add(this);
+  }
+
+  // boot by seed. the harbor gets a door and an ask, and learns the pk by asking.
+  async boot(seed: string, Ward: WardFactory, classes: Record<string, BeingClass>): Promise<Booted> {
+    this.partitions.set(seed, {});
+    return this.reboot(seed, Ward, classes);
+  }
+
+  // a restart: same seed, same partition, fresh ward. the ward's files are the harbor's to keep.
+  async reboot(seed: string, Ward: WardFactory, classes: Record<string, BeingClass>): Promise<Booted> {
+    const memory = this.partitions.get(seed);
+    if (!memory) throw new Error(`no partition for ${seed}`);
+    const ground: Ground = {
+      seed,
+      memory,
+      instantiate: (name: string, stance: Stance) => {
+        const C = classes[name];
+        if (!C) return null;
+        const obj = new C(stance);
+        this.objects.set(stance.cells, obj);
+        return obj;
+      },
+      // bytes cross, copied, never a reference. both ways.
+      carry: async (farPk, bytes) => {
+        this.wire.push(hex(bytes));
+        const back = await this.route(farPk, new Uint8Array(bytes));
+        return back === undefined ? undefined : new Uint8Array(back);
+      },
+      random: (n) => globalThis.crypto.getRandomValues(new Uint8Array(n)),
+    };
+    const w = await Ward(ground);
+    const bp = (await w.ask()) as { notes: { pk: string } }; // the harbor learns its ward's pk the way anyone learns anything: by asking
+    const booted: Booted = { ...w, pk: bp.notes.pk };
+    this.doors.set(booted.pk, booted.door);
+    this.wards.set(seed, booted);
+    return booted;
+  }
+}

package/src/harbor/reach.ts

@@ -0,0 +1,189 @@
+// SPDX-License-Identifier: Apache-2.0
+// Reach: carrying bytes to a pk off the device. One interface, two
+// implementations, as quo-harbor.md names them:
+//
+//   request   a URL, the quo. route of a world. POST the bytes to
+//             `<url>/<pk>`, get bytes back. Listener to listener.
+//   socket    a held WebSocket at `<url>`, opened by whichever side can
+//             dial, used in both directions with a frame id. Each side
+//             announces the ward pks it holds when the socket opens, and the
+//             other binds them.
+//
+// Both are written on what every terrain has: fetch, and the standard
+// WebSocket surface, which a browser, Node, an edge worker's pair and the
+// `ws` server all offer. The listener half of a socket is the terrain's
+// own and stays outside this tree; what is here is the framing, either end
+// of a line, and the request. Nothing here names a runtime, and
+// `src/conformance/reach.ts` is what every reach passes. A reach carries and returns; it reads
+// nothing. `undefined` is a promise that nothing was delivered: no such pk
+// at the far end, a connection that would not open, a socket that is gone.
+// A reach that sent the bytes and lost the line afterwards answers nothing
+// at all, and the ward's own bound ends the ask.
+import { hex, unhex } from '../ward/arithmetic.ts';
+
+export type Carry = (pk: string, bytes: Uint8Array) => Promise<Uint8Array | undefined>;
+export type Reach = { carry: Carry; close(): void };
+
+const never = () => new Promise<undefined>(() => {}); // sent, and no word since: the ward's bound decides
+
+// A request reach to one listener.
+export function request(url: string): Reach {
+  const base = url.replace(/\/$/, '');
+  return {
+    close: () => {},
+    carry: async (pk, bytes) => {
+      let res: Response;
+      try {
+        res = await fetch(`${base}/${pk}`, { method: 'POST', headers: { 'content-type': 'application/octet-stream', 'quo-suite': String(SUITE) }, body: new Uint8Array(bytes) as unknown as BodyInit });
+      } catch {
+        return undefined; // the connection never opened: nothing was delivered
+      }
+      if (res.status === 404) return undefined; // the listener holds no reach for that pk
+      if (!res.ok) return never();
+      return new Uint8Array(await res.arrayBuffer());
+    },
+  };
+}
+
+// The frames on a socket. Binary, one byte of kind first.
+//   ask    [0][id: 4 bytes][pk: 64 bytes][bytes]
+//   reply  [1][id: 4 bytes][bytes]
+//   none   [2][id: 4 bytes]                    nothing was delivered
+// And one text frame, JSON: { announce: [pk, ...], suite }, the ward pks this
+// side holds and the wire suite it speaks, sent when the socket opens and
+// whenever the pks change.
+const ASK = 0,
+  REPLY = 1,
+  NONE = 2;
+
+// The wire suite: which frames these are and which four algorithms seal what
+// they carry. One value, and it is not negotiated. It rides in the handshake
+// and never on an ask, so an ask stays bytes nobody can tell from noise, and
+// a line still learns before it carries anything whether the far side speaks
+// what this side speaks. A side meeting a suite it does not know carries
+// nothing for it and closes: the alternative is bytes that will never open,
+// answered by a silence that says nothing about why, forever. Nothing
+// changes this number before 1.0.0. After it, this is the one place a second
+// suite can be told from a first without guessing.
+export const SUITE = 1;
+
+// The close a side sends when it refuses a suite, in the range a protocol
+// may spend on itself. A line that just closes tells the far side nothing,
+// and a dialer that learns nothing dials again on its backoff for good: the
+// whole reason this number exists is that a kit which cannot be understood
+// should be told so instead of meeting a silence that names no reason. So
+// the refusal names itself on the way out, and the far side may read it.
+export const REFUSED = 4001;
+const OPEN = 1; // WebSocket.OPEN, on every terrain
+
+// The standard surface, and no more of it: what a browser WebSocket, Node's
+// WebSocket and a `ws` server socket all have.
+export type Line = {
+  readyState: number;
+  binaryType: string;
+  send(data: string | Uint8Array): void;
+  close(code?: number, reason?: string): void;
+  addEventListener(type: 'open' | 'error', fn: () => void): void;
+  // A close carries why, where the terrain gives it: the code and the reason
+  // the far side named. A line that just ends names neither.
+  addEventListener(type: 'close', fn: (e?: { code?: number; reason?: string }) => void): void;
+  addEventListener(type: 'message', fn: (e: { data: unknown }) => void): void;
+};
+
+export type Announce = (pks: string[]) => void;
+
+// One held socket, either side of it. `deliver` is what this side does with
+// an ask that arrives for a pk: its own door, or a socket it holds for that
+// pk, and nothing else. `onAnnounce` learns the far side's pks; `onClose`
+// forgets them.
+export class Socket implements Reach {
+  readonly line: Line;
+  readonly pending = new Map<number, (bytes: Uint8Array | undefined) => void>();
+  far: string[] = []; // the pks the far side announced
+  #id = 1;
+  #open: Promise<void>;
+
+  constructor(line: Line, deliver: Carry, onAnnounce: Announce, onClose: (why: { code?: number; reason?: string }) => void) {
+    this.line = line;
+    line.binaryType = 'arraybuffer';
+    this.#open = line.readyState === OPEN ? Promise.resolve() : new Promise((ok, no) => (line.addEventListener('open', ok), line.addEventListener('error', no)));
+    this.#open.catch(() => {}); // a handshake refused is a reach that failed, not a process that dies
+    line.addEventListener('message', (e) => {
+      if (typeof e.data === 'string') {
+        try {
+          const m = JSON.parse(e.data) as { announce?: unknown; suite?: unknown };
+          // Absent is this suite: a side that says nothing says one.
+          if (m.suite !== undefined && m.suite !== SUITE) {
+            this.far = [];
+            line.close(REFUSED, 'suite');
+            return;
+          }
+          if (Array.isArray(m.announce)) {
+            this.far = m.announce.filter((x): x is string => typeof x === 'string');
+            onAnnounce(this.far);
+          }
+        } catch {
+          /* not for us */
+        }
+        return;
+      }
+      const buf = e.data instanceof ArrayBuffer ? new Uint8Array(e.data) : ArrayBuffer.isView(e.data) ? new Uint8Array(e.data.buffer, e.data.byteOffset, e.data.byteLength) : undefined;
+      if (!buf || buf.length < 5) return;
+      const kind = buf[0],
+        id = new DataView(buf.buffer, buf.byteOffset, buf.byteLength).getUint32(1);
+      if (kind === ASK) {
+        const pk = hex(buf.subarray(5, 69));
+        void deliver(pk, new Uint8Array(buf.subarray(69))).then((back) => {
+          const head = new Uint8Array(5);
+          head[0] = back === undefined ? NONE : REPLY;
+          new DataView(head.buffer).setUint32(1, id);
+          if (line.readyState === OPEN) line.send(back === undefined ? head : concat(head, back));
+        });
+        return;
+      }
+      const waiting = this.pending.get(id);
+      if (!waiting) return;
+      this.pending.delete(id);
+      waiting(kind === REPLY ? new Uint8Array(buf.subarray(5)) : undefined);
+    });
+    line.addEventListener('error', () => {});
+    line.addEventListener('close', (e) => {
+      this.pending.clear(); // in flight and no word since: nothing is answered
+      onClose({ code: e?.code, reason: e?.reason });
+    });
+  }
+
+  // Say which ward pks this side holds.
+  announce(pks: string[]): void {
+    if (this.line.readyState === OPEN) this.line.send(JSON.stringify({ announce: pks, suite: SUITE }));
+  }
+
+  async carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | undefined> {
+    try {
+      await this.#open;
+    } catch {
+      return undefined;
+    }
+    if (this.line.readyState !== OPEN) return undefined;
+    const id = this.#id++;
+    const head = new Uint8Array(69);
+    head[0] = ASK;
+    new DataView(head.buffer).setUint32(1, id);
+    head.set(unhex(pk), 5);
+    return new Promise((ok) => {
+      this.pending.set(id, ok);
+      this.line.send(concat(head, bytes));
+    });
+  }
+
+  close(): void {
+    this.line.close();
+  }
+}
+
+function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}