keri-ts 2.0.1 → 2.2.0

package/esm/keri/npm/src/app/mailbox/mailbox-admin.js

@@ -0,0 +1,208 @@
+/**
+ * Mailbox administration for a single-signature controller: authorize or revoke
+ * a remote mailbox through a provider's admin endpoint, owned by the library so
+ * that every host (CLI, wallet, service) runs one implementation.
+ *
+ * Operations follow the workflow contract: `addMailbox` and `removeMailbox`
+ * are explicit, sign the endpoint-role reply, post it to the provider and
+ * return after the reply is accepted locally. `mailboxStatus` is a pure read of
+ * the accepted end-role state. `waitForMailboxState` only observes: it never
+ * starts workers and returns a timed-out value instead of throwing.
+ *
+ * Boundaries:
+ * - Dependencies are the concrete collaborators below, not an AgentRuntime
+ *   (ADR-0013). The host owns their lifetimes.
+ * - The provider is reached through the supplied fetch-only `HttpClient`; nothing
+ *   here needs TCP, files or `node:` modules, so a browser can call it.
+ * - Group controllers do not use these operations: their propose/complete split
+ *   needs the Poster worker (to deliver the proposal to co-signers) and the
+ *   group coordinator, which a library `proposeMailbox` would have to take as
+ *   collaborators. `completeMailboxAdmin` is the shared tail they reuse.
+ */
+import { concatBytes } from "cesr-ts";
+import { call, sleep } from "effection";
+import { ValidationError } from "../../core/errors.js";
+import { Roles } from "../../core/roles.js";
+import { endpointRoleAccepted, loadAcceptedEndpointRole, proposeGroupEndpointRole, } from "../identity/endpoint-roleing.js";
+import { systemClock } from "../runtime/runtime-clock.js";
+import { buildCesrStreamRequest } from "../transport/cesr-http.js";
+import { kelHeads, pinKelPublished } from "./kel-publishing.js";
+import { collectKelSubmission } from "./kel-submission.js";
+import { fetchEndpointUrls, preferredUrl } from "./mailboxing.js";
+/** Derive the mailbox-admin URL relative to one hosted endpoint path. */
+export function mailboxAdminUrl(url) {
+    try {
+        const parsed = new URL(url);
+        const pathname = parsed.pathname.replace(/\/+$/, "") || "/";
+        const base = pathname === "/" ? "" : pathname;
+        return `${parsed.protocol}//${parsed.host}${base}/mailboxes`;
+    }
+    catch (error) {
+        if (error instanceof ValidationError) {
+            throw error;
+        }
+        throw new ValidationError(`Invalid mailbox URL: ${url}`);
+    }
+}
+/**
+ * Preferred accepted URL of a mailbox endpoint.
+ *
+ * @throws ValidationError when no location reply has been accepted for it.
+ */
+export function requireMailboxEndpointUrl(hby, mailbox) {
+    const url = preferredUrl(fetchEndpointUrls(hby, mailbox));
+    if (!url) {
+        throw new ValidationError(`No endpoint URL is stored for mailbox ${mailbox}.`);
+    }
+    return url;
+}
+/** Read the accepted mailbox end-role state for `pre`; mutates nothing. */
+export function mailboxStatus(hby, pre, mailbox) {
+    const end = hby.db.ends.get([pre, Roles.mailbox, mailbox]);
+    if (!end)
+        return { mailbox, state: "absent" };
+    return { mailbox, state: end.allowed ? "authorized" : "revoked" };
+}
+/**
+ * Authorize `mailbox` for `hab`: sign (or reload) the mailbox end-role reply,
+ * post it to the provider and accept it locally.
+ *
+ * @throws ValidationError for a missing endpoint URL, a provider HTTP failure or a reply that local state does not accept.
+ */
+export function* addMailbox(deps, hab, mailbox) {
+    const url = requireMailboxEndpointUrl(deps.hby, mailbox);
+    const existing = deps.hby.db.ends.get([hab.pre, Roles.mailbox, mailbox]);
+    const rpy = existing?.allowed
+        ? hab.loadEndRole(hab.pre, mailbox, Roles.mailbox)
+        : hab.makeEndRole(mailbox, Roles.mailbox, true);
+    return yield* completeMailboxAdmin(deps, hab, mailbox, url, rpy, true);
+}
+/**
+ * Revoke `mailbox` for `hab`: sign a mailbox end-role cut, post it to the
+ * provider and accept it locally. Single-signature controllers only.
+ *
+ * @throws ValidationError as for `addMailbox`.
+ */
+export function* removeMailbox(deps, hab, mailbox) {
+    const url = requireMailboxEndpointUrl(deps.hby, mailbox);
+    const rpy = hab.makeEndRole(mailbox, Roles.mailbox, false);
+    return yield* completeMailboxAdmin(deps, hab, mailbox, url, rpy, false);
+}
+/**
+ * Post one signed mailbox end-role reply to the provider, accept it locally and
+ * confirm the resulting state. Also the completion step of a group add whose
+ * role was already approved.
+ *
+ * @param allow True when the reply grants the role; false when it cuts it.
+ * @throws ValidationError when the reply is empty, the provider refuses it, or local state does not reflect it.
+ */
+export function* completeMailboxAdmin(deps, hab, mailbox, endpointUrl, rpy, allow) {
+    if (rpy.length === 0) {
+        throw new ValidationError(`No accepted mailbox role reply is available for ${hab.pre}.`);
+    }
+    // The request carries the KEL up to this establishment event, which the mailbox then holds.
+    const established = kelHeads(deps.hby, hab.pre);
+    const response = yield* postMailboxAdmin(deps.http, endpointUrl, mailbox, collectKelSubmission(deps.hby, hab.pre), rpy);
+    if (!response.ok) {
+        throw new ValidationError(`Mailbox admin request failed with HTTP ${response.status}: ${response.body}`);
+    }
+    yield* deps.reactor.processBytes(rpy, {});
+    yield* deps.protocol.processEscrowsOnce();
+    const status = mailboxStatus(deps.hby, hab.pre, mailbox);
+    if (allow && status.state !== "authorized") {
+        throw new ValidationError("Mailbox add was not accepted into local state.");
+    }
+    if (!allow && status.state !== "revoked") {
+        throw new ValidationError("Mailbox removal was not accepted into local state.");
+    }
+    // The publisher need not send a KEL this request just carried.
+    if (allow && established)
+        pinKelPublished(deps.hby.db, hab.pre, mailbox, established, systemClock);
+    deps.publisher?.prompt(hab.pre);
+    return status;
+}
+/**
+ * Propose a group's mailbox authorization (`/end/role/add`) to the other members, who
+ * approve it with `approveGroupProposal`. Returns without waiting and sends nothing
+ * to the provider; {@link completeGroupMailbox} does that once the role is accepted.
+ * The caller runs the Poster's delivery for the duration.
+ */
+export function* proposeGroupMailbox(hby, protocol, postman, group, mailbox) {
+    return yield* proposeGroupEndpointRole(hby, protocol, postman, group, {
+        eid: mailbox,
+        role: Roles.mailbox,
+        allow: true,
+    });
+}
+/**
+ * Finish a group mailbox add whose end-role reply the members approved: post the
+ * accepted reply to the provider and confirm local state.
+ *
+ * @throws ValidationError while the group has not accepted the mailbox role, or as for `completeMailboxAdmin`.
+ */
+export function* completeGroupMailbox(deps, group, mailbox) {
+    if (!endpointRoleAccepted(deps.hby, group.pre, Roles.mailbox, mailbox)) {
+        throw new ValidationError(`Mailbox role for ${mailbox} is not yet approved for group ${group.pre}.`);
+    }
+    const url = requireMailboxEndpointUrl(deps.hby, mailbox);
+    const rpy = loadAcceptedEndpointRole(group, mailbox, Roles.mailbox);
+    return yield* completeMailboxAdmin(deps, group, mailbox, url, rpy, true);
+}
+/**
+ * Observe `read` until it reports the wanted state or the deadline passes. It
+ * starts no workers: whoever owns the runtime makes the state change.
+ */
+export function* waitForMailboxState(read, { want, deadline, clock = systemClock, pollMs = 250 }) {
+    while (true) {
+        const status = read();
+        if (status.state === want)
+            return { outcome: "settled", status };
+        const remaining = deadline - clock.now();
+        if (remaining <= 0)
+            return { outcome: "timed-out", status };
+        yield* sleep(Math.min(pollMs, remaining));
+    }
+}
+/**
+ * Submit one admin request: the raw `application/cesr` body first, then the
+ * legacy multipart form when the provider answers 406 or 415.
+ */
+function* postMailboxAdmin(http, url, mailbox, submission, rpy) {
+    const raw = yield* postMailboxAdminCesr(http, url, mailbox, concatBytes(submission.replay, rpy));
+    if (raw.ok || (raw.status !== 406 && raw.status !== 415))
+        return raw;
+    return yield* postMailboxAdminMultipart(http, url, mailbox, submission, rpy);
+}
+/** Send finite administrative CESR bytes with `CESR-DESTINATION` selecting the hosted mailbox. */
+export function* postMailboxAdminCesr(http, url, mailbox, bytes) {
+    const request = buildCesrStreamRequest(bytes, { destination: mailbox });
+    const response = yield* http.request(mailboxAdminUrl(url), {
+        method: "POST",
+        headers: request.headers,
+        body: request.body,
+    });
+    // Administrative JSON/diagnostics are finite metadata, not an unbounded stream.
+    return { ok: response.ok, status: response.status, body: new TextDecoder().decode(response.body) };
+}
+/**
+ * Send the legacy multipart form (`kel`, optional `delkel`, `rpy`). The platform
+ * encoder runs once so the generated boundary stays consistent with the body.
+ */
+export function* postMailboxAdminMultipart(http, url, mailbox, submission, rpy) {
+    const decoder = new TextDecoder();
+    const form = new FormData();
+    form.append("kel", decoder.decode(submission.kel));
+    if (submission.delkel.length > 0) {
+        form.append("delkel", decoder.decode(submission.delkel));
+    }
+    form.append("rpy", decoder.decode(rpy));
+    const prepared = new Response(form);
+    prepared.headers.set("CESR-DESTINATION", mailbox);
+    const bytes = yield* call(() => prepared.arrayBuffer());
+    const response = yield* http.request(mailboxAdminUrl(url), {
+        method: "POST",
+        headers: prepared.headers,
+        body: bytes,
+    });
+    return { ok: response.ok, status: response.status, body: decoder.decode(response.body) };
+}

package/esm/keri/npm/src/app/mailbox/mailbox-poller.js

@@ -1,12 +1,34 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _MailboxPoller_dirty;
 /** Recipient mailbox polling: signed queries, awaited SSE intake and persisted cursor progression. */
 import { call, scoped, spawn } from "effection";
 import { abortable } from "../runtime/abortable.js";
+import { doEvery, PROTOCOL_TOCK_MS } from "../runtime/doing.js";
 import { runtimeTurn } from "../runtime/runtime-turn.js";
+import { waitOnClock } from "../runtime/workflow-contract.js";
 import { isLegacyCesrMediaRejection, readResponseDetail } from "../transport/cesr-egress.js";
-import { buildCesrRequest, CESR_CONTENT_TYPE, KERIPY_CESR_JSON_CONTENT_TYPE } from "../transport/cesr-http.js";
+import { buildCesrRequest, CESR_CONTENT_TYPE, KERIPY_CESR_JSON_CONTENT_TYPE, } from "../transport/cesr-http.js";
 import { requestWithHeaderTimeout } from "../transport/httping.js";
+import { TransportError } from "../transport/transport-error.js";
 import { consumeMailboxSse } from "./mailbox-sse.js";
 import { mailboxPollEndpoints } from "./mailboxing.js";
+/** Tocks between the poller's full re-selection of workers: 160 tocks of 31.25 ms is five seconds. */
+export const MAILBOX_POLLER_SWEEP_TOCKS = 160;
+/**
+ * The production pacing of the mailbox poller. Between sweeps it re-selects workers only when the registered
+ * topics or the number of identifiers change, or for an identifier passed to {@link MailboxPoller.prompt} (the
+ * runtime prompts one when a mailbox end role is accepted). Endpoint changes other than an accepted mailbox end
+ * role (a rotated-in witness, a location accepted after its role, another process writing the same store) are
+ * therefore picked up within five seconds.
+ */
+export const MAILBOX_POLLER_PACING = Object.freeze({
+    tockMs: PROTOCOL_TOCK_MS,
+    sweepTocks: MAILBOX_POLLER_SWEEP_TOCKS,
+});
 /**
  * Retrieve recipient messages from remote mailbox or witness endpoints over HTTP/SSE.
  *
@@ -60,7 +82,25 @@ export class MailboxPoller {
             writable: true,
             value: void 0
         });
-        const { timeouts } = options;
+        /** Told after each poll a mailbox served. */
+        Object.defineProperty(this, "onPolled", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Told when a mailbox answers 403. */
+        Object.defineProperty(this, "onUnauthorized", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Identifiers whose mailbox endpoints changed; the poller re-selects their workers on the next tock. */
+        _MailboxPoller_dirty.set(this, new Set());
+        const { timeouts, onPolled, onUnauthorized } = options;
+        this.onPolled = onPolled;
+        this.onUnauthorized = onUnauthorized;
         this.hby = hby;
         this.mailboxDirector = mailboxDirector;
         this.timeoutPolicy = normalizeMailboxPollingTimeoutPolicy(timeouts);
@@ -84,14 +124,29 @@ export class MailboxPoller {
      * @param onBatch Awaited endpoint-batch consumer; the durable event cursor advances only after it succeeds. Failure or cancellation leaves that event available for later retrieval.
      * @throws Consumer/transport failures propagate; endpoint workers are joined on scope exit.
      */
-    *pollDo(onBatch) {
+    *pollDo(onBatch, pacing = MAILBOX_POLLER_PACING) {
         const remoteWorkers = new Map();
+        // deno-lint-ignore no-this-alias -- Generator callbacks have no lexical this.
+        const self = this;
+        let habs = -1, shape = "";
         try {
-            while (true) {
-                const topics = this.mailboxDirector.registeredTopics();
-                yield* this.syncRemoteWorkers(remoteWorkers, onBatch, topics);
-                yield* runtimeTurn();
-            }
+            return yield* doEvery(this.clock, pacing.tockMs, function* (tock) {
+                const topics = self.mailboxDirector.registeredTopics();
+                // Every tock looks only at what changed: the topics, the number of identifiers, and the identifiers
+                // prompted since. Everything else is found by the sweep on tock 0 and every `sweepTocks`.
+                const changed = topics.join("|") !== shape || self.hby.habs.size !== habs;
+                if (tock % pacing.sweepTocks === 0 || changed) {
+                    shape = topics.join("|");
+                    habs = self.hby.habs.size;
+                    __classPrivateFieldGet(self, _MailboxPoller_dirty, "f").clear();
+                    yield* self.syncRemoteWorkers(remoteWorkers, onBatch, topics);
+                }
+                else if (__classPrivateFieldGet(self, _MailboxPoller_dirty, "f").size) {
+                    const only = new Set(__classPrivateFieldGet(self, _MailboxPoller_dirty, "f"));
+                    __classPrivateFieldGet(self, _MailboxPoller_dirty, "f").clear();
+                    yield* self.syncRemoteWorkers(remoteWorkers, onBatch, topics, only);
+                }
+            });
         }
         finally {
             for (const task of [...remoteWorkers.values()].reverse()) {
@@ -99,19 +154,27 @@ export class MailboxPoller {
             }
         }
     }
+    /**
+     * Tell the poller `pre`'s mailbox roles or endpoints changed, so its workers are re-selected on the next tock
+     * instead of at the next sweep.
+     */
+    prompt(pre) {
+        __classPrivateFieldGet(this, _MailboxPoller_dirty, "f").add(pre);
+    }
     /**
      * Stream one remote response through its consumer before recording cursor progress.
      *
      * @param target Mailbox subject habitat plus the actual local signer (a member for groups).
      * @param endpoint Selected remote endpoint AID and HTTP(S) URL.
      * @param onBatch Awaited consumer; successful completion precedes durable cursor advancement.
+     * @returns How the poll ended; see {@link PollOutcome}.
      */
     *pollRemoteEndpointOnce(target, endpoint, onBatch) {
         const cursor = this.mailboxDirector.remoteQueryCursor(target.targetPre, endpoint.eid);
         // deno-lint-ignore no-this-alias -- Generator callbacks have no lexical this.
         const self = this;
         // The concrete HTTP/SSE operation owns and joins this whole poll attempt.
-        yield* call(() => fetchMailboxMessages(target.signerHab, target.targetPre, endpoint.eid, endpoint.url, cursor, mailboxFetchTimeoutPolicy(this.timeoutPolicy), this.http, this.clock, function* deliverThenAdvanceCursor(message) {
+        return yield* call(() => fetchMailboxMessages(target.signerHab, target.targetPre, endpoint.eid, endpoint.url, cursor, mailboxFetchTimeoutPolicy(this.timeoutPolicy), this.http, this.clock, function* deliverThenAdvanceCursor(message) {
             yield* call(() => onBatch({ pre: target.targetPre, eid: endpoint.eid, messages: [message.msg] }));
             self.mailboxDirector.updateRemoteCursor(target.targetPre, endpoint.eid, message.topic, message.idx);
         }));
@@ -123,10 +186,10 @@ export class MailboxPoller {
      * @param onBatch Shared awaited consumer used independently by each endpoint worker.
      * @param topics Current registered topics; no topics means no remote workers.
      */
-    *syncRemoteWorkers(remoteWorkers, onBatch, topics) {
+    *syncRemoteWorkers(remoteWorkers, onBatch, topics, only) {
         const active = new Set();
         if (topics.length > 0) {
-            for (const target of this.remotePollTargets()) {
+            for (const target of this.remotePollTargets(only)) {
                 for (const endpoint of mailboxPollEndpoints(target.hab)) {
                     const workerKey = `${target.targetPre}:${endpoint.key}`;
                     active.add(workerKey);
@@ -139,7 +202,7 @@ export class MailboxPoller {
             }
         }
         for (const [workerKey, task] of [...remoteWorkers.entries()]) {
-            if (active.has(workerKey)) {
+            if (active.has(workerKey) || (only && !only.has(workerKey.slice(0, workerKey.indexOf(":"))))) {
                 continue;
             }
             yield* task.halt();
@@ -150,26 +213,50 @@ export class MailboxPoller {
      * Poll one remote endpoint continuously in the long-lived runtime shape.
      *
      * This keeps KERIpy's "one poller per endpoint" behavior while preserving
-     * `keri-ts`'s split between mailbox transport and runtime parser ownership.
+     * `keri-ts`'s split between mailbox transport and runtime parser ownership. Each poll ends in a
+     * {@link PollOutcome}; {@link nextPoll} maps it and the backoff state to the next action. A mailbox that is
+     * unreachable or refuses is retried on {@link MailboxPoller.RefusalBackoff}, never in a tight loop and never
+     * by failing the runtime. A 403 also prompts the KEL publisher, which owns posting the KEL.
      *
      * @param target Mailbox subject habitat plus the actual local signer (a member for groups).
      * @param endpoint Selected remote endpoint AID and HTTP(S) URL.
      * @param onBatch Awaited consumer; successful completion precedes durable cursor advancement.
      */
     *remoteEndpointWorker(target, endpoint, onBatch) {
+        let state = { backoffMs: 0 };
         while (true) {
-            yield* this.pollRemoteEndpointOnce(target, endpoint, onBatch);
-            yield* runtimeTurn();
+            const outcome = yield* this.pollRemoteEndpointOnce(target, endpoint, onBatch);
+            const step = nextPoll(state, outcome, {
+                initialMs: this.timeoutPolicy.refusalInitialMs,
+                maxMs: this.timeoutPolicy.refusalMaxMs,
+            });
+            state = step.state;
+            switch (step.action.kind) {
+                case "poll":
+                    this.onPolled?.(target.targetPre, endpoint.eid);
+                    yield* runtimeTurn();
+                    break;
+                case "prompt-publisher":
+                    this.onUnauthorized?.(target.targetPre, endpoint.eid);
+                    yield* waitOnClock(this.clock, step.action.ms);
+                    break;
+                case "wait":
+                    yield* waitOnClock(this.clock, step.action.ms);
+                    break;
+            }
         }
     }
     /**
      * Select locally pollable subjects without substituting the group for its member signer.
      *
+     * @param only When given, only these identifiers are considered.
      * @returns Local subject/signing pairs; groups without an available local member are omitted.
      */
-    remotePollTargets() {
+    remotePollTargets(only) {
         const targets = [];
         for (const hab of this.hby.habs.values()) {
+            if (only && !only.has(hab.pre))
+                continue;
             const signerHab = this.pollSignerHab(hab);
             if (!signerHab) {
                 continue;
@@ -195,6 +282,7 @@ export class MailboxPoller {
         return this.hby.habs.get(mid) ?? null;
     }
 }
+_MailboxPoller_dirty = new WeakMap();
 /**
  * Default header acquisition (5 seconds) and absolute poll window (30 seconds).
  */
@@ -205,10 +293,13 @@ Object.defineProperty(MailboxPoller, "DefaultTimeoutPolicy", {
     value: Object.freeze({
         requestOpenTimeoutMs: 5_000,
         maxPollDurationMs: 30_000,
+        readIdleTimeoutMs: 500,
+        refusalInitialMs: 1_000,
+        refusalMaxMs: 30_000,
     })
 });
 /**
- * Idle read window after the first complete event, in milliseconds.
+ * Default idle read window after the first complete event, in milliseconds.
  */
 Object.defineProperty(MailboxPoller, "ReadIdleTimeoutMs", {
     enumerable: true,
@@ -216,15 +307,61 @@ Object.defineProperty(MailboxPoller, "ReadIdleTimeoutMs", {
     writable: true,
     value: 500
 });
+/**
+ * Wait after a poll that was not served (a refused status, a 403, no response headers, or an unreachable
+ * host), in milliseconds: it starts at `initialMs`, doubles with each consecutive failure up to `maxMs` and
+ * starts over after a served poll. Without a wait the worker would repeat the same signed request as fast as
+ * the loop turns.
+ */
+Object.defineProperty(MailboxPoller, "RefusalBackoff", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: Object.freeze({
+        initialMs: 1_000,
+        maxMs: 30_000,
+    })
+});
+/** Classify a non-success status: 403 is the mailbox not recognising the requester; anything else is a refusal. */
+export function classifyPollRefusal(status) {
+    switch (status) {
+        case 403:
+            return "unauthorized";
+        default:
+            return "refused";
+    }
+}
+/** Double the backoff (or start it) and wait that long. */
+export function backOff(state, backoff = MailboxPoller.RefusalBackoff) {
+    const backoffMs = Math.min(backoff.maxMs, state.backoffMs ? state.backoffMs * 2 : backoff.initialMs);
+    return { state: { backoffMs }, action: { kind: "wait", ms: backoffMs } };
+}
+/** The transition: where a poll's outcome leaves the worker, and what it does about it. */
+export function nextPoll(state, outcome, backoff = MailboxPoller.RefusalBackoff) {
+    switch (outcome) {
+        case "served":
+            return { state: { backoffMs: 0 }, action: { kind: "poll" } };
+        case "unauthorized": {
+            const step = backOff(state, backoff);
+            return { state: step.state, action: { kind: "prompt-publisher", ms: step.state.backoffMs } };
+        }
+        case "no-response":
+        case "unreachable":
+        case "refused":
+            return backOff(state, backoff);
+    }
+}
 /**
  * Query one endpoint and consume complete SSE events within one request scope.
- * Header timeout or non-success status ends this attempt without events. Successful
+ * A header timeout, a failed connection or a non-success status ends this attempt without events. Successful
  * body processing and its cleanup finish before the endpoint worker begins another poll.
- * The sole alternate submission is the exact pre-intake KERIpy media refusal:
+ * The sole second request is the exact pre-intake KERIpy media refusal:
  * drain/close that request, then reuse the same signed query and attachments with
  * legacy metadata. Authentication or protocol refusals do not take that branch.
  * consume runs inline and is awaited before the caller persists its cursor; this
  * callback is a scoped event-consumer boundary, not deferred workflow scheduling.
+ * A `TransportError` from the connection (opening it or reading its body) is an outcome; a failure of
+ * `consume`, cancellation and cleanup failures propagate.
  *
  * @param hab Local signing habitat; its state/store lifetime remains with the caller.
  * @param targetPre Mailbox subject AID; may be a group distinct from hab.
@@ -235,37 +372,62 @@ Object.defineProperty(MailboxPoller, "ReadIdleTimeoutMs", {
  * @param http Borrowed HTTP implementation selected by composition.
  * @param clock Borrowed clock with epoch-millisecond now and millisecond timer delays.
  * @param consume Awaited complete-event consumer; false stops the poll and errors propagate before remote cursor advancement.
+ * @returns How the poll ended.
  */
 function* fetchMailboxMessages(hab, targetPre, src, url, topics, timeouts, http, clock, consume) {
     const query = hab.query(targetPre, src, { route: "mbx", q: { topics } });
     const prepared = buildCesrRequest(query, { destination: src });
-    for (const contentType of [CESR_CONTENT_TYPE, KERIPY_CESR_JSON_CONTENT_TYPE]) {
-        const alternate = yield* scoped(function* () {
-            const controller = new AbortController();
-            const request = {
-                method: "POST",
-                headers: { ...prepared.headers, "Content-Type": contentType },
-                body: prepared.body,
-                signal: controller.signal,
-            };
-            const response = yield* requestWithHeaderTimeout(http, clock, url, request, timeouts.requestOpenTimeoutMs);
-            if (!response)
-                return false;
-            if (!response.ok) {
-                const detail = yield* abortable(signal => readResponseDetail(response, signal));
-                return isLegacyCesrMediaRejection(request, response.status, detail);
-            }
-            yield* consumeMailboxSse(response, controller, consume, clock, {
-                idleTimeoutMs: timeouts.readIdleTimeoutMs,
-                maxDurationMs: timeouts.maxReadDurationMs,
+    // A consumer's own TransportError is the consumer's failure, not the mailbox's.
+    let consumerFailure;
+    const guarded = function* (message) {
+        try {
+            return yield* consume(message);
+        }
+        catch (error) {
+            consumerFailure = error;
+            throw error;
+        }
+    };
+    const attempt = function* (contentType) {
+        try {
+            // Closing a refused request is part of the scoped operation. A close failure escapes before another
+            // request can submit these same signed bytes.
+            return yield* scoped(function* () {
+                const controller = new AbortController();
+                const request = {
+                    method: "POST",
+                    headers: { ...prepared.headers, "Content-Type": contentType },
+                    body: prepared.body,
+                    signal: controller.signal,
+                };
+                const response = yield* requestWithHeaderTimeout(http, clock, url, request, timeouts.requestOpenTimeoutMs);
+                if (!response)
+                    return { kind: "outcome", outcome: "no-response" };
+                if (!response.ok) {
+                    const detail = yield* abortable(signal => readResponseDetail(response, signal));
+                    if (isLegacyCesrMediaRejection(request, response.status, detail))
+                        return { kind: "legacy-media-required" };
+                    return { kind: "outcome", outcome: classifyPollRefusal(response.status) };
+                }
+                yield* consumeMailboxSse(response, controller, guarded, clock, {
+                    idleTimeoutMs: timeouts.readIdleTimeoutMs,
+                    maxDurationMs: timeouts.maxReadDurationMs,
+                });
+                return { kind: "outcome", outcome: "served" };
             });
-            return false;
-        });
-        // Closing the refused request is part of the scoped operation above. A close
-        // failure escapes before another request can submit these same signed bytes.
-        if (!alternate)
-            return;
-    }
+        }
+        catch (error) {
+            if (error instanceof TransportError && error !== consumerFailure) {
+                return { kind: "outcome", outcome: "unreachable" };
+            }
+            throw error;
+        }
+    };
+    const first = yield* attempt(CESR_CONTENT_TYPE);
+    if (first.kind === "outcome")
+        return first.outcome;
+    const second = yield* attempt(KERIPY_CESR_JSON_CONTENT_TYPE);
+    return second.kind === "outcome" ? second.outcome : "refused";
 }
 /**
  * Normalize the caller's polling policy against the existing defaults.
@@ -278,19 +440,22 @@ function normalizeMailboxPollingTimeoutPolicy(overrides) {
     return Object.freeze({
         requestOpenTimeoutMs: positiveTimeoutMs(overrides?.requestOpenTimeoutMs, defaults.requestOpenTimeoutMs),
         maxPollDurationMs: positiveTimeoutMs(overrides?.maxPollDurationMs, defaults.maxPollDurationMs),
+        readIdleTimeoutMs: positiveTimeoutMs(overrides?.readIdleTimeoutMs, defaults.readIdleTimeoutMs),
+        refusalInitialMs: positiveTimeoutMs(overrides?.refusalInitialMs, defaults.refusalInitialMs),
+        refusalMaxMs: positiveTimeoutMs(overrides?.refusalMaxMs, defaults.refusalMaxMs),
     });
 }
 /**
  * Translate poller windows into the concrete request/SSE settings.
  *
  * @param timeouts Normalized poller policy.
- * @returns Per-attempt windows with the fixed 500 ms read-idle interval.
+ * @returns Per-attempt windows with the policy's read-idle interval.
  */
 function mailboxFetchTimeoutPolicy(timeouts) {
     return {
         requestOpenTimeoutMs: timeouts.requestOpenTimeoutMs,
         maxReadDurationMs: timeouts.maxPollDurationMs,
-        readIdleTimeoutMs: MailboxPoller.ReadIdleTimeoutMs,
+        readIdleTimeoutMs: timeouts.readIdleTimeoutMs,
     };
 }
 /**