nervur 0.16.0 → 0.17.0

package/dist/harbor/core.js

@@ -0,0 +1,621 @@
+// 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 four 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; the
+// claims of a listener this harbor dialed, proved the same way and reached
+// through that line; and a hint, a pk at a URL, kept in the store. A hint
+// never displaces a reach proved at a door. 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 { maker, entropy as random, learnPk } from '../ward/ground.js';
+import { silence } from '../being/silence.js';
+import { request } from './reach.js';
+import { isWardPk, openReply, wardSignPk } from '../ward/seal.js';
+import { concat, sealingPair, KEY } from '../ward/arithmetic.js';
+import { within, LATE } from '../ward/allowance.js';
+import { restoreRow, rowsIn } from '../ward/partition.js';
+import { rowsOf } from './store.js';
+export const DEFAULT_CODE = 'classes/index.ts';
+// The device's entropy, spelled once. A harbor draws it for a ward's seed at
+// birth, for the lid of every probe it sends, and it hands the same function
+// to every ward it boots as the ground's `random`.
+// 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;
+// How many pks one announce may claim, and how many are proven at once.
+const ANNOUNCE = 64;
+const PROVING = 8;
+// How many times each reach has announced: a proof from an older announce
+// binds nothing when it lands.
+const announces = new WeakMap();
+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
+    faults = new Map(); // ward name -> saves the store refused. what a terrain does with it is its own
+    // Told every time a save is refused, with the ward's name and how many of
+    // its saves the store has now refused. The refusal is already the answer of
+    // the ask that caused it, so nobody is waiting on this; it is for the box's
+    // own record, a journal line or a counter, and a terrain that keeps none
+    // leaves it alone.
+    onFault = () => { };
+    unbooted = []; // the wards the store keeps that would not host this run, by name
+    classes = {}; // classes handed in-process, beside the loader's
+    #saving = new Map();
+    // 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 = [];
+    // How a dialer says what this harbor holds now. An announce is a claim and
+    // a claim is worth nothing until the door behind it answers a probe, so
+    // saying it again costs a proof and buys nothing to an impostor. What is
+    // not free is never saying it again: a ward booted, adopted or dropped
+    // after a line opened would be announced only by the next line, and a line
+    // that does not drop never opens again, so it would be unreachable through
+    // that listener for as long as the socket stayed healthy.
+    announcers = new Set();
+    #announce() {
+        for (const say of this.announcers)
+            say();
+    }
+    // What this device lends the beings of the wards it hosts, by name. One
+    // for the harbor, and `lendFor` says which ward may ask it: every ward,
+    // unless a terrain says a stranger's ward is lent nothing.
+    // Set at birth or once the harbor's own ward is standing, which is the
+    // usual order: a terrain puts that ward up first, then boots the rest on a
+    // ground that can reach it.
+    lend;
+    constructor(store, loader = async () => ({}), lend) {
+        this.store = store;
+        this.loader = loader;
+        this.lend = lend;
+    }
+    lendFor(_name, _record) {
+        return this.lend;
+    }
+    // Boot every ward the store keeps, and learn the hints. One ward that will
+    // not host, a partition this kit cannot read or a loader that throws, is
+    // named in `unbooted` and takes nobody else down with it.
+    async boot() {
+        for (const name of await this.store.list()) {
+            // A ward this harbor already hosts is not booted twice. A terrain that
+            // keeps a ward of its own puts it up before this runs, so that a being
+            // born in any other ward can lend from her first line.
+            if (this.wards.has(name))
+                continue;
+            try {
+                const kept = await this.store.load(name);
+                if (kept)
+                    await this.host(name, kept);
+            }
+            catch {
+                this.unbooted.push(name);
+            }
+        }
+        for (const [pk, url] of Object.entries(await this.store.hints()))
+            this.hint(pk, url);
+    }
+    // The object a ward writes into, by the name it is kept under: the
+    // partition the harbor was handed at boot and keeps so it can save it.
+    // Nothing in the harbor reads it, and it is not on `Hosted`, because a
+    // side that holds a ward would then hold every seed in it and reach any
+    // being past every door. It is here for one reader, the conformance
+    // suite, whose census is ward state read straight and whose forgeries are
+    // ward state written straight, the way `MemoryHarbor.partitions` is. A
+    // side asks the ward.
+    partitionOf(name) {
+        return this.#saving.get(name)?.memory;
+    }
+    // ---- saving
+    // The ward wrote one row. Its partition is saved once the line is free, and
+    // once for every burst of writes, with every row named in that burst.
+    #wrote(name, row) {
+        const s = this.#saving.get(name);
+        if (!s || s.gone)
+            return;
+        s.dirty.add(row);
+        if (s.timer === undefined)
+            s.timer = setTimeout(() => void this.#flush(name), 0);
+    }
+    // The rows a store refused, put back in the ward's memory to what the
+    // store holds for them. A being whose row was refused would otherwise go
+    // on answering out of a memory that runs ahead of the device: her next
+    // write is a row past the same ceiling, refused again, and everything she
+    // was told between now and the reload is gone with it. Standing her at
+    // what is kept costs her the writes that were never kept, which is what
+    // the asker was told, and leaves a small write after it one the store
+    // takes.
+    //
+    // The shape is read where the shape lives. The harbor hands each row and
+    // the copy it kept to the partition, which knows which part of itself a row
+    // is; nothing here reads a being, a bind table or a head. And nothing here
+    // asks the store: what it took is what this harbor handed it, which is
+    // `kept`, and a row nobody has handed it since this ward was hosted is a
+    // row the ward has not moved, so there is nothing to put back.
+    // Every row together, and never the refused ones alone. A relation's state
+    // is spread over rows, the head for the door's heirs and a being's own row
+    // for the keys she speaks under: put one back and the door stands ahead of
+    // the knocker and the relation never speaks again. So the ward is put back
+    // to the whole point, which is what the store held at the last save taken
+    // while no call was in flight. A row that point never knew is left where it
+    // is and stays named: no save has ever taken it, so there is nothing to put
+    // it back to. The rows that moved come back, so the store is put back with
+    // them and a reload finds no half-done row.
+    #standAtKept(s) {
+        if (s.gone)
+            return [];
+        const moved = [];
+        for (const row of s.kept.keys()) {
+            const was = s.kept.get(row);
+            const now = rowsOf(s.memory, [row])[0][1];
+            if (JSON.stringify(was) === JSON.stringify(now))
+                continue;
+            restoreRow(s.memory, row, was);
+            moved.push(row);
+        }
+        for (const row of moved)
+            s.dirty.delete(row);
+        return moved;
+    }
+    // The ward back to the point, and the store with it. The store is written
+    // because a reload reads it and not the memory: a refusal that put only the
+    // memory back would leave the rows the store did take standing ahead of the
+    // ward until the next restart, and one half of a relation ahead of the
+    // other. What goes out is what the store already took once, so it is a
+    // write the store has no reason to refuse; one that refuses it anyway is
+    // counted like any other, and there is nothing further to put back to.
+    async #putBack(name, s) {
+        // What the store took under the refused call is not a point to stand at.
+        // It is also what has to be written over: a row the ward never moved
+        // after that save comes back unchanged in memory and is still ahead of
+        // the point in the store, so the rows that go out are the ones the memory
+        // moved and the ones the store took under the call, together.
+        const under = [...s.under.keys()];
+        s.under.clear();
+        const moved = this.#standAtKept(s);
+        const rows = [...new Set([...moved, ...under])];
+        if (rows.length === 0 || s.gone)
+            return;
+        try {
+            await this.store.save(name, s.memory, rows);
+            for (const row of rows)
+                s.dirty.delete(row);
+        }
+        catch {
+            // A store that will not take back what it took once is a store this
+            // ward cannot be put back in. The count says so, the memory stands at
+            // the point all the same, and the rows stay named for the next save.
+            this.#fault(name);
+        }
+    }
+    // The call ended and the ward is whole, so the point catches up with it. A
+    // row the store took under the call and nobody has touched since is where
+    // the ward stands, so it joins the point as it is; a row that moved after
+    // that save is named for one more, and that save is quiet and moves the
+    // point itself. Nothing is written twice for a ward whose call left its
+    // rows where the store already has them.
+    #settle(name, s) {
+        for (const [row, value] of s.under) {
+            const now = rowsOf(s.memory, [row])[0][1];
+            if (JSON.stringify(value) === JSON.stringify(now))
+                s.kept.set(row, value);
+            else
+                s.dirty.add(row);
+        }
+        s.under.clear();
+        if (s.dirty.size > 0)
+            void this.#flush(name);
+    }
+    // One refusal, counted and told. What a terrain does with the count is its
+    // own; the arrival that caused it is told by the answer, not by this.
+    #fault(name) {
+        const faults = (this.faults.get(name) ?? 0) + 1;
+        this.faults.set(name, faults);
+        try {
+            this.onFault(name, faults);
+        }
+        catch {
+            /* a box that cannot write its own journal is not a ward's problem */
+        }
+    }
+    // Answers whether everything it wrote was kept. False is a store that
+    // refused, and it is the ward's answer to the arrival that caused it, not
+    // a number in a map nobody reads. A flush that had nothing to write kept
+    // everything it was given, which is true and is why a read is never
+    // refused.
+    async #flush(name) {
+        const s = this.#saving.get(name);
+        if (!s)
+            return true;
+        if (s.timer !== undefined) {
+            clearTimeout(s.timer);
+            s.timer = undefined;
+        }
+        // A flush already in flight is the one that will write these rows, and
+        // its verdict is theirs: two arrivals whose writes went out together are
+        // both refused when that write was refused, because neither of them is
+        // in the store.
+        if (s.running)
+            return s.running;
+        s.running = (async () => {
+            // A put back that was owed to a refusal under a call is done here, the
+            // first moment the ward is whole again. Nothing is written over it
+            // until it is done, because what is in memory is half of a call the
+            // store already said no to.
+            // The pen is held from the refusal to the put back that answers it.
+            // What a save would write between the two is about to be put back
+            // anyway, so writing it buys nothing and costs the one thing that
+            // matters: a store written there holds rows of two moments, one side of
+            // a call kept and the other about to be undone, and a box that goes
+            // down before the put back leaves it torn with nobody left to mend it.
+            if (s.back) {
+                if (s.calls > 0)
+                    return false; // the call that owed it is still in flight, and a put back inside one would roll back rows it is still writing
+                s.back = false;
+                await this.#putBack(name, s);
+                return false; // the verdict of the refusal that owed it, and nothing is written over a put back in the same save
+            }
+            while (s.dirty.size > 0 && !s.gone) {
+                // Taken before the write, so a row named while this one is in flight
+                // is written by the next turn of the loop and not lost with it.
+                const rows = [...s.dirty];
+                s.dirty.clear();
+                // The copy of what is about to be written, taken before the store is
+                // asked and kept only if the store takes it. It is the same values
+                // the store is about to write down, so it costs one copy of the rows
+                // of this save and nothing of the rows it does not name.
+                const writing = rowsOf(s.memory, rows);
+                try {
+                    const quiet = s.calls === 0; // read before the store is asked: the point is where the ward stood when this save was taken
+                    await this.store.save(name, s.memory, rows);
+                    // The store took it, and a restart finds it. Whether it is a point
+                    // a refused ward may be put back to is another question: a save
+                    // taken under a call holds half of a relation, so it is written and
+                    // is not somewhere to stand.
+                    for (const [row, value] of writing)
+                        (quiet ? s.kept : s.under).set(row, value);
+                }
+                catch {
+                    this.#fault(name);
+                    // A row the store would not take is a row that is not kept, so it
+                    // stays named and the verdict is no. The loop ends here rather than
+                    // trying again: what the next attempt writes is the same bytes to
+                    // the same store, and it is the next arrival that asks for one, not
+                    // this one in a circle. Whoever wrote it is told, which is the
+                    // whole point, and the row waits where a reader can still see it.
+                    for (const row of rows)
+                        s.dirty.add(row);
+                    // The refusal waits for an arrival to hear it: a save taken by a
+                    // timer answers nobody, and a ward whose row was refused between
+                    // two arrivals would otherwise have the refusal counted and the
+                    // next door go on saying yes. And the ward goes back to the point
+                    // now, unless a call is in flight, in which case the put back is
+                    // owed until that call ends.
+                    s.fault = true;
+                    if (s.calls > 0) {
+                        s.back = true;
+                        return false;
+                    }
+                    await this.#putBack(name, s);
+                    return false;
+                }
+            }
+            return true;
+        })();
+        try {
+            return await s.running;
+        }
+        finally {
+            s.running = null;
+        }
+    }
+    // ---- 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.has(pk))
+            return; // a reach proven at a door beats a hint, held or reached through a dialed line
+        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 it is
+    // the silence a door owes such a box, signed by the claimed key.
+    async prove(pk, reach) {
+        if (!isWardPk(pk))
+            return false;
+        try {
+            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. An announce
+    // names at most this many pks, and they are proven a few at a time: a
+    // side that announced a thousand would otherwise cost a thousand keys, a
+    // thousand frames and a thousand waits at once, on its word alone.
+    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 does not claim now is unbound at once: a ward
+        // that left a dialer is not reachable through it, proof or no proof.
+        // And it is the newest word: a proof still in flight from an earlier
+        // announce on this reach binds nothing when it lands, since the side
+        // has spoken again since.
+        const said = (announces.get(reach) ?? 0) + 1;
+        announces.set(reach, said);
+        for (const [pk, b] of this.reaches)
+            if (b.reach === reach && !pks.includes(pk))
+                this.reaches.delete(pk);
+        const claimed = [...new Set(pks)].slice(0, ANNOUNCE);
+        const prove = async (pk) => {
+            if (this.doors.has(pk))
+                return;
+            // A line already held for this pk is not displaced by another line that
+            // proves the same pk. A proof says only that the ward is reachable that
+            // way, and a relay that forwards to the real ward proves as well as the
+            // ward's own line does: taking the binding would add a hop the relay
+            // chooses, and can drop. The first held line keeps it until it closes,
+            // which unbind says.
+            const standing = this.reaches.get(pk);
+            if (standing?.held && standing.reach !== reach)
+                return;
+            if (!(await this.prove(pk, reach)))
+                return;
+            if (announces.get(reach) !== said)
+                return; // a newer announce has spoken since
+            if (this.reaches.get(pk)?.held && this.reaches.get(pk).reach !== reach)
+                return; // one took it while this was proving
+            this.reaches.set(pk, { reach, held });
+        };
+        for (let i = 0; i < claimed.length; i += PROVING)
+            await Promise.all(claimed.slice(i, i + PROVING).map(prove));
+    }
+    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: random(KEY), 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, and
+    // never again under this name: whoever still holds the old pointers holds
+    // a ward that saves nothing and answers its owner silence.
+    async drop(name) {
+        const h = this.wards.get(name);
+        if (h) {
+            await h.save();
+            // Gone for whoever still holds the old pointers, whose save closure has
+            // this row in hand, and out of the map, which now says what this harbor
+            // serves and nothing else.
+            const s = this.#saving.get(name);
+            if (s)
+                s.gone = true;
+            this.#saving.delete(name);
+            this.wards.delete(name);
+            this.doors.delete(h.pk);
+            this.#announce(); // this harbor no longer claims it: a listener unbinds a pk an announce stops naming
+        }
+        return this.store.take(name);
+    }
+    // Put what another harbor dropped, and boot it: same seed, same pk. A ward
+    // that will not boot is not adopted. This is the one path where a partition
+    // written somewhere else arrives, so it is the one place the ward's own
+    // shape check is met, and the name is refused for as long as it is kept:
+    // a partition put and left would hold the name against every later try,
+    // with a copy of it in a store that can never serve it. It goes back out,
+    // and the only copy is the one the caller is still holding.
+    async adopt(name, kept) {
+        await this.store.put(name, kept);
+        try {
+            return await this.host(name, kept);
+        }
+        catch (e) {
+            await this.store.take(name);
+            throw e;
+        }
+    }
+    // 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 WeakMap(); // cells -> the object instantiate made. a side's hand, never the ward's; it follows the cells out when she is unbooted
+        const ground = {
+            seed,
+            memory,
+            // This ward's own classes first, then the harbor's: a ward that names a
+            // class of its own is answered with hers.
+            instantiate: maker(objects, classes, this.classes),
+            carry: (pk, bytes) => this.carry(pk, new Uint8Array(bytes)),
+            random,
+            wrote: (row) => this.#wrote(name, row),
+            // What the ward wrote is in the store when this resolves, and it says
+            // whether the store took it. The ward calls it at the end of every
+            // arrival, before it seals, so a call through a pointer has already
+            // waited for the store when it comes back: a restart right after one
+            // finds everything, and a refusal is that arrival's own answer rather
+            // than a number counted behind it. A ward that wrote nothing has
+            // nothing to save, so asking it what it holds is free, which is what
+            // makes the ask pointer the way to find out rather than an expensive
+            // one.
+            //
+            // A ward on its way out keeps nothing and refuses nothing: an arrival
+            // racing an unhost is not a store saying no, and saying so would be a
+            // lie in the one direction that matters.
+            keep: async () => {
+                const s = this.#saving.get(name);
+                if (!s || s.gone)
+                    return true;
+                const ok = await this.#flush(name);
+                // A refusal is heard once, by the first arrival to ask after it: the
+                // save that met it may have been a timer's, which had nobody to tell.
+                // Under a call it is left standing, so the call that carried the
+                // refused write is refused too, and the outermost arrival hears it.
+                const no = !ok || s.fault;
+                s.fault = false; // heard. the next arrival is answered by the store and not by what happened before it
+                return !no;
+            },
+            // The ward says a call is in flight, and says when it ends. The harbor
+            // goes on writing under it; what it does not do is take a save made
+            // there as the point a refused ward is put back to, and a refusal that
+            // lands under a call waits here for the call to end before it puts the
+            // ward back. The ward is the one that knows, because a being reaching
+            // another being of her own ward goes to that ward's door directly and
+            // the harbor never sees that call at all.
+            calling: () => {
+                const s = this.#saving.get(name);
+                if (!s)
+                    return () => { };
+                s.calls += 1;
+                let lowered = false;
+                return () => {
+                    if (lowered)
+                        return;
+                    lowered = true;
+                    s.calls -= 1;
+                    if (s.calls > 0 || s.gone)
+                        return;
+                    // The moment the ward is whole again: the point catches up with the
+                    // call that just ended, or a put back that was owed is done now, so
+                    // a being stands at what is kept before her next word rather than
+                    // at the next save.
+                    if (s.back)
+                        void this.#flush(name);
+                    else
+                        this.#settle(name, s);
+                };
+            },
+        };
+        const lend = this.lendFor(name, kept.record);
+        if (lend)
+            ground.lend = lend;
+        // What the store holds for this ward at birth is what it was just handed
+        // or just read, row by row. It is copied once here so that a being whose
+        // very first write of this run is refused is put back too, rather than
+        // waiting for a save of hers to succeed before the harbor knows what she
+        // was. One copy of a partition per hosted ward, paid at boot and never
+        // again: after this, a row's copy is replaced by the save that kept it.
+        const saving = { memory, dirty: new Set(), kept: new Map(rowsOf(memory, rowsIn(memory))), running: null, timer: undefined, gone: false, calls: 0, fault: false, back: false, under: new Map() };
+        this.#saving.set(name, saving);
+        // A ward that will not be born leaves nothing behind: a partition of a
+        // shape this kit cannot read throws here, and a name the harbor does not
+        // serve must not have a saving row saying it does. Learning the pk is
+        // inside this, because a ward that will not say its pk is a ward this
+        // harbor cannot route to and is no more born than one that threw.
+        let w, pk;
+        try {
+            w = await Ward(ground);
+            pk = await learnPk(w);
+        }
+        catch (e) {
+            saving.gone = true;
+            this.#saving.delete(name);
+            throw e;
+        }
+        // The same keep, for a caller that holds the ward rather than asks it:
+        // a side that wrote through `being` and wants the store current says so
+        // here. It answers nothing, because a caller inside the process reads
+        // the fault off the harbor and an arrival is the only thing that needs a
+        // verdict of its own.
+        const save = async () => void (await ground.keep?.());
+        const door = (bytes) => w.door(bytes);
+        const ask = async (method, args) => {
+            if (saving.gone)
+                return silence;
+            return w.ask(method, args);
+        };
+        // The objects map is keyed by the cells the ward handed instantiate, so
+        // the way back to a being is her cells; the partition is read for that
+        // one lookup and for nothing else, and a key with no object is a being
+        // who is not here this run. `keys` is what the map holds, so a caller
+        // never needs the beings table to find out what to ask for.
+        const beings = memory.beings;
+        const being = (key) => {
+            const cells = beings && Object.hasOwn(beings, key) ? beings[key] : undefined;
+            return cells ? objects.get(cells) : undefined;
+        };
+        const keys = () => Object.keys(beings ?? {}).filter((k) => being(k) !== undefined);
+        const hosted = { door, ask, pk, name, record: { ...kept.record, pk }, being, keys, save };
+        this.wards.set(name, hosted);
+        this.doors.set(hosted.pk, door);
+        await save();
+        this.#announce(); // reachable through every line this harbor already holds, not only the next one
+        return hosted;
+    }
+}

package/dist/harbor/dial.d.ts

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