@net-mesh/browser 0.42.0 → 0.44.0

package/dist/netcode/paths.js

@@ -0,0 +1,261 @@
+/**
+ * NPCs driven by paths in the store (sharded-match plan, slice N2): an NPC
+ * on a known route is published once as a path record, instead of in every
+ * snapshot, and every client evaluates the path itself.
+ *
+ * Two sources, then, for one NPC: snapshots (live, lossy, every tick while
+ * live) and the store's path record (reliable, written on a switch). They
+ * can arrive in either order, so each carries a **mode version** `mv` that
+ * the owner bumps on every switch between `'path'` and `'live'`:
+ *
+ * - the client draws from **whichever source shows the highest `mv`**;
+ * - if that says `'path'` and the record has not arrived yet, the last live
+ *   motion is carried forward for at most `carryMs` (500), then held;
+ * - a switch of source blends over `smoothingMs` (100), so it never jumps;
+ * - an NPC whose highest `mv` says `'live'` but that no snapshot shows any
+ *   more (dead, or out of interest) is held for `carryMs`, then no longer
+ *   drawn — which is how a retired path record (`'live'`, no points)
+ *   clears it.
+ *
+ * ```ts
+ * const modes = npcModes<Npc>();
+ * renderLoop(() => draw(modes.resolve(match.view(), lobbyReplica.getState().paths, id => match.hostNow(ownerOf(id)))));
+ * ```
+ *
+ * An NPC whose position is secret (fog) never uses a path: a record goes to
+ * every reader of the store. The shard host recipe refuses to put such an
+ * NPC on a path.
+ */
+/** Waypoints one record may carry. */
+export const MAX_PATH_POINTS = 64;
+/** Where a path puts its NPC at owner host time `t`: interpolated, held before the first point and after the last. */
+export function pathAt(points, t) {
+    if (points.length === 0)
+        return null;
+    if (t <= points[0].t)
+        return { x: points[0].x, z: points[0].z };
+    const last = points.at(-1);
+    if (t >= last.t)
+        return { x: last.x, z: last.z };
+    let i = 1;
+    while (points[i].t < t)
+        i += 1;
+    const a = points[i - 1];
+    const b = points[i];
+    const alpha = b.t === a.t ? 1 : (t - a.t) / (b.t - a.t);
+    return { x: a.x + (b.x - a.x) * alpha, z: a.z + (b.z - a.z) * alpha };
+}
+/** What is wrong with a path record; empty when it is valid. */
+export function pathProblems(path) {
+    const problems = [];
+    if (!Number.isSafeInteger(path.mv) || path.mv < 0)
+        problems.push('mv is not a non-negative integer');
+    if (path.mode !== 'path' && path.mode !== 'live')
+        problems.push('mode is neither path nor live');
+    if (path.key !== null && typeof path.key !== 'string')
+        problems.push('key is neither a string nor null');
+    if (!Array.isArray(path.points) || path.points.length > MAX_PATH_POINTS)
+        problems.push(`more than ${MAX_PATH_POINTS} points`);
+    else {
+        if (path.mode === 'path' && path.points.length === 0)
+            problems.push('a path with no points');
+        for (let i = 0; i < path.points.length; i += 1) {
+            const p = path.points[i];
+            if (![p.t, p.x, p.z].every(Number.isFinite))
+                problems.push(`point ${i} is not finite`);
+            if (i > 0 && p.t < path.points[i - 1].t)
+                problems.push(`point ${i} goes back in time`);
+        }
+    }
+    return problems;
+}
+/**
+ * The lobby store's `setPath` action (D8): record `path` for `npc`. Refused
+ * (the action rejects, the state is unchanged) unless the caller hosts the
+ * shard that owns `npc` in the installed assignment, the record is valid,
+ * and its `mv` is above the one held.
+ */
+export function pathAction(options) {
+    const field = options.field ?? 'paths';
+    return (input, context) => {
+        const state = context.getState();
+        if (typeof input?.npc !== 'string')
+            throw new Error('npc is not a string');
+        const assignment = options.assignment(state);
+        // An array check, not just `includes`: on a string, `includes` would be
+        // a substring match.
+        const owner = Object.values(assignment?.shards ?? {}).find(shard => Array.isArray(shard.npcs) && shard.npcs.includes(input.npc));
+        if (owner === undefined || owner.host !== context.peer)
+            throw new Error(`only the host that owns ${input.npc} writes its path`);
+        const problems = pathProblems(input.path);
+        if (problems.length > 0)
+            throw new Error(`invalid path: ${problems.join('; ')}`);
+        const records = (state[field] ?? {});
+        const held = Object.hasOwn(records, input.npc) ? records[input.npc] : undefined;
+        if (held !== undefined && input.path.mv <= held.mv)
+            throw new Error(`mv ${input.path.mv} is not above ${held.mv}`);
+        context.setState({ [field]: { ...records, [input.npc]: input.path } });
+        return { mv: input.path.mv };
+    };
+}
+/** Resolve NPCs between their snapshot entries and their path records. */
+export function npcModes(options = {}) {
+    const now = options.now ?? (() => globalThis.performance?.now() ?? Date.now());
+    const smoothing = Math.max(0, options.smoothingMs ?? 100);
+    const carryMs = Math.max(0, options.carryMs ?? 500);
+    const delay = options.interpolationDelayMs ?? 100;
+    const tracks = new Map();
+    let carried = 0;
+    let switches = 0;
+    const place = (base, at, mv, mode) => ({ ...base, x: at.x, z: at.z, mv, mode });
+    return {
+        resolve(view, records, ownerNow) {
+            const out = { ...view };
+            const at = now();
+            const ids = new Set();
+            for (const [id, entity] of Object.entries(view))
+                if (entity.mv !== undefined)
+                    ids.add(id);
+            for (const id of Object.keys(records ?? {}))
+                ids.add(id);
+            for (const id of ids) {
+                let track = tracks.get(id);
+                if (track === undefined) {
+                    track = {
+                        live: null,
+                        previousLive: null,
+                        drawn: null,
+                        source: null,
+                        blend: null,
+                        carriedSince: null,
+                        seen: null,
+                        last: null,
+                        missingSince: null,
+                        seenAt: at,
+                    };
+                    tracks.set(id, track);
+                }
+                track.seenAt = at;
+                const entry = Object.hasOwn(view, id) ? view[id] : undefined;
+                const record = records !== null && records !== undefined && Object.hasOwn(records, id) ? records[id] : undefined;
+                if (entry !== undefined)
+                    track.last = entry;
+                if (entry !== undefined && entry.mode !== 'path' && (track.live === null || track.live.state !== entry)) {
+                    track.previousLive = track.live;
+                    track.live = { state: entry, at };
+                }
+                if (entry?.mv !== undefined && (track.seen === null || entry.mv >= track.seen.mv)) {
+                    track.seen = { mv: entry.mv, mode: entry.mode ?? 'live' };
+                }
+                const entryMv = track.seen?.mv ?? -1;
+                const recordMv = record?.mv ?? -1;
+                // The highest mode version decides — whichever source carried it.
+                const mode = entryMv >= recordMv ? track.seen?.mode ?? 'live' : record.mode;
+                const mv = Math.max(entryMv, recordMv);
+                let target = null;
+                let source = null;
+                if (mode !== 'live')
+                    track.missingSince = null;
+                if (mode === 'live') {
+                    if (entry !== undefined && entry.mode !== 'path') {
+                        track.missingSince = null;
+                        target = entry;
+                    }
+                    else {
+                        // Live, but no snapshot shows it: held for carryMs (its entry
+                        // may be a tick behind a switch back to live), then gone.
+                        track.missingSince ??= at;
+                        if (at - track.missingSince > carryMs || track.drawn === null) {
+                            delete out[id];
+                            track.drawn = null;
+                            track.source = null;
+                            track.blend = null;
+                            continue;
+                        }
+                        target = track.drawn;
+                    }
+                    source = 'live';
+                }
+                else if (record !== undefined && record.mode === 'path' && record.mv >= mv) {
+                    const clock = ownerNow(id);
+                    // The freshest state there is: in the announce window the entry
+                    // itself, after it the last one any snapshot showed.
+                    const base = entry ?? track.last ?? track.live?.state ?? track.drawn;
+                    if (clock === null) {
+                        // The record is here; only the owner's clock is not yet. Hold
+                        // what was drawn: nothing is late, so this is not a carry.
+                        const held = track.drawn ?? base;
+                        if (held === null)
+                            delete out[id];
+                        else
+                            out[id] = held;
+                        continue;
+                    }
+                    const point = pathAt(record.points, clock - delay);
+                    if (point !== null && base !== null) {
+                        target = place(base, point, mv, 'path');
+                        source = 'path';
+                    }
+                }
+                else if (entry !== undefined && entry.mode === 'path' && entryMv >= mv) {
+                    // The record is late, but the owner is still announcing the
+                    // switch in its snapshots: their position is the path's.
+                    target = entry;
+                    source = 'path';
+                }
+                if (target === null) {
+                    // Path due, record not here: carry the last live motion forward
+                    // for at most carryMs, then hold.
+                    const live = track.live;
+                    if (live === null) {
+                        if (track.drawn !== null)
+                            out[id] = track.drawn;
+                        else
+                            delete out[id];
+                        continue;
+                    }
+                    if (track.source !== 'carry') {
+                        track.carriedSince = at;
+                        carried += 1;
+                    }
+                    const ahead = Math.min(at - live.at, carryMs);
+                    const before = track.previousLive;
+                    let x = live.state.x;
+                    let z = live.state.z;
+                    if (before !== null && live.at > before.at) {
+                        const dt = live.at - before.at;
+                        x += ((live.state.x - before.state.x) / dt) * ahead;
+                        z += ((live.state.z - before.state.z) / dt) * ahead;
+                    }
+                    target = place(live.state, { x, z }, mv, 'path');
+                    source = 'carry';
+                }
+                if (track.source !== null && source !== track.source && track.drawn !== null) {
+                    switches += 1;
+                    track.blend = { from: track.drawn, at };
+                }
+                track.source = source;
+                let drawn = target;
+                if (track.blend !== null) {
+                    const alpha = smoothing === 0 ? 1 : (at - track.blend.at) / smoothing;
+                    if (alpha >= 1)
+                        track.blend = null;
+                    else {
+                        const from = track.blend.from;
+                        drawn = { ...drawn, x: from.x + (drawn.x - from.x) * alpha, z: from.z + (drawn.z - from.z) * alpha };
+                    }
+                }
+                track.drawn = drawn;
+                out[id] = drawn;
+            }
+            // An NPC neither source shows any more is forgotten, once it has been
+            // gone longer than anything here could still carry or blend it.
+            for (const [id, track] of tracks) {
+                if (!ids.has(id) && at - track.seenAt > carryMs + smoothing)
+                    tracks.delete(id);
+            }
+            return out;
+        },
+        stats: () => ({ carried, switches, tracks: tracks.size }),
+    };
+}

package/dist/netcode/shards.d.ts

@@ -0,0 +1,138 @@
+/**
+ * `joinShards` — one player's merged view of a match split across several
+ * hosts (sharded-match plan, slice S1; topology A: every player joins
+ * every host).
+ *
+ * ```ts
+ * const match = joinShards<Ship, Move>({
+ *   transport: node,
+ *   label: 'arena.move',
+ *   assignment,                 // { epoch, hosts: { [shard]: nodeHex }, owner: { [id]: shard } }
+ *   local: { id: myId, predict: move },
+ *   interest: cellsAround(x, z),
+ * });
+ * renderLoop(() => draw(match.view()));   // merged: remote interpolated, own predicted
+ * onKey(input => match.input(input));     // to the shard that owns you, only
+ * lobby.onAssignment(next => match.setAssignment(next));
+ * ```
+ *
+ * One {@link joinNetcode} per shard host, with `local` only on the shard
+ * that owns this player. **An entity is drawn only from the shard that
+ * owns it at the installed epoch**, so a host can show nothing it does not
+ * own:
+ *
+ * - an entry from any other shard is dropped (`droppedNotOwner`);
+ * - a shard whose newest snapshot is from another epoch is **frozen**: what
+ *   it sends is not drawn, and its entities stay at their last drawn state,
+ *   minus any it no longer owns, until it reaches the installed epoch (an
+ *   older one: `droppedStaleEpoch` counts the entries refused) or
+ *   {@link ShardedMatch.setAssignment} installs its newer one here
+ *   (`heldNewerEpoch`). Freezing rather than blanking an older shard means
+ *   a player that installs an epoch before its hosts do sees no blink.
+ *
+ * Counts are per snapshot a shard delivered, not per frame drawn.
+ *
+ * When an entity's owner changes, the old owner's last copy lingers for
+ * `lingerMs` or until the new owner first shows it, whichever is first —
+ * as `joinWorld` lingers a departed region's entities — so a handover does
+ * not blink. A shard that is rejoined (its host changed, or this player's
+ * owner moved to or from it) keeps showing what it last drew, minus what it
+ * no longer owns, until the new connection delivers its first snapshot: so
+ * a planned move does not blank the rest of either shard for a join round
+ * trip.
+ *
+ * What this is not: the host's half (simulate only what you own, refuse
+ * input for others, leases) is the shard host recipe's (S2), and where the
+ * assignment comes from is the lobby's (S4).
+ */
+import { type JoinNetcodeOptions, type LocalEntity, type NetcodeStats } from './client.js';
+import { type NetcodeTransport } from './wire.js';
+/** Who hosts which shard and who owns which entity, at one epoch. */
+export interface ShardAssignment {
+    /** Strictly increasing; a lower or equal one is never installed over a higher. */
+    readonly epoch: number;
+    /** Shard name → its host's node id, 16 hex. */
+    readonly hosts: Readonly<Record<string, string>>;
+    /** Entity id → the shard that owns it. Omit to resolve with `ownerOf`. */
+    readonly owner?: Readonly<Record<string, string>>;
+}
+/** {@link joinShards}'s argument. */
+export interface JoinShardsOptions<E, I> extends Omit<JoinNetcodeOptions<E, I>, 'host' | 'local' | 'epoch' | 'transport' | 'label' | 'interest' | 'sequencer'> {
+    readonly transport: NetcodeTransport;
+    /** The netcode label every shard host serves. */
+    readonly label: string;
+    readonly assignment: ShardAssignment;
+    /**
+     * The owning shard of `id` at `assignment`, for an assignment that does
+     * not list every entity (NPCs owned by `hash(id) mod hosts`, D7).
+     * Default: `assignment.owner[id]`. An entity with no owner is not drawn.
+     */
+    ownerOf?(id: string, assignment: ShardAssignment): string | undefined;
+    /** This player's own entity, predicted locally; its inputs go to its owner only. Omit to spectate. */
+    readonly local?: LocalEntity<E, I>;
+    /** Interest keys, sent to every shard. */
+    readonly interest?: readonly string[];
+    /** How long an entity whose owner changed keeps its old owner's last state, ms. Default 1000. */
+    readonly lingerMs?: number;
+    /**
+     * Whether this player still hears the lobby (`leaseWatch` over the
+     * assignment's `renewals`). While `false` the view is frozen where it
+     * was, inputs are not sent (`inputsFrozen`), and `stats().frozen` is
+     * `true` — the game shows "reconnecting".
+     */
+    live?(): boolean;
+}
+/** Per-shard state, as {@link ShardedMatch.stats} reports it. */
+export interface ShardStats extends NetcodeStats {
+    /** The host serving the shard. */
+    readonly host: string;
+    /** ms since this shard last delivered a snapshot (since joining, before the first). */
+    readonly silentMs: number;
+}
+/** What {@link ShardedMatch.stats} reports. */
+export interface ShardedMatchStats {
+    /** The installed epoch. */
+    readonly epoch: number;
+    readonly shards: Readonly<Record<string, ShardStats>>;
+    /** Entries a shard sent for an entity it does not own at the installed epoch. */
+    readonly droppedNotOwner: number;
+    /** Entries dropped because their shard's snapshot was from an older epoch. */
+    readonly droppedStaleEpoch: number;
+    /** Snapshots from a newer epoch than installed, whose shard was held at its last state. */
+    readonly heldNewerEpoch: number;
+    /** Inputs not sent: no shard owns this player at the installed epoch. */
+    readonly inputsUnowned: number;
+    /** Inputs not sent because the view was frozen (`live` false). */
+    readonly inputsFrozen: number;
+    /** The view is frozen: this player does not hear the lobby. */
+    readonly frozen: boolean;
+}
+/** The running merged view. */
+export interface ShardedMatch<E, I> {
+    /** Every shard's own entities, merged; yours predicted. */
+    view(): Readonly<Record<string, E>>;
+    /** Apply `data` locally and send it to the shard that owns you, stamped with the epoch. */
+    input(data: I): void;
+    /** That shard's host clock, for hit claims. `null` before its first pong, or for an unknown shard. */
+    hostNow(shard: string): number | null;
+    /** Receive only these interest keys, from every shard. */
+    setInterest(keys: readonly string[]): void;
+    /**
+     * Install a newer assignment. Returns `false`, and changes nothing, for
+     * an epoch not above the installed one. A shard whose host changed is
+     * rejoined; so are the old and new owners of this player, which moves
+     * the prediction to the new owner.
+     */
+    setAssignment(next: ShardAssignment): boolean;
+    /**
+     * Resolves once every shard has delivered a snapshot; rejects with the
+     * first shard's join failure. Follows rejoins: a shard rejoined by
+     * {@link setAssignment} while this waits is waited on afresh, and the
+     * closed connection it replaced neither resolves nor rejects it.
+     */
+    ready(): Promise<void>;
+    stats(): ShardedMatchStats;
+    close(): void;
+}
+/** Join every shard host of a match and merge their views. */
+export declare function joinShards<E, I>(options: JoinShardsOptions<E, I>): ShardedMatch<E, I>;

package/dist/netcode/shards.js

@@ -0,0 +1,270 @@
+/**
+ * `joinShards` — one player's merged view of a match split across several
+ * hosts (sharded-match plan, slice S1; topology A: every player joins
+ * every host).
+ *
+ * ```ts
+ * const match = joinShards<Ship, Move>({
+ *   transport: node,
+ *   label: 'arena.move',
+ *   assignment,                 // { epoch, hosts: { [shard]: nodeHex }, owner: { [id]: shard } }
+ *   local: { id: myId, predict: move },
+ *   interest: cellsAround(x, z),
+ * });
+ * renderLoop(() => draw(match.view()));   // merged: remote interpolated, own predicted
+ * onKey(input => match.input(input));     // to the shard that owns you, only
+ * lobby.onAssignment(next => match.setAssignment(next));
+ * ```
+ *
+ * One {@link joinNetcode} per shard host, with `local` only on the shard
+ * that owns this player. **An entity is drawn only from the shard that
+ * owns it at the installed epoch**, so a host can show nothing it does not
+ * own:
+ *
+ * - an entry from any other shard is dropped (`droppedNotOwner`);
+ * - a shard whose newest snapshot is from another epoch is **frozen**: what
+ *   it sends is not drawn, and its entities stay at their last drawn state,
+ *   minus any it no longer owns, until it reaches the installed epoch (an
+ *   older one: `droppedStaleEpoch` counts the entries refused) or
+ *   {@link ShardedMatch.setAssignment} installs its newer one here
+ *   (`heldNewerEpoch`). Freezing rather than blanking an older shard means
+ *   a player that installs an epoch before its hosts do sees no blink.
+ *
+ * Counts are per snapshot a shard delivered, not per frame drawn.
+ *
+ * When an entity's owner changes, the old owner's last copy lingers for
+ * `lingerMs` or until the new owner first shows it, whichever is first —
+ * as `joinWorld` lingers a departed region's entities — so a handover does
+ * not blink. A shard that is rejoined (its host changed, or this player's
+ * owner moved to or from it) keeps showing what it last drew, minus what it
+ * no longer owns, until the new connection delivers its first snapshot: so
+ * a planned move does not blank the rest of either shard for a join round
+ * trip.
+ *
+ * What this is not: the host's half (simulate only what you own, refuse
+ * input for others, leases) is the shard host recipe's (S2), and where the
+ * assignment comes from is the lobby's (S4).
+ */
+import { createInputSequencer, joinNetcode, } from './client.js';
+import { defaultNow, peerHex } from './wire.js';
+/** Join every shard host of a match and merge their views. */
+export function joinShards(options) {
+    const now = options.now ?? defaultNow;
+    const lingerMs = Math.max(0, options.lingerMs ?? 1000);
+    const ownerOf = options.ownerOf ?? ((id, at) => at.owner?.[id]);
+    const self = options.local?.id;
+    let installed = checked(options.assignment);
+    let interest = options.interest;
+    let closed = false;
+    const shards = new Map();
+    const lingering = new Map();
+    let droppedNotOwner = 0;
+    let droppedStaleEpoch = 0;
+    let heldNewerEpoch = 0;
+    let inputsUnowned = 0;
+    let inputsFrozen = 0;
+    let frozenView = {};
+    const live = () => options.live?.() ?? true;
+    // One sequence for this player across every shard: a move to another
+    // owner continues it, and re-sends what the old owner never acknowledged.
+    const sequencer = createInputSequencer();
+    // Everything a shard's `joinNetcode` takes as given; the rest is per shard.
+    const { assignment: _assignment, ownerOf: _ownerOf, local: _local, interest: _interest, lingerMs: _lingerMs, live: _live, ...netcodeOptions } = options;
+    const selfOwner = () => (self === undefined ? undefined : ownerOf(self, installed));
+    const join = (shard, host, drawn = {}) => {
+        const owns = shard === selfOwner();
+        const client = joinNetcode({
+            ...netcodeOptions,
+            host,
+            ...(owns && options.local !== undefined ? { local: options.local } : {}),
+            ...(interest === undefined ? {} : { interest }),
+            epoch: () => installed.epoch,
+            sequencer,
+            now,
+        });
+        return { host, client, owns, drawn, seen: 0, joinedAt: now() };
+    };
+    for (const [shard, host] of Object.entries(installed.hosts))
+        shards.set(shard, join(shard, host));
+    return {
+        view() {
+            if (!live())
+                return frozenView;
+            const out = {};
+            const at = now();
+            for (const [shard, entry] of shards) {
+                const stats = entry.client.stats();
+                const fresh = stats.snapshots !== entry.seen;
+                entry.seen = stats.snapshots;
+                const epoch = stats.epoch;
+                if (stats.snapshots === 0) {
+                    // Rejoined, and nothing from the new connection yet: what the old
+                    // one last drew holds, minus what this shard no longer owns —
+                    // the same rule as a frozen shard, so a rejoin does not blink.
+                    const held = {};
+                    for (const [id, state] of Object.entries(entry.drawn)) {
+                        if (ownerOf(id, installed) === shard)
+                            held[id] = state;
+                    }
+                    entry.drawn = held;
+                    Object.assign(out, held);
+                    continue;
+                }
+                if (epoch !== null && epoch !== installed.epoch) {
+                    // Not at our epoch: nothing it sends now is drawn. It is frozen
+                    // where it was last drawn, minus what it no longer owns — so a
+                    // player that installs an epoch before its hosts do does not see
+                    // the world blink, and a non-owner is still never drawn.
+                    if (fresh) {
+                        if (epoch > installed.epoch)
+                            heldNewerEpoch += 1;
+                        else
+                            droppedStaleEpoch += Object.keys(entry.client.view()).length;
+                    }
+                    const frozen = {};
+                    for (const [id, state] of Object.entries(entry.drawn)) {
+                        if (ownerOf(id, installed) === shard)
+                            frozen[id] = state;
+                    }
+                    entry.drawn = frozen;
+                    Object.assign(out, frozen);
+                    continue;
+                }
+                const entities = entry.client.view();
+                const drawn = {};
+                for (const id of Object.keys(entities)) {
+                    if (ownerOf(id, installed) !== shard) {
+                        if (fresh)
+                            droppedNotOwner += 1;
+                        continue;
+                    }
+                    drawn[id] = entities[id];
+                    lingering.delete(id);
+                }
+                entry.drawn = drawn;
+                Object.assign(out, drawn);
+            }
+            for (const [id, { state, until }] of lingering) {
+                if (until <= at)
+                    lingering.delete(id);
+                else if (!(id in out))
+                    out[id] = state;
+            }
+            frozenView = out;
+            return out;
+        },
+        input(data) {
+            if (closed)
+                return;
+            if (!live()) {
+                inputsFrozen += 1;
+                return;
+            }
+            const owner = selfOwner();
+            const entry = owner === undefined ? undefined : shards.get(owner);
+            if (entry === undefined || !entry.owns) {
+                inputsUnowned += 1;
+                return;
+            }
+            entry.client.input(data);
+        },
+        hostNow: shard => shards.get(shard)?.client.hostNow() ?? null,
+        setInterest(keys) {
+            interest = [...keys];
+            for (const entry of shards.values())
+                entry.client.setInterest(keys);
+        },
+        setAssignment(next) {
+            if (closed)
+                return false;
+            const candidate = checked(next);
+            if (candidate.epoch <= installed.epoch)
+                return false;
+            const previous = installed;
+            const previousSelfOwner = selfOwner();
+            // What was on screen, before ownership moves: a handover lingers.
+            const at = now();
+            for (const [shard, entry] of shards) {
+                for (const [id, state] of Object.entries(entry.drawn)) {
+                    if (ownerOf(id, candidate) !== shard && ownerOf(id, previous) === shard) {
+                        lingering.set(id, { state, until: at + lingerMs });
+                    }
+                }
+            }
+            installed = candidate;
+            const nextSelfOwner = selfOwner();
+            // What a rejoined shard goes on showing until its first snapshot.
+            const carried = new Map();
+            for (const [shard, entry] of shards) {
+                const host = candidate.hosts[shard];
+                const ownershipMoved = previousSelfOwner !== nextSelfOwner && (shard === previousSelfOwner || shard === nextSelfOwner);
+                if (host === entry.host && !ownershipMoved)
+                    continue;
+                entry.client.close();
+                shards.delete(shard);
+                if (host !== undefined)
+                    carried.set(shard, entry.drawn);
+            }
+            for (const [shard, host] of Object.entries(candidate.hosts)) {
+                if (!shards.has(shard))
+                    shards.set(shard, join(shard, host, carried.get(shard)));
+            }
+            return true;
+        },
+        ready() {
+            // Waits on the live connections: one replaced while this waits is
+            // dropped from the wait (its close rejects its own `ready()`), and the
+            // set is checked again once the rest settle.
+            const current = (entry) => [...shards.values()].includes(entry);
+            const wait = () => {
+                const entries = [...shards.values()];
+                return Promise.all(entries.map(entry => entry.client.ready().catch((error) => {
+                    if (closed || current(entry))
+                        throw error;
+                }))).then(() => (closed || entries.every(current) ? undefined : wait()));
+            };
+            return wait();
+        },
+        stats() {
+            const at = now();
+            const perShard = {};
+            for (const [shard, entry] of shards) {
+                const stats = entry.client.stats();
+                perShard[shard] = { ...stats, host: entry.host, silentMs: at - (stats.lastSnapshotAt ?? entry.joinedAt) };
+            }
+            return {
+                epoch: installed.epoch,
+                shards: perShard,
+                droppedNotOwner,
+                droppedStaleEpoch,
+                heldNewerEpoch,
+                inputsUnowned,
+                inputsFrozen,
+                frozen: !live(),
+            };
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            for (const entry of shards.values())
+                entry.client.close();
+            shards.clear();
+            lingering.clear();
+        },
+    };
+}
+/** An assignment with its host ids normalised, or a `TypeError`. */
+function checked(assignment) {
+    if (!Number.isSafeInteger(assignment.epoch) || assignment.epoch < 0) {
+        throw new TypeError(`assignment epoch must be a non-negative integer, got ${String(assignment.epoch)}`);
+    }
+    const hosts = {};
+    for (const [shard, host] of Object.entries(assignment.hosts)) {
+        const hex = peerHex(host);
+        if (hex === null)
+            throw new TypeError(`shard ${shard}: host is not a node id: ${JSON.stringify(host)}`);
+        hosts[shard] = hex;
+    }
+    return { ...assignment, hosts };
+}