@nervur-org/dock 0.3.0

package/dist/beings/clock.js

@@ -0,0 +1,528 @@
+// SPDX-License-Identifier: Apache-2.0
+// The clock. A harbor is processes, storage, a network, entropy and a clock,
+// and of those only entropy crosses the edge into a being, as `random` in the
+// ground. The clock does not cross and must not: a being who could read one
+// would be a being who could not be moved, since the moment she read would be
+// her box's and no other. So a clock reaches a being the one way anything
+// reaches a being, as an ask.
+//
+// One class, two placements. On its own daemon she wakes beings of her own
+// harbor, on standings the root placed; on a service she wakes beings in other
+// estates, across a wire, on standings their roots placed. The woken being
+// cannot tell which one woke her, and should not: moving from one to the other
+// is a standing taken and a line moved, never a class rewritten.
+//
+// She reads no clock. `tick` takes the moment, and it comes from the one
+// timer on the device, the `timer` faculty in her dock: at her birth she asks
+// to be woken, and every tick arrives at her door as the occupant `timer`
+// with the moment in its args. So a tick can be replayed exactly, and the
+// suite needs no fake timers. `list` and `next` take the moment for the same
+// reason: what she says is next is computed from a moment she was handed.
+//
+// Nobody is woken without a schedule saying so. Every tick answers when she
+// is next due, the timer arms the box for the earliest such moment across
+// every Clock who lent her, and a schedule kept or dropped says the new
+// moment at her door at once. A box holding no schedule never ticks.
+//
+// One source, one list. `kept` is her own cell, and every schedule she holds
+// is in it: what the device always does, placed once by the root with `keep`,
+// and what an occupant registered on the service placement. Nothing is read
+// from a file and nothing is set on the class, so a schedule outlives the
+// process the way every cell does, and is gone when it is dropped.
+import { Being, isSilence, isWord, wordOf, OWNER } from '@nervur-org/nervur';
+import { TIMER, join } from '../dock/index.js';
+// The root and nobody else. `OWNER` is one of the ward's own words, refused at
+// every mint, so no occupant can ever wear it: an ask gated this way is the
+// device's own and cannot be reached through a door.
+const root = (_occ, asker) => asker.id === OWNER;
+// The box's timer and nobody else. The id is the one she minted when she
+// invited her back, so nobody else can wear it: one id names one record, and
+// a wake is the timer's to cause and comes through her own door.
+const WOKE = `${TIMER}:wake`;
+const timer = (_occ, asker) => asker.id === WOKE;
+// The root, or whoever the root invited. What she holds and when it goes next
+// is read through a door like anything else: the owner creates and places, and
+// the watching is done by somebody with a standing, through a gate. A
+// placement whose occupants must not see each other's schedules says so in its
+// own `asks`, since a subclass replaces the map rather than merging into it.
+const watching = (occ, asker) => occ !== undefined || asker.id === OWNER;
+// What one wake answered with. The three words as the door and the ward say
+// them, `error` for a being who answered an error object, and `unplaced` for a
+// schedule naming a standing the root never placed.
+const said = (out) => (isSilence(out) ? 'silence' : isWord(out) ? wordOf(out) : out !== null && typeof out === 'object' && !Array.isArray(out) && typeof out.error === 'string' ? 'error' : 'answered');
+const MINUTE = 60_000;
+const floor = (ms) => Math.floor(ms / MINUTE) * MINUTE;
+// ---- cron. Five fields, minute hour day-of-month month day-of-week, with
+// `*`, `a`, `a-b`, `*/n`, `a-b/n` and comma lists, and the three-letter names
+// for months and weekdays. Nothing else: no seconds, no `@daily`, no `L` or
+// `#`. A field that will not parse is a schedule that is refused where it was
+// written, never a schedule that quietly never fires.
+const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
+const WEEKDAYS = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+function field(spec, lo, hi, names = []) {
+    const out = new Set();
+    const one = (s) => {
+        const i = names.indexOf(s.toLowerCase());
+        const n = i >= 0 ? i + lo : Number(s);
+        if (!Number.isInteger(n) || n < lo || n > hi + (hi === 6 ? 1 : 0))
+            throw new Error(`${s} is not a value between ${lo} and ${hi}`);
+        return hi === 6 && n === 7 ? 0 : n; // seven is Sunday, as every crontab says
+    };
+    for (const part of spec.split(',')) {
+        const [range, step] = part.split('/');
+        if (range === undefined || range === '')
+            throw new Error(`${part} is not a field`);
+        const by = step === undefined ? 1 : Number(step);
+        if (!Number.isInteger(by) || by < 1)
+            throw new Error(`${part} does not step by a whole number`);
+        let from = lo, to = hi;
+        if (range !== '*') {
+            const ends = range.split('-');
+            if (ends.length > 2)
+                throw new Error(`${part} is not a range`);
+            from = one(ends[0]);
+            to = ends.length === 2 ? one(ends[1]) : from;
+            if (ends.length === 1 && step !== undefined)
+                to = hi; // `5/2` is `5-hi/2`, as every crontab says
+        }
+        if (to < from)
+            throw new Error(`${part} ends before it starts`);
+        for (let n = from; n <= to; n += by)
+            out.add(n);
+    }
+    return [...out].sort((a, b) => a - b);
+}
+export function parseCron(spec) {
+    const f = spec.trim().split(/\s+/);
+    if (f.length !== 5)
+        throw new Error('a cron is five fields: minute hour day-of-month month day-of-week');
+    return {
+        minutes: field(f[0], 0, 59),
+        hours: field(f[1], 0, 23),
+        days: field(f[2], 1, 31),
+        months: field(f[3], 1, 12, MONTHS),
+        weekdays: field(f[4], 0, 6, WEEKDAYS),
+        anyDay: f[2] === '*',
+        anyWeekday: f[4] === '*',
+    };
+}
+// The classic rule, and the one everybody trips on: two restricted day fields
+// are an or, not an and, so `0 3 1 * mon` is the first of the month and every
+// Monday, not the first of the month when it is a Monday.
+const dateMatches = (c, month, day, weekday) => {
+    if (!c.months.includes(month))
+        return false;
+    const d = c.days.includes(day), w = c.weekdays.includes(weekday);
+    return c.anyDay && c.anyWeekday ? true : c.anyDay ? w : c.anyWeekday ? d : d || w;
+};
+// ---- civil time. A zone is a calendar, not a clock: nothing here reads the
+// moment, it only says what a moment is called somewhere and what a name is a
+// moment of. The civil day in Bucharest is not the UTC day, which is the whole
+// reason a schedule carries a zone.
+const FORMATS = new Map();
+function format(tz) {
+    let f = FORMATS.get(tz);
+    if (!f)
+        FORMATS.set(tz, (f = new Intl.DateTimeFormat('en-US', { timeZone: tz, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit' })));
+    return f;
+}
+export function civil(ms, tz) {
+    const p = {};
+    for (const { type, value } of format(tz).formatToParts(ms))
+        p[type] = value;
+    return { year: Number(p.year), month: Number(p.month), day: Number(p.day), hour: Number(p.hour), minute: Number(p.minute) };
+}
+// What the zone is doing at that moment, in milliseconds, civil minus UTC.
+const offset = (ms, tz) => {
+    const c = civil(ms, tz);
+    return Date.UTC(c.year, c.month - 1, c.day, c.hour, c.minute) - ms;
+};
+// A civil name back to a moment. The guess is corrected once, which is enough
+// for every zone: an hour that daylight saving skipped lands on the hour that
+// replaced it, and an hour it repeated fires once, in the second of the two.
+export function fromCivil(tz, year, month, day, hour, minute) {
+    const guess = Date.UTC(year, month - 1, day, hour, minute);
+    const first = guess - offset(guess, tz);
+    const again = guess - offset(first, tz);
+    return again;
+}
+const nextDay = (c) => {
+    const d = new Date(Date.UTC(c.year, c.month - 1, c.day + 1));
+    return { year: d.getUTCFullYear(), month: d.getUTCMonth() + 1, day: d.getUTCDate() };
+};
+const weekdayOf = (year, month, day) => new Date(Date.UTC(year, month - 1, day)).getUTCDay();
+// The first minute strictly after `after` that this cron names in this zone,
+// or null when it names none inside four years and a bit. A schedule that
+// fires only on the twenty-ninth of February is inside that reach from
+// wherever it is asked; anything outside it was written wrong.
+export function nextFire(c, tz, after) {
+    const from = floor(after) + MINUTE;
+    let date = civil(from, tz);
+    for (let n = 0; n < 1500; n += 1) {
+        if (dateMatches(c, date.month, date.day, weekdayOf(date.year, date.month, date.day))) {
+            const hit = inDay(c, tz, date.year, date.month, date.day, from);
+            if (hit !== null)
+                return hit;
+        }
+        date = nextDay(date);
+    }
+    return null;
+}
+const HOUR = 3_600_000;
+const SPAN = 23 * HOUR + 59 * MINUTE;
+// The first moment this cron names inside one civil day, at or after `from`,
+// or null when it names none there. Two paths, because the day a zone moves is
+// a different problem from every other day.
+//
+// On an ordinary day the offset holds from midnight to midnight, so a civil
+// name and a moment differ by one constant. The fields are already ascending,
+// so the first name at or after `from` is the answer: two reads of the zone,
+// no allocation, and nothing built that is then thrown away. A cron naming
+// every minute of every hour costs the same as one naming a single morning.
+//
+// On the day a zone moves, ascending civil is not ascending UTC. An hour the
+// clocks skipped lands on the hour that replaced it, so a civil 03:30 that
+// never happened can come out later than the 04:00 after it. There every
+// moment is built and sorted, which is what that day costs, and it is the only
+// day that costs it.
+function inDay(c, tz, year, month, day, from) {
+    const midnight = fromCivil(tz, year, month, day, 0, 0);
+    if (fromCivil(tz, year, month, day, 23, 59) - midnight === SPAN) {
+        for (const h of c.hours)
+            for (const mi of c.minutes) {
+                const ms = midnight + h * HOUR + mi * MINUTE;
+                if (ms >= from)
+                    return ms;
+            }
+        return null;
+    }
+    const moments = [];
+    for (const h of c.hours)
+        for (const mi of c.minutes)
+            moments.push(fromCivil(tz, year, month, day, h, mi));
+    moments.sort((a, b) => a - b);
+    return moments.find((ms) => ms >= from) ?? null;
+}
+// ---- a schedule as it is written. One reader, so the root placing one on a
+// device and an occupant registering on the service are held to one shape
+// and one set of words for what is wrong with theirs.
+export function readSchedule(v) {
+    if (v === null || typeof v !== 'object' || Array.isArray(v))
+        return 'a schedule is an object';
+    const s = v;
+    if (typeof s.id !== 'string' || !/^[\w.:-]+$/.test(s.id))
+        return 'a schedule has an id, a word';
+    if (typeof s.ask !== 'string' || !/^[\w.:-]+\.[\w-]+$/.test(s.ask))
+        return `${s.id}: ask is <standing>.<name>`;
+    if ((s.cron === undefined) === (s.at === undefined))
+        return `${s.id}: a schedule is a cron or an at, and not both`;
+    const out = { id: s.id, ask: s.ask };
+    if (s.cron !== undefined) {
+        if (typeof s.cron !== 'string')
+            return `${s.id}: cron is five fields as a string`;
+        try {
+            parseCron(s.cron);
+        }
+        catch (e) {
+            return `${s.id}: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        out.cron = s.cron;
+    }
+    if (s.at !== undefined) {
+        if (typeof s.at !== 'string' || !Number.isFinite(Date.parse(s.at)))
+            return `${s.id}: at is a moment written out`;
+        out.at = s.at;
+    }
+    if (s.tz !== undefined) {
+        if (typeof s.tz !== 'string')
+            return `${s.id}: tz is a zone name`;
+        try {
+            format(s.tz);
+        }
+        catch {
+            return `${s.id}: ${s.tz} is not a zone this device knows`;
+        }
+        out.tz = s.tz;
+    }
+    if (s.args !== undefined) {
+        if (s.args === null || typeof s.args !== 'object' || Array.isArray(s.args))
+            return `${s.id}: args is an object`;
+        out.args = s.args;
+    }
+    if (s.note !== undefined)
+        out.note = s.note;
+    if (s.time !== undefined) {
+        if (typeof s.time !== 'number' || !Number.isFinite(s.time) || s.time <= 0)
+            return `${s.id}: time is how long the wake may spend`;
+        out.time = s.time;
+    }
+    if (s.catchUp !== undefined) {
+        if (typeof s.catchUp !== 'boolean')
+            return `${s.id}: catchUp is true or false`;
+        out.catchUp = s.catchUp;
+    }
+    return out;
+}
+// A schedule with no zone is UTC, said out loud rather than taken from the
+// device: the device's own zone is a thing that changes under a running
+// daemon, and a schedule that means a civil hour somewhere names the where.
+const zoneOf = (s) => s.tz ?? 'UTC';
+// She reads no clock, so every ask of hers that needs one takes it as an
+// argument. `format` says what that argument is, and a side that has a clock
+// of its own fills it rather than asking a human to type milliseconds: the
+// ask says what the argument is, and each side decides what to do with that.
+const NOW = { type: 'object', properties: { now: { type: 'number', format: 'moment', description: 'the moment, in milliseconds' } }, required: ['now'] };
+export class Clock extends Being {
+    static cells = { kept: {}, fires: {} };
+    // At her birth she lends the box's timer and invites her back, so from then
+    // on the moment arrives as an ask at her own door, under the id she minted
+    // and by nobody else. A box with no timer to lend leaves her holding
+    // nothing, and she waits for a tick a suite or an operator hands her.
+    //
+    // Again at every birth: a standing points at a being and not at a box, and
+    // a restart and a migration are one silent event she cannot tell apart.
+    // Birth is synchronous and taking a standing is not, so the promise is
+    // kept and whoever needs it waits on it.
+    joined;
+    constructor(stance) {
+        super(stance);
+        this.joined = join(this, TIMER, { method: 'tick' });
+    }
+    static asks = {
+        tick: { description: 'fire everything due at this moment, and answer the tally and when she is next due', input: NOW, for: timer },
+        list: { description: 'every schedule she holds, its last fire and when it is next', input: NOW, for: watching },
+        next: { description: 'the earliest schedule due after this moment', input: NOW, for: watching },
+        keep: {
+            description: 'add a schedule, or replace the one of that id, until it is dropped',
+            input: {
+                type: 'object',
+                properties: { id: { type: 'string' }, ask: { type: 'string', description: '<standing>.<name>, split at the last dot' }, args: { type: 'object' }, note: {}, cron: { type: 'string' }, at: { type: 'string' }, tz: { type: 'string' }, time: { type: 'number' }, catchUp: { type: 'boolean' } },
+                required: ['id', 'ask'],
+            },
+            for: root,
+        },
+        drop: { description: 'take one of her schedules out, with what it last fired', input: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] }, for: root },
+    };
+    #kept() {
+        return this.cells.kept;
+    }
+    // The root's own, and the root's alone. One way to declare a schedule: what
+    // the device always does, placed once when the root stands the estate up,
+    // and what something decided while it was running, a call back in three
+    // days, are the same ask and land in the same cell, and each stays until
+    // it is dropped. A second keep under an id replaces the first.
+    //
+    // On a service this ask is the occupants' door as well, and a root there
+    // places the device's own the same way. The asker is in the signature of
+    // both, unused here and used by a placement that opens the gate: an ask is
+    // `(args, asker)` everywhere, and a base that took one argument would be a
+    // base no subclass could widen.
+    async keep(args, _asker) {
+        const one = readSchedule(args);
+        if (typeof one === 'string')
+            return { error: one };
+        this.#kept()[one.id] = one;
+        await this.told();
+        return { kept: one.id };
+    }
+    async drop(args, _asker) {
+        if (typeof args.id !== 'string')
+            return { error: 'a drop names an id' };
+        if (!Object.hasOwn(this.#kept(), args.id))
+            return { error: 'no such schedule of hers' };
+        delete this.#kept()[args.id];
+        delete this.#fires()[args.id];
+        await this.told();
+        return { dropped: args.id };
+    }
+    // The box's timer holds one moment for the whole device, and a schedule
+    // kept or dropped moves when this Clock is next due. So she says the new
+    // moment at her timer's door rather than waiting for a round that may be a
+    // day away: a schedule kept at noon for one minute past noon fires at one
+    // minute past noon on a box that was asleep.
+    //
+    // She reads no clock to do it. The moment comes from the timer, who is the
+    // one being on the device that reads one, and `due` only ever brings the
+    // next round forward. A Clock lent no timer says nothing and waits for a
+    // moment somebody hands her.
+    //
+    // A placement whose occupants keep schedules of their own calls this where
+    // it keeps them, for the same reason the base does.
+    async told() {
+        if (!Object.hasOwn(this.cells.standings, TIMER))
+            return;
+        const timer = this.standings[TIMER];
+        const said = await timer?.ask('now', {});
+        const now = said !== null && typeof said === 'object' ? said.now : undefined;
+        if (typeof now !== 'number' || !Number.isFinite(now))
+            return;
+        // A schedule due at this very moment is a round now, not a round at the
+        // next moment after it: what she was handed is a minute already begun,
+        // and the schedule kept inside it names it.
+        const at = this.schedules().some((s) => this.#ready(s, now)) ? now : this.#soonest(floor(now));
+        if (at !== null)
+            await timer?.ask('due', { at });
+    }
+    // One list, her own cell and nothing else.
+    schedules() {
+        return Object.values(this.#kept());
+    }
+    #fires() {
+        return this.cells.fires;
+    }
+    // When this schedule goes next, after a moment. Null for a one-shot that has
+    // fired and for a cron that names nothing inside its reach.
+    #next(s, after) {
+        if (s.at !== undefined) {
+            const at = Date.parse(s.at);
+            return this.#fires()[s.id] ? null : at;
+        }
+        return nextFire(parseCron(s.cron), zoneOf(s), after);
+    }
+    // The earliest moment any schedule of hers is due after a minute. It is
+    // what she answers a tick with, and it is the whole of what the box's timer
+    // needs from her: a box whose Clocks all say null arms nothing and sleeps
+    // until somebody keeps something. A schedule whose wake was unreached is
+    // due again at the next minute, because nothing was delivered, and a
+    // schedule that will not parse is no moment at all.
+    #soonest(after) {
+        let soonest = null;
+        for (const s of this.schedules()) {
+            let at = null;
+            try {
+                at = this.#fires()[s.id]?.word === 'unreached' ? after + MINUTE : this.#next(s, after);
+            }
+            catch {
+                continue;
+            }
+            if (at !== null && (soonest === null || at < soonest))
+                soonest = at;
+        }
+        return soonest;
+    }
+    // Whether this schedule is due at this moment. A wake that was unreached is
+    // retried, because nothing was delivered; `late` is not, because the far
+    // door may have heard and be working still; and silence is never retried by
+    // anyone. Catch-up fires once for a gap, however long it was, never once per
+    // minute the box was down.
+    #due(s, now) {
+        const f = this.#fires()[s.id];
+        // Once a minute, whatever came back. The daemon ticks once a minute, so
+        // this only shows when a tick is replayed, and a tick replayed must fire
+        // nothing twice: that is what makes a moment handed in worth handing in.
+        if (f && f.at >= floor(now))
+            return false;
+        if (f?.word === 'unreached')
+            return true;
+        if (s.at !== undefined)
+            return !f && Date.parse(s.at) <= now;
+        const from = s.catchUp && f ? f.at : floor(now) - MINUTE;
+        const n = nextFire(parseCron(s.cron), zoneOf(s), from);
+        return n !== null && n <= now;
+    }
+    // The same question outside a tick, where a schedule that will not parse is
+    // no moment rather than an error: a tick says what is wrong with one, and
+    // nothing else of hers is allowed to fail on it.
+    #ready(s, now) {
+        try {
+            return this.#due(s, now);
+        }
+        catch {
+            return false;
+        }
+    }
+    // One wake: her standing, the ask on it, and what came back written down.
+    // Every send on one standing waits for the one before it, which is what a
+    // relation already is, so an estate with fifty schedules at one minute
+    // serializes on its own lane and delays nobody else.
+    async #wake(s, minute) {
+        const dot = s.ask.lastIndexOf('.');
+        const id = s.ask.slice(0, dot), name = s.ask.slice(dot + 1);
+        let word = 'unplaced';
+        if (Object.hasOwn(this.cells.standings, id)) {
+            const st = this.standings[id];
+            word = said(await st.ask(name, s.args ?? {}, s.time === undefined ? undefined : { time: s.time }));
+        }
+        const was = this.#fires()[s.id];
+        this.#fires()[s.id] = { at: minute, word, tries: word === 'unreached' ? (was?.word === 'unreached' ? was.tries : 0) + 1 : 1 };
+        return { id: s.id, ask: s.ask, word };
+    }
+    async tick(args) {
+        const now = args.now;
+        if (typeof now !== 'number' || !Number.isFinite(now))
+            return { error: 'a tick carries the moment: { now }' };
+        const minute = floor(now);
+        let due;
+        try {
+            due = this.schedules().filter((s) => this.#due(s, now));
+        }
+        catch (e) {
+            return { error: e instanceof Error ? e.message : String(e) };
+        }
+        const fired = await Promise.all(due.map((s) => this.#wake(s, minute)));
+        // What she is due next, after this tick and the fires it wrote down. The
+        // timer reads it off the answer and arms for the earliest across every
+        // Clock who lent her, so nobody is woken without a schedule saying so.
+        return { now: minute, fired, next: this.#soonest(minute) };
+    }
+    list(args) {
+        const now = args.now;
+        if (typeof now !== 'number' || !Number.isFinite(now))
+            return { error: 'a list is asked at a moment: { now }' };
+        const schedules = this.schedules().map((s) => {
+            const f = this.#fires()[s.id];
+            let next = null;
+            try {
+                next = this.#next(s, Math.max(now, f?.at ?? now));
+            }
+            catch {
+                next = null; // a schedule that will not parse says so where it was written
+            }
+            return Object.assign({}, s, { last: f?.at ?? null, word: f?.word ?? null, tries: f?.tries ?? 0, next });
+        });
+        return { now, schedules };
+    }
+    next(args) {
+        const now = args.now;
+        if (typeof now !== 'number' || !Number.isFinite(now))
+            return { error: 'a next is asked at a moment: { now }' };
+        let soonest = null;
+        for (const s of this.schedules()) {
+            let at = null;
+            try {
+                at = this.#next(s, now);
+            }
+            catch {
+                continue;
+            }
+            if (at !== null && (soonest === null || at < soonest.at))
+                soonest = { id: s.id, at };
+        }
+        return { next: soonest };
+    }
+}
+// Her id, and the key she is booted under. The daemon looks for exactly this
+// key in `main`, so a device with a clock has her here and nowhere else.
+export const CLOCK = 'clock';
+// The root's setup: the clock booted, and one standing at each being she is to
+// wake, under that being's own key. The same two asks a device's ground takes,
+// because it is the same act: the owner creates and places, and the work is
+// hers from then on.
+export async function setupClock(hosted, wakes = []) {
+    const out = (await hosted.ask('boot', { key: CLOCK, class: 'Clock' }));
+    if (out.error)
+        throw new Error(`clock: ${out.error}`);
+    for (const being of wakes)
+        await placeClock(hosted, being);
+}
+// One being the clock may wake: she invites the clock under `clock`, and the
+// clock takes the standing under the being's own key, which is what a
+// schedule's `ask` names.
+export async function placeClock(hosted, being) {
+    const inv = (await hosted.ask('invite', { being, id: CLOCK }));
+    if ('error' in inv)
+        throw new Error(`clock: ${inv.error}`);
+    const placed = (await hosted.ask('knock', { being: CLOCK, id: being, invitation: inv }));
+    if (placed.taken !== being)
+        throw new Error(`clock: ${placed.error ?? `she could not take ${being}`}`);
+}

package/dist/beings/courier.d.ts

@@ -0,0 +1,50 @@
+import { Being } from '@nervur-org/nervur';
+import type { Invitation, JsonObject, OccupantRecord } from '@nervur-org/nervur';
+export declare const MOVER = "mover";
+export type Moving = {
+    world: string;
+    at: string;
+    name: string;
+    seed: string;
+    partition: JsonObject;
+    record: JsonObject;
+};
+declare const invited: (occ: OccupantRecord | undefined) => occ is OccupantRecord;
+export declare function isMoving(v: unknown): v is Moving;
+export declare class Courier extends Being {
+    static asks: {
+        hand: {
+            description: string;
+            input: {
+                type: string;
+            };
+            for: typeof invited;
+        };
+        done: {
+            description: string;
+            input: {
+                type: string;
+            };
+            for: typeof invited;
+        };
+    };
+    giving: (() => Promise<Moving | {
+        error: string;
+    }>) | undefined;
+    gone: (() => Promise<{
+        deleted: string;
+    } | {
+        error: string;
+    }>) | undefined;
+    hand(): Promise<JsonObject>;
+    done(): Promise<JsonObject>;
+    fetch(invitation: Invitation): Promise<Moving | {
+        error: string;
+    }>;
+    landed(): Promise<{
+        deleted: string;
+    } | {
+        error: string;
+    }>;
+}
+export {};

package/dist/beings/courier.js

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: Apache-2.0
+// The courier: a ward moving from one device to another as an ask. A tab
+// holds a world in a local ward of its own, its seed and every standing it
+// won there, and a human who wants that world on their phone has no account
+// to log into and nothing to type: the ward itself moves, whole, and the far
+// world is never told, because the pk does not change and every standing
+// still points at her.
+//
+// Both ends are this class, in a ward of its own on each device, and the
+// device **giving** is the one that shows an invitation. That is not a
+// preference. A device is reachable only through a listener it dials, and a
+// phone that has joined no world dials nothing at all, so it cannot be
+// knocked; the device already in the world holds a socket to that world's
+// rendezvous and can be. So the invitation travels with the reach note of
+// that rendezvous, the receiving device dials it, and knocks.
+//
+// The move is two asks over one standing, because the answer to the first
+// may be lost. `hand` answers with the ward, and nothing is deleted; the
+// device that took it puts it on its own harbor, and only then asks `done`,
+// which is where the copy here goes. A move interrupted between them leaves
+// two copies of a ward that has not been touched since it was saved, and
+// the human tries again; a move that deleted first and lost the answer
+// would leave none.
+//
+// Nothing of the ward is kept here on either side. What is given comes from
+// the shell holding this device when it is asked for, and what arrives goes
+// back to the shell, since a partition written into another ward's cells is
+// a copy nobody asked for.
+import { Being, isSilence, isWord, wordOf } from '@nervur-org/nervur';
+// The id each end knows the other by for the length of one move.
+export const MOVER = 'mover';
+const HEX = /^(?:[0-9a-f]{2})+$/;
+const PK = /^[0-9a-f]{128}$/;
+const invited = (occ) => occ !== undefined;
+export function isMoving(v) {
+    if (v === null || typeof v !== 'object' || Array.isArray(v))
+        return false;
+    const m = v;
+    const object = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+    return typeof m.world === 'string' && PK.test(m.world) && typeof m.at === 'string' && typeof m.name === 'string' && typeof m.seed === 'string' && HEX.test(m.seed) && object(m.partition) && object(m.record);
+}
+const answered = (out) => {
+    if (isSilence(out))
+        return { error: 'silence' };
+    if (isWord(out))
+        return { error: wordOf(out) };
+    if (out === null || typeof out !== 'object' || Array.isArray(out))
+        return { error: 'the other device answered nothing' };
+    return out;
+};
+export class Courier extends Being {
+    static asks = {
+        hand: { description: 'the ward this device is giving away: its world, where that world lives, and the ward itself', input: { type: 'object' }, for: invited },
+        done: { description: 'the ward arrived on the other device: delete the copy here', input: { type: 'object' }, for: invited },
+    };
+    // The shell holding the device that gives: what to hand over, and what to
+    // do when the other end says it landed. Set while a move is offered and
+    // gone after, so a courier nobody is holding gives nothing.
+    giving;
+    gone;
+    // ---- what the device taking asks
+    async hand() {
+        if (!this.giving)
+            return { error: 'this device is giving nothing away' };
+        return await this.giving();
+    }
+    async done() {
+        if (!this.gone)
+            return { error: 'this device is giving nothing away' };
+        return await this.gone();
+    }
+    // ---- what the shell taking calls. Not asks: nobody reaches these through a door.
+    // Knock the far courier, take the ward she answers with, and hold her:
+    // the standing is what the second ask goes through, and a knock is spent
+    // the moment it is answered.
+    async fetch(invitation) {
+        const out = answered(await this.knock(invitation, 'hand', {}));
+        if ('error' in out && typeof out.error === 'string')
+            return { error: out.error };
+        if (!isMoving(out))
+            return { error: 'the other device answered with something that is not a ward' };
+        if ((await this.take(MOVER, invitation)) === null)
+            return { error: 'this device could not hold the other one' };
+        return out;
+    }
+    // It is here: the other device may delete its copy.
+    async landed() {
+        const standing = this.standings[MOVER];
+        if (!standing)
+            return { error: 'this device is not holding the other one' };
+        const out = answered(await standing.ask('done', {}));
+        if (typeof out.deleted === 'string')
+            return { deleted: out.deleted };
+        return { error: typeof out.error === 'string' ? out.error : 'the other device would not let go' };
+    }
+}