@quo-systems/quo 0.1.0 → 0.2.0

package/dist/harbor/core.d.ts

@@ -0,0 +1,46 @@
+import type { WardPointers } from '../ward/ground.ts';
+import type { BeingClass, BeingLike } from '../being/types.ts';
+import { 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>;
+};
+export type Bound = {
+    reach: Reach;
+    held: boolean;
+};
+export type Loader = (record: WardRecord) => Promise<Record<string, BeingClass>>;
+export declare const DEFAULT_CODE = "classes/index.ts";
+export declare class Harbor {
+    #private;
+    readonly store: Store;
+    readonly loader: Loader;
+    readonly wards: Map<string, Hosted>;
+    readonly doors: Map<string, (bytes: Uint8Array) => Promise<{
+        bytes: Uint8Array;
+        heard: boolean;
+    }>>;
+    readonly reaches: Map<string, Bound>;
+    readonly down: Set<string>;
+    readonly refused: Map<string, number>;
+    readonly classes: Record<string, BeingClass>;
+    readonly fallbacks: Reach[];
+    constructor(store: Store, loader?: Loader);
+    boot(): Promise<void>;
+    carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | undefined>;
+    deliver(pk: string, bytes: Uint8Array): Promise<Uint8Array | undefined>;
+    hint(pk: string, url: string): void;
+    remember(pk: string, url: string): Promise<void>;
+    prove(pk: string, reach: Reach): Promise<boolean>;
+    bind(pks: string[], reach: Reach, held: boolean): Promise<void>;
+    unbind(reach: Reach): void;
+    create(name: string, user?: string, code?: string): Promise<Hosted>;
+    drop(name: string): Promise<Kept | undefined>;
+    adopt(name: string, kept: Kept): Promise<Hosted>;
+    host(name: string, kept: Kept): Promise<Hosted>;
+}

package/dist/harbor/core.js

@@ -0,0 +1,218 @@
+// 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 once the door behind the
+// dialer's claim has proved it holds the key, 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.js';
+import { request } from './reach.js';
+import { openReply, wardSignPk } from '../ward/seal.js';
+import { concat, sealingPair, KEY } from '../ward/arithmetic.js';
+import { within, LATE } from '../ward/allowance.js';
+export const DEFAULT_CODE = 'classes/index.ts';
+// How long a probe waits for the door behind a claim. A claim that answers
+// nothing in this time is not bound; the next announce is another chance.
+const PROBE = 10_000;
+export class Harbor {
+    store;
+    loader;
+    wards = new Map(); // name -> pointers
+    doors = new Map(); // ward pk -> door
+    reaches = new Map(); // the directory: foreign ward pk -> reach
+    down = new Set(); // pks this harbor will not reach right now: weather, for a test
+    refused = new Map(); // own ward pk -> arrivals its door would not admit. what a terrain does with it is its own
+    classes = {}; // 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.
+    fallbacks = [];
+    constructor(store, loader = async () => ({})) {
+        this.store = store;
+        this.loader = loader;
+    }
+    // Boot every ward the store keeps, and learn the hints.
+    async boot() {
+        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
+    // Bytes to one of this harbor's own doors, and the one bit the door says
+    // beside its reply, counted.
+    async #own(pk, door, bytes) {
+        const r = await door(bytes);
+        if (!r.heard)
+            this.refused.set(pk, (this.refused.get(pk) ?? 0) + 1);
+        return new Uint8Array(r.bytes);
+    }
+    async carry(pk, bytes) {
+        if (this.down.has(pk))
+            return undefined;
+        const door = this.doors.get(pk);
+        if (door)
+            return this.#own(pk, 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, bytes) {
+        if (this.down.has(pk))
+            return undefined;
+        const door = this.doors.get(pk);
+        if (door)
+            return this.#own(pk, door, bytes);
+        const bound = this.reaches.get(pk);
+        return bound?.held ? bound.reach.carry(pk, bytes) : undefined;
+    }
+    hint(pk, url) {
+        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, url) {
+        this.hint(pk, url);
+        await this.store.hint(pk, url);
+    }
+    // An announce is a claim, and a claim binds nothing until proven: anyone
+    // who can reach a listener could otherwise name a pk that is not theirs and
+    // take its reachability. The proof is the door itself, as it already is. A
+    // lid this harbor minted and noise after it is a box that does not open,
+    // and the door answers one such box with silence sealed to the lid and
+    // signed by the ward key. Only the holder of that ward's seed can write
+    // that reply, the lid is fresh so nothing replays, and a box that does not
+    // open writes nothing at the ward. This is the one box a harbor ever opens,
+    // the one it sealed itself, and it reads nothing from it but that the
+    // signature is the claimed key's.
+    async prove(pk, reach) {
+        if (!/^[0-9a-f]{128}$/.test(pk))
+            return false;
+        try {
+            const random = (n) => globalThis.crypto.getRandomValues(new Uint8Array(n));
+            const lid = await sealingPair(random(KEY));
+            const back = await within(PROBE, reach.carry(pk, concat([lid.pk, random(KEY)])));
+            if (back === LATE || back === undefined)
+                return false;
+            const reply = await openReply(back, lid.secret, wardSignPk(pk));
+            return reply !== null && 'silence' in reply;
+        }
+        catch {
+            return false;
+        }
+    }
+    // Bind what the far side claims, each pk proven at its door first. Both
+    // sides bind this way: the listener the dialer's claims, the dialer the
+    // listener's, since a claim is a claim whichever end made it.
+    async bind(pks, reach, held) {
+        // An announce is the whole of what that side holds now, so a pk this
+        // reach was bound for and no longer claims is unbound at once: a ward
+        // that left a dialer is not reachable through it, proof or no proof.
+        for (const [pk, b] of this.reaches)
+            if (b.reach === reach && !pks.includes(pk))
+                this.reaches.delete(pk);
+        await Promise.all(pks.map(async (pk) => {
+            if (this.doors.has(pk) || !(await this.prove(pk, reach)))
+                return;
+            this.reaches.set(pk, { reach, held });
+        }));
+    }
+    unbind(reach) {
+        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, user = '', code = DEFAULT_CODE) {
+        const 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) {
+        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, kept) {
+        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, kept) {
+        const { seed, partition: memory } = kept;
+        const classes = await this.loader(kept.record);
+        const objects = new Map(); // cells -> the object instantiate made. a side's hand, never the ward's
+        const 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 = (f) => async (...a) => {
+            try {
+                return await f(...a);
+            }
+            finally {
+                await save();
+            }
+        };
+        const door = after(w.door);
+        const ask = after(w.ask);
+        const bp = (await w.ask()); // learned by asking, as anyone learns anything
+        const beings = memory.beings;
+        const being = (key) => {
+            const cells = beings?.[key];
+            return cells ? objects.get(cells) : undefined;
+        };
+        const 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/dist/harbor/dial.d.ts

@@ -0,0 +1,8 @@
+import type { Harbor } from './core.ts';
+import { Socket } from './reach.ts';
+export type Dialer = {
+    url: string;
+    socket: Socket | null;
+    close(): void;
+};
+export declare function dial(harbor: Harbor, url: string): Dialer;

package/dist/harbor/dial.js

@@ -0,0 +1,45 @@
+import { REFUSED, Socket } from './reach.js';
+export function dial(harbor, url) {
+    const d = { url, socket: null, close: () => { } };
+    let stopped = false, wait = 1000, timer;
+    const connect = () => {
+        if (stopped)
+            return;
+        const line = new WebSocket(url.replace(/\/$/, '').replace(/^http/, 'ws'));
+        const s = 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;
+            void harbor.bind(far, s, false); // the listener's claims, each proven at its door: 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/dist/harbor/index.d.ts

@@ -0,0 +1,6 @@
+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/dist/harbor/index.js

@@ -0,0 +1,10 @@
+// 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 } from './memory.js';
+export { Harbor, DEFAULT_CODE } from './core.js';
+export { dial } from './dial.js';
+export { MemoryStore, values } from './store.js';
+export { request, Socket, SUITE, REFUSED } from './reach.js';

package/dist/harbor/memory.d.ts

@@ -0,0 +1,24 @@
+import type { BeingClass } from '../being/types.ts';
+import type { Ground, WardPointers } from '../ward/ground.ts';
+export type Booted = WardPointers & {
+    pk: string;
+};
+export type WardFactory = (ground: Ground) => Promise<WardPointers>;
+export declare class MemoryHarbor {
+    readonly doors: Map<string, (bytes: Uint8Array) => Promise<{
+        bytes: Uint8Array;
+        heard: boolean;
+    }>>;
+    readonly down: Set<string>;
+    readonly wire: string[];
+    readonly refused: Map<string, number>;
+    readonly peers: Set<MemoryHarbor>;
+    cut: boolean;
+    readonly partitions: Map<string, Record<string, unknown>>;
+    readonly wards: Map<string, Booted>;
+    readonly objects: Map<object, unknown>;
+    route(farPk: string, bytes: Uint8Array): Promise<Uint8Array | undefined>;
+    link(harbor: MemoryHarbor): void;
+    boot(seed: string, Ward: WardFactory, classes: Record<string, BeingClass>): Promise<Booted>;
+    reboot(seed: string, Ward: WardFactory, classes: Record<string, BeingClass>): Promise<Booted>;
+}

package/dist/harbor/memory.js

@@ -0,0 +1,68 @@
+import { hex } from '../ward/arithmetic.js';
+export class MemoryHarbor {
+    doors = new Map(); // ward pk -> door
+    down = new Set(); // ward pks this harbor cannot reach right now
+    wire = []; // every byte string that ever crossed, as hex. for inspection
+    refused = new Map(); // ward pk -> arrivals its door would not admit: strangers, counted
+    peers = new Set();
+    cut = false;
+    partitions = new Map(); // seed -> memory. the harbor keeps it and reads nothing
+    wards = new Map(); // seed -> pointers
+    objects = new Map(); // 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, bytes) {
+        if (this.down.has(farPk))
+            return undefined;
+        const door = this.doors.get(farPk);
+        if (door) {
+            const r = await door(bytes);
+            if (!r.heard)
+                this.refused.set(farPk, (this.refused.get(farPk) ?? 0) + 1);
+            return r.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) {
+        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, Ward, classes) {
+        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, Ward, classes) {
+        const memory = this.partitions.get(seed);
+        if (!memory)
+            throw new Error(`no partition for ${seed}`);
+        const ground = {
+            seed,
+            memory,
+            instantiate: (name, 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()); // the harbor learns its ward's pk the way anyone learns anything: by asking
+        const booted = { ...w, pk: bp.notes.pk };
+        this.doors.set(booted.pk, booted.door);
+        this.wards.set(seed, booted);
+        return booted;
+    }
+}

package/dist/harbor/reach.d.ts

@@ -0,0 +1,36 @@
+export type Carry = (pk: string, bytes: Uint8Array) => Promise<Uint8Array | undefined>;
+export type Reach = {
+    carry: Carry;
+    close(): void;
+};
+export declare function request(url: string): Reach;
+export declare const SUITE = 1;
+export declare const REFUSED = 4001;
+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;
+    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;
+export declare class Socket implements Reach {
+    #private;
+    readonly line: Line;
+    readonly pending: Map<number, (bytes: Uint8Array | undefined) => void>;
+    far: string[];
+    constructor(line: Line, deliver: Carry, onAnnounce: Announce, onClose: (why: {
+        code?: number;
+        reason?: string;
+    }) => void);
+    announce(pks: string[]): void;
+    carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | undefined>;
+    close(): void;
+}

package/dist/harbor/reach.js

@@ -0,0 +1,166 @@
+// 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.js';
+const never = () => new Promise(() => { }); // sent, and no word since: the ward's bound decides
+// A request reach to one listener.
+export function request(url) {
+    const base = url.replace(/\/$/, '');
+    return {
+        close: () => { },
+        carry: async (pk, bytes) => {
+            let res;
+            try {
+                res = await fetch(`${base}/${pk}`, { method: 'POST', headers: { 'content-type': 'application/octet-stream', 'quo-suite': String(SUITE) }, body: new Uint8Array(bytes) });
+            }
+            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
+// 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 {
+    line;
+    pending = new Map();
+    far = []; // the pks the far side announced
+    #id = 1;
+    #open;
+    constructor(line, deliver, onAnnounce, onClose) {
+        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);
+                    // 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) => 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) {
+        if (this.line.readyState === OPEN)
+            this.line.send(JSON.stringify({ announce: pks, suite: SUITE }));
+    }
+    async carry(pk, bytes) {
+        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() {
+        this.line.close();
+    }
+}
+function concat(a, b) {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}

package/dist/harbor/store.d.ts

@@ -0,0 +1,33 @@
+export type WardRecord = {
+    pk: string;
+    code: string;
+    user: string;
+};
+export type Kept = {
+    seed: Uint8Array;
+    partition: Record<string, unknown>;
+    record: WardRecord;
+};
+export type Store = {
+    list(): Promise<string[]>;
+    load(name: string): Promise<Kept | undefined>;
+    put(name: string, kept: Kept): Promise<void>;
+    save(name: string, partition: Record<string, unknown>): Promise<void>;
+    record(name: string, record: WardRecord): Promise<void>;
+    take(name: string): Promise<Kept | undefined>;
+    hints(): Promise<Record<string, string>>;
+    hint(pk: string, url: string): Promise<void>;
+};
+export declare const values: (p: Record<string, unknown>) => Record<string, unknown>;
+export declare class MemoryStore implements Store {
+    readonly rows: Map<string, Kept>;
+    readonly reach: Map<string, string>;
+    list(): Promise<string[]>;
+    load(name: string): Promise<Kept | undefined>;
+    put(name: string, kept: Kept): Promise<void>;
+    save(name: string, partition: Record<string, unknown>): Promise<void>;
+    record(name: string, record: WardRecord): Promise<void>;
+    take(name: string): Promise<Kept | undefined>;
+    hints(): Promise<Record<string, string>>;
+    hint(pk: string, url: string): Promise<void>;
+}