opencode-courier 0.2.3 → 0.3.0

package/dist/group.js

@@ -0,0 +1,247 @@
+import { isNotFound, millis, num, obj, str } from "./json.js";
+import { envelope, groupNotice, isStatus } from "./notices.js";
+import { scanEntries } from "./storage.js";
+/**
+ * Join groups: each member of a parent's group under `group/<parentID>/<name>/<sessionID>`, with its
+ * held report or how it left; released and dropped once none is out. docs/reference.md, § Join groups.
+ */
+const PREFIX = "group/";
+/** What a group may be called: short, and with no `/`, which separates the parts of its keys, or `"`, which closes an attribute. */
+const NAME = /^[\w.-]{1,60}$/;
+export const isGroupName = (value) => typeof value === "string" && NAME.test(value);
+export const memberKey = (parentID, group, sessionID) => `${PREFIX}${parentID}/${group}/${sessionID}`;
+/** The key prefix of a parent's groups, and of one group's members. */
+export const groupsPrefix = (parentID) => `${PREFIX}${parentID}/`;
+export const groupPrefix = (parentID, group) => `${groupsPrefix(parentID)}${group}/`;
+/** A member's standing from its stored value, or `released` when there is none. */
+export function standingOf(member) {
+    if (!member)
+        return "released";
+    if (member.report)
+        return "held";
+    return member.left?.by ?? "out";
+}
+function readMember(value) {
+    const given = obj(value);
+    const title = str(given.title);
+    const joinedAt = num(given.joinedAt);
+    if (title === undefined || joinedAt === undefined)
+        return undefined;
+    const report = readReport(given.report);
+    const left = obj(given.left);
+    const by = str(left.by);
+    return {
+        title,
+        joinedAt,
+        ...(report ? { report } : {}),
+        ...(by === "failed" || by === "interrupted" || by === "deleted" || by === "dropped" ? { left: { at: num(left.at) ?? 0, by } } : {}),
+    };
+}
+function readReport(value) {
+    const given = obj(value);
+    const status = given.status;
+    const message = str(given.message);
+    const at = num(given.at);
+    if (!isStatus(status) || message === undefined || at === undefined)
+        return undefined;
+    return { at, status, message, ...(given.artifacts !== undefined ? { artifacts: given.artifacts } : {}) };
+}
+/** A member as the storage takes it, which asks for an index signature the interface lacks. */
+const stored = (member) => ({ ...member });
+/** The members under `prefix`, a key prefix within `PREFIX`; a value that is not a member is left out. */
+async function membersUnder(storage, prefix) {
+    const entries = await scanEntries(storage, prefix);
+    return entries.flatMap(({ key, value }) => {
+        const parts = `${prefix.slice(PREFIX.length)}${key}`.split("/");
+        const member = parts.length === 3 ? readMember(value) : undefined;
+        return member ? [{ ...member, parentID: parts[0], group: parts[1], sessionID: parts[2] }] : [];
+    });
+}
+/** The member a session is in a parent's group, if the group is open and it is a member. */
+export async function memberOf(storage, parentID, group, sessionID) {
+    return readMember(await storage.get(memberKey(parentID, group, sessionID)));
+}
+/** Makes a spawned session a member of its parent's group, opening the group if it was not. */
+export async function joinGroup(storage, parentID, group, sessionID, title, at) {
+    await storage.set(memberKey(parentID, group, sessionID), stored({ title, joinedAt: at }));
+}
+/** Whether every member of a group has a held report or has left: released once the parent's turn has ended. */
+const complete = (members) => members.every((member) => member.report || member.left);
+/** The members of each group among `members`, by the claim key of the group. */
+function byGroup(members) {
+    const groups = new Map();
+    for (const member of members) {
+        const key = claimKey(member.parentID, member.group);
+        const group = groups.get(key);
+        if (group)
+            group.push(member);
+        else
+            groups.set(key, [member]);
+    }
+    return groups;
+}
+/** Whether a parent has a complete group with a report in it, which the scheduler delivers once the parent's turn has ended. */
+export async function hasCompleteGroup(storage, parentID) {
+    return [...byGroup(await membersUnder(storage, groupsPrefix(parentID))).values()].some((members) => complete(members) && members.some((member) => member.report));
+}
+/** Holds a member's report with its group, in place of an earlier one, or of how it had left. */
+export async function holdReport(storage, membership, report) {
+    const { parentID, group, sessionID, title, joinedAt } = membership;
+    await storage.set(memberKey(parentID, group, sessionID), stored({ title, joinedAt, report }));
+}
+/** How many members of a group have reported and how many have not left, and whether the group is complete. */
+export async function groupStanding(storage, parentID, group) {
+    const members = await membersUnder(storage, groupPrefix(parentID, group));
+    return {
+        reported: members.filter((member) => member.report).length,
+        members: members.filter((member) => !member.left).length,
+        complete: complete(members),
+    };
+}
+/** A session's membership of a parent's group, if it is a member; `out` says whether the group still waits for its report. */
+export async function membershipOf(storage, parentID, group, sessionID) {
+    const member = await memberOf(storage, parentID, group, sessionID);
+    return member && { ...member, parentID, group, sessionID, out: standingOf(member) === "out" };
+}
+/**
+ * Notes that a member left its group without a report: its turn failed or was interrupted, it was deleted or dropped. Read
+ * again first: one whose report is held meanwhile keeps it, one that left keeps why. True when that completes the group.
+ */
+export async function markLeft(storage, membership, by, at) {
+    const { parentID, group, sessionID } = membership;
+    const current = await memberOf(storage, parentID, group, sessionID);
+    if (!current || standingOf(current) !== "out")
+        return false;
+    await storage.set(memberKey(parentID, group, sessionID), stored({ title: current.title, joinedAt: current.joinedAt, left: { at, by } }));
+    return (await groupStanding(storage, parentID, group)).complete;
+}
+/** `markLeft` for a member not read yet; undefined when it is in no open group. */
+export async function leaveGroup(storage, parentID, group, sessionID, by, at) {
+    const membership = await membershipOf(storage, parentID, group, sessionID);
+    return membership && (await markLeft(storage, membership, by, at));
+}
+/**
+ * Puts a member whose report is held back among those out: its latest word to the parent was a blocked report. Read
+ * again first: a group released meanwhile is not opened again, and a report held since is kept.
+ */
+export async function unholdForBlocked(storage, membership) {
+    const { parentID, group, sessionID, title, joinedAt } = membership;
+    if (!membership.report)
+        return;
+    const current = await memberOf(storage, parentID, group, sessionID);
+    if (JSON.stringify(current?.report) !== JSON.stringify(membership.report))
+        return;
+    await storage.set(memberKey(parentID, group, sessionID), stored({ title, joinedAt }));
+}
+/** Drops a member from its group as its roster entry goes, unless its report is held: that still goes to the parent. True when dropped. */
+export async function dropMember(storage, parentID, group, sessionID) {
+    const member = await memberOf(storage, parentID, group, sessionID);
+    if (!member || member.report)
+        return false;
+    await storage.remove(memberKey(parentID, group, sessionID));
+    return true;
+}
+/** Drops a member from its group whatever it holds: its report could not be held after all, so it goes on its own. */
+export async function unholdReport(storage, membership) {
+    await storage.remove(memberKey(membership.parentID, membership.group, membership.sessionID));
+}
+/** Drops every group of a parent, whose members' reports can no longer be delivered. */
+export async function dropGroups(storage, parentID) {
+    const members = await membersUnder(storage, groupsPrefix(parentID));
+    await Promise.all(members.map((member) => storage.remove(memberKey(parentID, member.group, member.sessionID))));
+}
+/** The claim key of a group's release, in the hub's shared set of deliveries under way. */
+const claimKey = (parentID, group) => `group:${parentID}/${group}`;
+/**
+ * Delivers every released group once, from the scheduler's tick: claimed in the shared `claimed`, re-read,
+ * delivered and only then dropped, so a failed delivery is tried again at the next tick, and a crash in between delivers it again.
+ */
+export async function deliverReleased(ports, claimed) {
+    const groups = [...byGroup(await membersUnder(ports.storage, PREFIX))].filter(([key, members]) => complete(members) && !claimed.has(key));
+    // Claimed all at once, before any delivery, so a tick alongside claims none of these.
+    for (const [key] of groups)
+        claimed.add(key);
+    await Promise.all(groups.map(([key, members]) => releaseClaimed(ports, claimed, key, members[0])));
+}
+async function releaseClaimed(ports, claimed, key, { parentID, group }) {
+    try {
+        await release(ports, parentID, group);
+    }
+    catch (error) {
+        ports.log(`courier group ${group} of ${parentID}: ${String(error)}`);
+    }
+    finally {
+        claimed.delete(key);
+    }
+}
+/**
+ * Whether the parent's turn that started a group's last member has ended, so no more join it; `gone` when OpenCode no
+ * longer knows the parent. A turn ending stamps the session's `time.idle`, which a shutdown does not.
+ */
+async function sealed(ports, parentID, members) {
+    const joined = Math.max(...members.map((member) => member.joinedAt));
+    try {
+        const { time } = await ports.session.get({ sessionID: parentID });
+        // NaN, for a parent that has ended no turn yet, holds it.
+        return millis(time.idle) >= joined;
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return "gone";
+        throw error;
+    }
+}
+async function release(ports, parentID, group) {
+    // Re-read: another server may have delivered and dropped it since the scan.
+    const members = (await membersUnder(ports.storage, groupPrefix(parentID, group))).sort((a, b) => a.joinedAt - b.joinedAt);
+    if (!members.length || !complete(members))
+        return;
+    const seal = await sealed(ports, parentID, members);
+    if (!seal)
+        return;
+    if (seal === "gone")
+        return drop(ports, parentID, group, members, "the session is gone");
+    const reports = members.flatMap((member) => (member.report ? [{ sessionID: member.sessionID, title: member.title, ...member.report }] : []));
+    const left = members.flatMap((member) => (member.left ? [{ sessionID: member.sessionID, title: member.title, by: member.left.by }] : []));
+    if (reports.length) {
+        try {
+            await ports.session.synthetic({
+                sessionID: parentID,
+                text: envelope(reports.map((report) => report.sessionID).join(","), groupNotice(group, reports, left), {
+                    group,
+                    reports: String(reports.length),
+                }),
+                description: `Reports of group ${group}`,
+                metadata: { source: "courier", from: reports.map((report) => report.sessionID).join(","), group, reports: reports.length },
+                delivery: "steer",
+            });
+        }
+        catch (error) {
+            // A parent OpenCode no longer knows will never take it: dropped, like the children of a deleted session.
+            if (!isNotFound(error)) {
+                ports.log(`courier group ${group} of ${parentID} not delivered, held for another try: ${String(error)}`);
+                return;
+            }
+            return drop(ports, parentID, group, members, `the session is gone (${String(error)})`);
+        }
+    }
+    await drop(ports, parentID, group, members);
+}
+/** Drops a group's members once delivered, or unsent, saying why. */
+async function drop(ports, parentID, group, members, unsent) {
+    if (unsent)
+        ports.log(`courier group ${group} of ${parentID} dropped: ${unsent}`);
+    // A member left behind here is delivered again at the next tick, as after a crash: logged, so it can be seen.
+    const dropped = await Promise.allSettled(members.map((member) => dropDelivered(ports.storage, member)));
+    for (const [index, result] of dropped.entries())
+        if (result.status === "rejected")
+            ports.log(`courier group ${group} of ${parentID}: delivered, but ${members[index].sessionID} could not be dropped: ${String(result.reason)}`);
+}
+/** Drops a delivered member's key, unless it was written again since it was read: that report is still to deliver. */
+async function dropDelivered(storage, delivered) {
+    const key = memberKey(delivered.parentID, delivered.group, delivered.sessionID);
+    const { parentID, group, sessionID, ...read } = delivered;
+    if (JSON.stringify(readMember(await storage.get(key))) !== JSON.stringify(read))
+        return;
+    await storage.remove(key);
+}

package/dist/hub.d.ts

@@ -1,6 +1,7 @@
 import type { Plugin } from "@opencode/plugin";
 import type { Server } from "node:http";
 import { type LaterPorts } from "./later.js";
+import type { SpawnGate } from "./limits.js";
 import type { Asked, Outcome, Withdrawal } from "./notices.js";
 import type { Permissions, Waiting } from "./relay.js";
 import type { RosterStorage } from "./roster.js";
@@ -8,36 +9,15 @@ import { type Registry } from "./storage.js";
 import type { WebhookConfig, WebhookPorts } from "./webhook.js";
 type Context = Plugin.Context;
 /**
- * The plugin's process-wide state, in one place. OpenCode sets the plugin up once per location
- * (project or worktree), all in one process, and after an update loads the new copy of the package
- * next to the old one until the old one unloads; so the state every instance shares lives on
- * `globalThis`, outside the module graph, and this is the only module that puts it there.
- *
- * The hub is versioned by `HUB_VERSION`, not by the package's version: copies whose hub has the
- * same shape share one hub, however far apart their releases, and only a change to the hub's shape
- * (the ports a `Member` carries included) or to the meaning of one of its fields bumps it. An
- * optional field that a copy without it gets along without, such as `Member.location` or
- * `Scheduler.running`, is added without a bump while no release has the hub (the latest is 0.2.2).
- *
- * Version skew: a copy that finds a hub of another version under `opencode-courier.hub` logs that
- * once and runs its own hub under `opencode-courier.hub@<version>`. Whatever its version, a hub
- * takes the claim sets and the other shared objects of the copies before the hub from their own
- * keys (`opencode-courier.claimed`, `.watched`, `.forms`, `.questions`, `.receiver`, `.locations`),
- * making each when it is missing, so every copy in the process, with a hub or without, claims an
- * event or a delivery in the same set, and an old and a new copy never both act on it. Those keys'
- * shapes and meanings are therefore fixed: a hub version that needs other ones makes new keys, and
- * keeps claiming in the old ones too while a copy that uses them may still be loaded. `members` is
- * the one thing each version keeps to itself, so a job a hub runs once for its members runs once
- * per hub version, and still claims what it acts on in the shared sets, which keep it from acting
- * twice.
+ * The plugin's process-wide state on `globalThis`, shared by every loaded copy; only this module puts
+ * it there. `HUB_VERSION`, the fixed claim keys and version skew: docs/reference.md, § Several copies.
  */
-export declare const HUB_VERSION = 1;
+export declare const HUB_VERSION = 2;
 /** The key of the hub; a copy that finds another version there keeps its own under `${HUB_KEY}@<version>`. */
 export declare const HUB_KEY = "opencode-courier.hub";
 /**
- * A question this process knows: one whose call waits (`call`), or one whose call was cut off,
- * which is answered by message. `link` withdraws the top session's question call that passes its
- * answer on, once the question is settled without that call.
+ * A question this process knows: its call waits (`call`), or was cut off and is answered by message.
+ * `link` withdraws the top session's call passing the answer on, once settled without that call.
  */
 export interface Question extends Asked {
     /** The directory of the location the call runs in, whose shutdown withdraws its form. */
@@ -51,11 +31,8 @@ export interface Question extends Asked {
     settling?: Promise<void>;
 }
 /**
- * The relay's timings, carried by its ports: how long a question cut off by a closing location
- * waits before an instance still loaded tells its top session, how long an answer waits for another
- * one to it that is still being passed on, how long what follows a call's end waits for the notice
- * of the question to go out, and how long a dismissal is held to see whether the location is
- * shutting down.
+ * The relay's timings, carried by its ports: the closing grace before a cut-off question is told, the
+ * wait for an answer still being passed on, the wait for a notice to go out, and the dismissal hold.
  */
 export interface QuestionTiming {
     readonly closingGraceMs: number;
@@ -76,7 +53,8 @@ export interface QuestionPorts {
 }
 export interface WatchPorts {
     readonly storage: RosterStorage;
-    readonly session: Pick<Context["session"], "synthetic">;
+    /** `context` reads the last reply of a session that ended its turn without reporting. */
+    readonly session: Pick<Context["session"], "synthetic" | "context">;
     readonly event: Pick<Context["event"], "subscribe">;
     /**
      * The permission domains of every loaded location, whose pending requests are relayed when the
@@ -86,20 +64,20 @@ export interface WatchPorts {
     /** The clock a location shutdown is recorded by: the question relay's, which judges it. */
     readonly now: () => number;
     readonly log: (message: string) => void;
+    /** Has the scheduler deliver what is due now rather than at its next tick: a group completed, or its parent's turn ended. */
+    readonly nudge: () => void;
 }
 /**
- * What every plugin instance in the process shares. A hub follows OpenCode's events through two of
- * its members, one a standby, and a copy of another hub version, or one from before the hub, follows
- * them too, all sent the same events; so an event id is claimed synchronously and handled once.
- * `waiting` holds the permission requests a session was told about and has not answered;
- * `answered`, requests answered before anyone was told, so a notice whose roster lookup was
- * overtaken by the answer is not sent. `forms` does the same for the forms of spawned sessions.
+ * What every plugin instance in the process shares. Several subscriptions and copies see the same
+ * events, so each is claimed synchronously and handled once; `answered` keeps stale notices unsent.
  */
 export interface WatchState {
     readonly seen: Set<string>;
     readonly waiting: Waiting;
     readonly answered: Set<string>;
     readonly forms: FormsTold;
+    /** The type of each item enqueued for a spawned session, by inbox id, for its delivery to look up. */
+    readonly inbox: Map<string, string>;
 }
 /** The forms sessions were told about, kept apart from the permission requests. */
 export interface FormsTold {
@@ -123,9 +101,8 @@ export interface Receivers {
     closing?: Promise<void>;
 }
 /**
- * The question relay's state, shared by every instance, since a child and the session it asks can
- * be in different locations: the questions told to a top session and not yet settled, the cut-off
- * ones whose top session has been told so, and the question calls waiting for their form to be shown.
+ * The question relay's state, shared by every instance, as a child and the session it asks can be in
+ * different locations: open questions, cut-off ones already told, and calls waiting for their form.
  */
 export interface QuestionState {
     readonly questions: Map<string, Question>;
@@ -135,9 +112,8 @@ export interface QuestionState {
     readonly passing: Map<string, Promise<unknown>>;
     readonly answered: Set<string>;
     /**
-     * The ports of the loaded instances, of every copy of the plugin. A release before the hub picks
-     * one here to tell a cut-off question through, so every copy keeps it filled; this copy reads its
-     * hub's members, and this only for an instance of another copy, when it has none.
+     * The ports of every loaded instance of every copy. A release before the hub picks one here to tell
+     * a cut-off question through, so every copy fills it; this copy reads it only for another copy.
      */
     readonly loaded: Set<QuestionPorts>;
     /** How many instances follow OpenCode's events now, and whether any has since the process started. */
@@ -186,11 +162,8 @@ export interface Scheduler {
     /** The loop's interval, while it runs. */
     timer?: unknown;
     /**
-     * The tick under way, if any, whichever copy of the plugin started it and whether or not its
-     * member is still loaded. A tick that falls due meanwhile renews the owner key for it, for up to a
-     * minute from its start, and is skipped; past that minute one whose member has left holds up
-     * nothing, and the next tick starts. Optional, since a copy of the same hub version made before it
-     * existed keeps only `ticking`.
+     * The tick under way, whichever copy started it: for a minute the key is renewed for it and due
+     * ticks skip; past it, one whose member left holds nothing up. Older copies have only `ticking`.
      */
     running?: Tick;
     /**
@@ -200,6 +173,8 @@ export interface Scheduler {
     ticking?: Member;
     /** One tick, by the copy of the plugin that joined last, so a copy loaded after an update runs its own code. */
     tick?: () => Promise<void>;
+    /** Whether a nudge came since the tick under way started, whichever copy's, so it ticks once more when done. */
+    nudged?: boolean;
 }
 /** How the hub starts and stops the scheduler's loop, and waits before re-reading the owner key; tests pass their own. */
 export interface Timers {
@@ -208,10 +183,8 @@ export interface Timers {
     readonly wait: (ms: number) => Promise<void>;
 }
 /**
- * The key in the plugin's storage, shared by every OpenCode server on one data directory, naming
- * the server whose scheduler delivers the `courier_later` messages: `{ server, at }`, its id and
- * when it last wrote the key, in epoch milliseconds. Outside `later/`, which the schedulers scan
- * for messages, those of copies before the key included.
+ * The storage key, shared by every server on one data directory, naming the server whose scheduler
+ * delivers `courier_later` messages: `{ server, at }`, its id and when it last wrote (epoch ms).
  */
 export declare const OWNER_KEY = "scheduler/owner";
 /** How long the owner key holds without being renewed; the owner renews it every tick, four times as often. */
@@ -229,9 +202,8 @@ export declare const OWNER_WAIT_MS = 500;
  */
 export declare const SERVER: string;
 /**
- * How long an unloading instance waits, before it lets go, for the work it leaves behind: what it
- * started itself, a tick or an event's notice still under way through it, and on the last leave the
- * owner key's release.
+ * How long an unloading instance waits for the work it leaves behind: what it started itself, a tick
+ * or a notice under way through it, and on the last leave the owner key's release.
  */
 export declare const LEAVE_MS = 2000;
 /** How many subscriptions to OpenCode's events a hub keeps, each through another member: one, and a standby. */
@@ -261,7 +233,7 @@ export interface Hub {
     /** The ids of the `courier_later` messages being delivered. */
     readonly claimed: Set<string>;
     /** The events handled, and the permission requests a session was told about or that were answered first. */
-    readonly watched: Omit<WatchState, "forms">;
+    readonly watched: Omit<WatchState, "forms" | "inbox">;
     /** The forms sessions were told about, and those settled first. */
     readonly forms: FormsTold;
     /**
@@ -278,26 +250,25 @@ export interface Hub {
 export interface Opened {
     readonly hub: Hub;
     /**
-     * Adds a loaded instance to the hub and its permission domain to `locations`; returns its leave,
-     * which takes both out again. The first instance to join logs a hub of another version found
-     * under `HUB_KEY`. An instance joining a hub without members starts the scheduler's loop, with a
-     * tick at once; the last one to leave stops it. An instance joining while the hub has fewer than
-     * `WATCHERS` subscriptions to OpenCode's events starts one through itself; when one leaves that
-     * has one, another member without one starts its replacement before it ends. The last leave
-     * settles once the scheduler's owner key is released, after the tick under way, whichever copy
-     * started it. Every leave first waits for the work its member leaves behind: what was handed to
-     * `track`, a tick under way through it, and the subscription it ran, which ends after the event
-     * it is handling; all of it, the release included, for up to `LEAVE_MS`. The question relay's
-     * own work is not waited for: it outlives the instance on purpose.
+     * Adds a loaded instance to the hub and `locations`; returns its leave. The first join starts the
+     * scheduler and watchers, the last leave stops them; a leave waits `LEAVE_MS` for the member's work.
      */
     readonly join: (member: Member) => () => Promise<void>;
     /** Hands the hub work a member started, which its leave waits for; the member's own background work. */
     readonly track: (member: Member, work: Promise<unknown>) => void;
+    /** The spawns under way, under a fixed key of its own rather than in the hub, so every hub version shares it. */
+    readonly gate: SpawnGate;
+    /** `WatchState.inbox`, under a fixed key of its own like the gate, so every hub version shares it. */
+    readonly inbox: Map<string, string>;
+    /**
+     * Runs a tick now, or once the tick under way has ended, so what has just fallen due (a released
+     * group) is delivered at once rather than at the next tick; nothing while no instance is loaded.
+     */
+    readonly nudge: () => void;
 }
 /**
- * Finds or makes this copy's hub in `registry`: the one under `HUB_KEY`, or its own under a
- * versioned key when a hub of another version holds that. Either way, its claim sets and shared
- * objects are the ones under the keys of the copies before the hub, made when missing.
+ * Finds or makes this copy's hub in `registry`: the one under `HUB_KEY`, or its own under a versioned
+ * key when another version holds that; its claim sets are the pre-hub keys', made when missing.
  */
 export declare function open(registry: Registry, timers?: Timers, server?: string): Opened;
 /** This copy's hub, in the process. */
@@ -306,20 +277,24 @@ export declare const hub: Hub;
 export declare const join: (member: Member) => () => Promise<void>;
 /** Hands this copy's hub work a member started; see `Opened.track`. */
 export declare const track: (member: Member, work: Promise<unknown>) => void;
+/** The spawns under way in the process; see `Opened.gate`. */
+export declare const gate: SpawnGate;
+/** The types of the items enqueued for spawned sessions; see `Opened.inbox`. */
+export declare const inbox: Map<string, string>;
+/** Has this copy's scheduler deliver what is due now; see `Opened.nudge`. */
+export declare const nudge: () => void;
 /** The member of this copy's hub set up with `location` that joined last, while it is loaded. */
 export declare function memberAt(location: object): Member | undefined;
 /**
- * The question ports of the member that has just joined at `location`, the newest there, for as long
- * as it stays loaded: resolved once, so an instance joining later at the same location, while this
- * one is still loaded, does not take its place.
+ * The question ports of the member that just joined at `location`, while it is loaded: resolved once,
+ * so a later instance at the same location does not take its place while this one is still loaded.
  */
 export declare function portsAt(location: object): () => QuestionPorts | undefined;
 /** The permission domains of the loaded instances. */
 export declare const permissions: () => MapIterator<Permissions>;
 /**
- * For tests: forgets every remembered id and the question relay's state, the relay's loaded
- * instances and its count of watchers included. The hub's members, the locations and the webhook
- * receiver are left alone; leaving and unloading take them out.
+ * For tests: forgets every remembered id, the spawns under way and the question relay's state, loaded
+ * instances and watcher count included. Members, locations and the receiver are left to unloading.
  */
 export declare function resetHub(): void;
 export {};