@opinionated-machine/sse-fallback 0.1.1 → 0.3.0

package/dist/subscription.js

@@ -1,4 +1,5 @@
 import { createSSEStreamParser } from '@opinionated-machine/sse-parser';
+import { validateSnapshotSource } from "./binding.js";
 import { DEFAULT_POLICY } from "./bindingTypes.js";
 import { Reconciler } from "./reconciler.js";
 import { backoffDelay, ResettableTimer, sleep } from "./scheduler.js";
@@ -13,6 +14,7 @@ export class SubscriptionStoppedError extends Error {
     status;
     limit;
     channel;
+    streamWasLive;
     constructor(detail) {
         super(`Subscription stopped (${detail.reason}) before the awaited event arrived`);
         this.name = 'SubscriptionStoppedError';
@@ -20,8 +22,83 @@ export class SubscriptionStoppedError extends Error {
         this.status = detail.status;
         this.limit = detail.limit;
         this.channel = detail.channel;
+        this.streamWasLive = detail.streamWasLive;
     }
 }
+/**
+ * A request answered with a status the channel cannot use. Handed to
+ * `onStreamError` / `onPollError`, and as the `cause` of a
+ * {@link FallbackDegradedError}.
+ */
+export class FallbackHttpError extends Error {
+    channel;
+    status;
+    request;
+    constructor(message, detail) {
+        super(message);
+        this.name = 'FallbackHttpError';
+        this.channel = detail.channel;
+        this.status = detail.status;
+        this.request = detail.request;
+    }
+}
+/**
+ * The stream stopped working for a reason the client can name, and the subscription is running
+ * without it: on its poll for an endpoint snapshot, or on nothing at all for a synthesized one.
+ *
+ * Delivered to `diagnostics.onDegraded` when the subscription degrades, and again every
+ * `degradationReportIntervalMs` for as long as it stays degraded, so a tab that lives on the
+ * fallback keeps showing up in an error tracker instead of reporting once and going quiet.
+ * Hand it to one as it is: the message names the route, the status and the channel left.
+ */
+export class FallbackDegradedError extends Error {
+    kind;
+    /** The refusing or rejecting status, for `'stream-refused'` and `'stream-rejected'`. */
+    status;
+    /** The stream request that failed. */
+    request;
+    /** Whether any stream of this subscription had carried bytes before it broke. */
+    streamWasLive;
+    /** Whether a poll keeps delivering while the stream is down. */
+    pollCarriesDelivery;
+    /** How many times this degradation has been reported, starting at 1. */
+    reportCount;
+    /** Time since the subscription degraded, 0 on the first report. */
+    degradedForMs;
+    constructor(detail) {
+        super(describeDegradation(detail), { cause: detail.cause });
+        this.name = 'FallbackDegradedError';
+        this.kind = detail.kind;
+        this.status = detail.status;
+        this.request = detail.request;
+        this.streamWasLive = detail.streamWasLive;
+        this.pollCarriesDelivery = detail.pollCarriesDelivery;
+        this.reportCount = detail.reportCount;
+        this.degradedForMs = detail.degradedForMs;
+    }
+}
+function describeDegradation(detail) {
+    const route = `${detail.request.method.toUpperCase()} ${detail.request.path}`;
+    const history = detail.streamWasLive ? 'it had been live' : 'it was never live';
+    const fault = {
+        'stream-refused': `was refused with ${detail.status}`,
+        'stream-rejected': detail.status === 200
+            ? `answered 200 with content-type ${detail.contentType || '(none)'}`
+            : `was rejected with ${detail.status}`,
+        'stream-silent': 'was accepted but closed without carrying any bytes',
+        'stream-unreachable': 'could not be reached',
+    }[detail.kind];
+    const fallback = detail.pollCarriesDelivery
+        ? 'updates arrive late, on the fallback poll'
+        : 'no poll covers this binding, so nothing is delivered until it recovers';
+    return `SSE stream ${route} ${fault} (${history}); ${fallback}`;
+}
+/**
+ * Consecutive versionless polls dropped for racing a pushed event, after
+ * which the next one is delivered anyway: a busy stream must not starve the
+ * poll that repairs an outage.
+ */
+const MAX_SUPERSEDED_POLLS = 3;
 class ResilientSubscriptionImpl {
     binding;
     transport;
@@ -33,8 +110,18 @@ class ResilientSubscriptionImpl {
     reconciler;
     pollGate;
     onAuthChallenge;
+    /**
+     * Whether a poll can deliver anything. False for a synthesized snapshot,
+     * which answers without asking the server: every poll would be a request
+     * for news that only the stream carries.
+     */
+    pollCanDeliver;
+    /** {@link FallbackPolicy.streamRefusal}, with `'auto'` resolved. */
+    streamRefusal;
     abortController = new AbortController();
     currentStreamAbort;
+    /** Wakes the stream loop out of its reconnect backoff, while it sleeps one. */
+    reconnectBackoffWake;
     statusValue = 'connecting';
     stopped = false;
     stopDetail;
@@ -50,27 +137,51 @@ class ResilientSubscriptionImpl {
     degraded = false;
     /** Whether the current stream has produced any bytes at all. */
     streamProducedBytes = false;
+    /** Whether ANY stream of this subscription ever produced bytes. */
+    streamEverProducedBytes = false;
+    /** Whether the stream has been given up for good, see `abandonStream`. */
+    streamAbandonedValue = false;
+    /** The degradation last reported through `onDegraded`, until the stream recovers. */
+    reportedDegradation;
+    /** Events the stream delivered, so a versionless poll can tell it was overtaken. */
+    streamDeliveries = 0;
+    supersededPolls = 0;
     pollInFlight = false;
     pollQueued = false;
     pollFailures = 0;
     idlePolls = 0;
     /** Polls attempted, for `subscriptionBudget.maxPolls`. */
     pollsAttempted = 0;
-    /** Whether the one auth retry has been spent since the last successful request. */
-    authRetrySpent = false;
+    /**
+     * The one auth retry per failure streak: the channel that spent it once
+     * `onAuthChallenge` ran, `'declined'` once it said it could not recover.
+     * Both hold until a request succeeds.
+     */
+    authCredit = 'available';
     deadman = new ResettableTimer(() => this.schedulePoll());
     staleConnection = new ResettableTimer(() => this.onStaleConnection());
     budgetTimer = new ResettableTimer(() => this.stopWith({ reason: 'budget-exhausted', limit: 'maxDurationMs' }));
+    degradationReminder = new ResettableTimer(() => this.emitDegradation());
     eventListeners = new Set();
     stateListeners = new Set();
     statusListeners = new Set();
     stopListeners = new Set();
+    establishedListeners = new Set();
     iteratorFeeds = new Set();
     constructor(binding, options) {
         this.binding = binding;
         this.transport = options.transport;
         this.params = options.params ?? {};
         this.policy = { ...DEFAULT_POLICY, ...binding.config.policy, ...options.policy };
+        validateSnapshotSource(binding.config);
+        assertPolicySuitsBinding(binding.config.snapshotSource, this.policy);
+        this.pollCanDeliver = binding.config.snapshotSource === 'endpoint';
+        this.streamRefusal =
+            this.policy.streamRefusal === 'auto'
+                ? this.pollCanDeliver
+                    ? 'keep-polling'
+                    : 'stop'
+                : this.policy.streamRefusal;
         this.diagnostics = options.diagnostics ?? {};
         this.random = options.random ?? Math.random;
         this.parseEventData = options.parseEventData ?? JSON.parse;
@@ -101,14 +212,7 @@ class ResilientSubscriptionImpl {
         if (this.policy.mode === 'poll-only') {
             // No stream is ever opened, so the machine starts where a dual-mode
             // subscription only lands after repeated connect failures.
-            this.degraded = true;
-            this.setStatus('polling');
-            if (this.policy.initialPoll === 'eager') {
-                this.schedulePoll();
-            }
-            else {
-                this.armDeadman();
-            }
+            this.degrade({ forcePoll: this.policy.initialPoll === 'eager' });
             return;
         }
         void this.runStreamLoop();
@@ -123,6 +227,9 @@ class ResilientSubscriptionImpl {
     get status() {
         return this.statusValue;
     }
+    get streamAbandoned() {
+        return this.streamAbandonedValue;
+    }
     get result() {
         return this.stopDetail;
     }
@@ -141,6 +248,10 @@ class ResilientSubscriptionImpl {
         this.statusListeners.add(listener);
         return () => this.statusListeners.delete(listener);
     }
+    onStreamEstablished(listener) {
+        this.establishedListeners.add(listener);
+        return () => this.establishedListeners.delete(listener);
+    }
     onStop(listener) {
         if (this.stopDetail !== undefined) {
             this.runListener(listener, this.stopDetail);
@@ -202,12 +313,16 @@ class ResilientSubscriptionImpl {
     nudge() {
         if (this.stopped)
             return;
-        this.schedulePoll();
-        // If the stream looks dead, force a reconnect check too.
-        if (this.streamConnected && this.policy.staleConnectionTimeoutMs !== 'off') {
-            // Byte-activity watchdog stays authoritative; nothing else to do here.
+        if (this.pollCanDeliver) {
+            this.schedulePoll();
+            // The byte-activity watchdog stays authoritative for the stream.
             return;
         }
+        // No poll to force: a fresh stream is the only repair there is, so
+        // reconnect now rather than wait out the backoff. A connect in flight or
+        // an open stream is not cut: aborting either would count as a connect
+        // failure and add a backoff, slowing down the recovery it was asked for.
+        this.reconnectBackoffWake?.abort();
     }
     stop() {
         this.stopWith({ reason: 'manual' });
@@ -220,6 +335,7 @@ class ResilientSubscriptionImpl {
         this.deadman.clear();
         this.staleConnection.clear();
         this.budgetTimer.clear();
+        this.degradationReminder.clear();
         this.currentStreamAbort?.abort();
         this.abortController.abort();
         this.setStatus('stopped', detail);
@@ -229,6 +345,7 @@ class ResilientSubscriptionImpl {
         for (const feed of this.iteratorFeeds)
             feed.finish();
         this.iteratorFeeds.clear();
+        this.establishedListeners.clear();
     }
     // --------------------------------------------------------------------
     // Stream loop
@@ -236,13 +353,16 @@ class ResilientSubscriptionImpl {
     // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the connect/consume/reconnect loop is a single state machine — splitting it would obscure the transitions
     async runStreamLoop() {
         let firstConnect = true;
-        while (!this.stopped) {
+        while (!this.stopped && !this.streamAbandoned) {
             const streamAbort = new AbortController();
             this.currentStreamAbort = streamAbort;
             const onMasterAbort = () => streamAbort.abort();
             this.abortController.signal.addEventListener('abort', onMasterAbort, { once: true });
             let connectFailed = false;
+            let failure;
+            let credentialsRefreshed = false;
             this.streamProducedBytes = false;
+            const request = this.binding.buildStreamRequest(this.params);
             // A connect that never produces headers must not park the subscription:
             // bound it here so it fails like any other connect failure (backoff,
             // degradation, fallback polling) instead of hanging forever.
@@ -251,7 +371,10 @@ class ResilientSubscriptionImpl {
                 connectTimeout.arm(this.policy.connectTimeoutMs);
             }
             try {
-                const response = await this.transport.openStream(this.binding.buildStreamRequest(this.params), { signal: streamAbort.signal, lastEventId: this.lastEventId });
+                const response = await this.transport.openStream(request, {
+                    signal: streamAbort.signal,
+                    lastEventId: this.lastEventId,
+                });
                 connectTimeout.clear();
                 if (this.stopped)
                     return;
@@ -263,7 +386,17 @@ class ResilientSubscriptionImpl {
                     // chunks of a refused connect are never consumed, and without this
                     // every retry would leak a socket.
                     streamAbort.abort();
-                    this.diagnostics.onStreamError?.(new Error(`SSE connect failed with status ${response.status}`));
+                    const error = new FallbackHttpError(response.status === 200
+                        ? `SSE connect answered 200 with content-type ${contentType}`
+                        : `SSE connect failed with status ${response.status}`, { channel: 'stream', status: response.status, request });
+                    failure = {
+                        kind: 'stream-rejected',
+                        status: response.status,
+                        contentType,
+                        request,
+                        cause: error,
+                    };
+                    this.diagnostics.onStreamError?.(error);
                     if (this.policy.unretryableStatuses.includes(response.status)) {
                         // An expired token is the common case behind a 401 in a SPA, and
                         // recovering without a page reload is the point of this package.
@@ -273,21 +406,39 @@ class ResilientSubscriptionImpl {
                         if (this.stopped)
                             return;
                         if (!recovered) {
+                            if (this.streamRefusal === 'keep-polling') {
+                                this.abandonStream({
+                                    kind: 'stream-refused',
+                                    status: response.status,
+                                    request,
+                                    cause: error,
+                                });
+                                return;
+                            }
                             this.stopWith({
                                 reason: 'unretryable-status',
                                 status: response.status,
                                 channel: 'stream',
+                                streamWasLive: this.streamEverProducedBytes,
                             });
                             return;
                         }
+                        // A refreshed token says nothing about the stream's health, so
+                        // the retry skips the failure count and the backoff, as a poll does.
+                        credentialsRefreshed = true;
                     }
                 }
                 else {
                     this.serverRetryHintMs = undefined;
                     if (firstConnect) {
-                        if (this.policy.initialPoll === 'eager') {
+                        // A synthesized snapshot has nothing to hydrate from, so it takes
+                        // the second branch: quiet is the normal state for a stream whose
+                        // events are rare, and holding it out of 'live' until a byte
+                        // arrives would mark a healthy surface as broken for hours. A
+                        // connection that is open and dead is the stale watchdog's job.
+                        if (this.pollCanDeliver && this.policy.initialPoll === 'eager') {
                             // Subscribe-first hydration: buffer live events until the
-                            // snapshot lands — zero missed-event window.
+                            // snapshot lands, a zero missed-event window.
                             this.reconciler.beginHydration();
                             this.schedulePoll();
                         }
@@ -297,8 +448,11 @@ class ResilientSubscriptionImpl {
                     }
                     else {
                         // While degraded, an accepted connect is not evidence of anything:
-                        // only bytes downgrade the status back out of 'polling'.
-                        if (!this.degraded) {
+                        // only bytes move the status back out of 'polling'. A synthesized
+                        // snapshot has no 'polling' to hold, and holding it in
+                        // 'reconnecting' would mark a quiet, healthy stream as broken for
+                        // as long as its events are rare, the same case as a first connect.
+                        if (!this.degraded || !this.pollCanDeliver) {
                             this.setStatus('live');
                         }
                         if ((this.binding.config.replay ?? 'untrusted') === 'untrusted') {
@@ -321,6 +475,11 @@ class ResilientSubscriptionImpl {
                 if (this.stopped)
                     return;
                 connectFailed = !this.streamConnected;
+                failure = {
+                    kind: connectFailed ? 'stream-unreachable' : 'stream-silent',
+                    request,
+                    cause: error,
+                };
                 this.diagnostics.onStreamError?.(error);
             }
             finally {
@@ -329,25 +488,38 @@ class ResilientSubscriptionImpl {
                 this.streamConnected = false;
                 this.abortController.signal.removeEventListener('abort', onMasterAbort);
             }
-            if (this.stopped || this.reconciler.isTerminated)
+            if (this.stopped || this.streamAbandoned || this.reconciler.isTerminated)
                 return;
+            if (credentialsRefreshed)
+                continue;
+            // Armed before any status is published below, so a listener that
+            // nudges on 'reconnecting' cuts this backoff short.
+            const backoffWake = new AbortController();
+            this.reconnectBackoffWake = backoffWake;
             // A connection only counts as successful once it has actually carried
             // bytes. A stream that is accepted and then closes immediately would
             // otherwise reset the backoff on every attempt and never degrade,
             // turning a broken upstream into a reconnect-and-poll storm.
+            let countedFailure;
             if (connectFailed || !this.streamProducedBytes) {
                 this.consecutiveConnectFailures += 1;
+                countedFailure = failure ?? { kind: 'stream-silent', request };
+                // Reminders name the cause as it stands now, not the one that degraded it.
+                if (this.reportedDegradation)
+                    this.reportedDegradation.failure = countedFailure;
             }
-            if (this.consecutiveConnectFailures >= this.policy.degradedAfterFailures) {
-                if (!this.degraded) {
-                    this.degraded = true;
-                    this.setStatus('polling');
-                    // Degraded cadence applies from the next deadman arm.
-                    this.armDeadman();
-                }
+            if (!this.degraded && this.consecutiveConnectFailures >= this.policy.degradedAfterFailures) {
+                // The poll this drop needs is scheduled below; the deadman carries
+                // the degraded cadence from its next arm.
+                this.degrade({ forcePoll: false });
+                if (countedFailure)
+                    this.reportDegradation(countedFailure);
             }
             else {
-                this.setStatus('reconnecting');
+                // Already degraded, a drop keeps an endpoint binding on 'polling'. A
+                // synthesized one may have reported 'live' off a quiet reconnect, and
+                // is back to having nothing that covers the outage.
+                this.setStatus(this.degraded && this.pollCanDeliver ? 'polling' : 'reconnecting');
             }
             // The stream just dropped — data may have been lost; poll now.
             this.schedulePoll();
@@ -357,10 +529,116 @@ class ResilientSubscriptionImpl {
             const delay = this.serverRetryHintMs !== undefined && !connectFailed
                 ? this.serverRetryHintMs
                 : backoffDelay(backoffConfig, this.consecutiveConnectFailures, this.random);
-            const proceed = await sleep(delay, this.abortController.signal);
-            if (!proceed)
+            await this.waitOutReconnectBackoff(delay, backoffWake);
+            if (this.stopped)
+                return;
+        }
+    }
+    /**
+     * Sleep out the reconnect backoff, cut short by `stop()` or by `nudge()`.
+     * A nudge ends the wait without stopping anything, so the caller tells the
+     * two apart by `stopped`.
+     */
+    async waitOutReconnectBackoff(delayMs, wake) {
+        const onMasterAbort = () => wake.abort();
+        this.abortController.signal.addEventListener('abort', onMasterAbort, { once: true });
+        try {
+            // A status listener run on the way here may already have stopped it.
+            if (this.stopped)
                 return;
+            await sleep(delayMs, wake.signal);
         }
+        finally {
+            this.reconnectBackoffWake = undefined;
+            this.abortController.signal.removeEventListener('abort', onMasterAbort);
+        }
+    }
+    /**
+     * Give the stream up for the life of the subscription and let the poll
+     * carry it, after a refusal no reconnect can get past.
+     *
+     * One-way, and held in `streamAbandonedValue` rather than in the caller's
+     * `return`: the connect loop tests it, so neither a later edit nor a
+     * throwing hook can put the subscription back on a request the server has
+     * already refused. Re-probing on a timer would win the latency back, at the
+     * cost of turning one refusal into an unbounded retry.
+     *
+     * The poll is forced rather than left to the deadman: under
+     * `initialPoll: 'eager'` the hydration poll is scheduled by an accepted
+     * connect, so a first connect that is refused leaves nothing armed.
+     */
+    abandonStream(refusal) {
+        const { status } = refusal;
+        this.streamAbandonedValue = true;
+        // A retry the STREAM spent on a refresh that worked, only to be refused
+        // anyway, went to a channel that no longer exists. The poll now carries
+        // the subscription alone, so it gets the credit back instead of dying on
+        // a refusal the application was never asked about. A hook that declined
+        // keeps its answer: the poll carries the same credentials, and asking
+        // again would mean a second refresh or login prompt for one outage. A
+        // credit the poll spent stays spent: its own retry is what it bought.
+        if (this.authCredit === 'spent-by-stream')
+            this.authCredit = 'available';
+        const streamWasLive = this.streamEverProducedBytes;
+        this.runListener(() => this.diagnostics.onStreamRefused?.({ status, streamWasLive }), undefined);
+        // The hook may have stopped the subscription; a stopped one must not be
+        // put back into 'polling'.
+        if (this.stopped || this.reconciler.isTerminated)
+            return;
+        this.degrade({ forcePoll: true });
+        this.reportDegradation(refusal);
+    }
+    /**
+     * Report that the stream broke and the subscription runs without it, then
+     * keep reporting on `degradationReportIntervalMs` until it recovers.
+     *
+     * One report per degradation would not be enough: a tab that degraded an
+     * hour ago looks, in an error tracker, like a fault that went away. A new
+     * cause (a refusal after a run of silent connects) is reported at once.
+     */
+    reportDegradation(failure) {
+        if (this.stopped || this.reconciler.isTerminated)
+            return;
+        const current = this.reportedDegradation;
+        this.reportedDegradation = {
+            failure,
+            streamWasLive: this.streamEverProducedBytes,
+            since: current?.since ?? Date.now(),
+            reports: current?.reports ?? 0,
+        };
+        this.emitDegradation();
+    }
+    emitDegradation() {
+        const degradation = this.reportedDegradation;
+        if (!degradation || this.stopped || this.reconciler.isTerminated)
+            return;
+        degradation.reports += 1;
+        const { failure } = degradation;
+        const error = new FallbackDegradedError({
+            ...failure,
+            streamWasLive: degradation.streamWasLive,
+            pollCarriesDelivery: this.pollCanDeliver,
+            reportCount: degradation.reports,
+            degradedForMs: Date.now() - degradation.since,
+        });
+        this.runListener(() => this.diagnostics.onDegraded?.(error), undefined);
+        if (this.stopped)
+            return;
+        const interval = this.policy.degradationReportIntervalMs;
+        if (interval !== 'off')
+            this.degradationReminder.arm(interval);
+    }
+    endDegradation() {
+        const degradation = this.reportedDegradation;
+        if (!degradation)
+            return;
+        this.reportedDegradation = undefined;
+        this.degradationReminder.clear();
+        const recovery = {
+            kind: degradation.failure.kind,
+            degradedForMs: Date.now() - degradation.since,
+        };
+        this.runListener(() => this.diagnostics.onRecovered?.(recovery), undefined);
     }
     consumeStream(response) {
         this.streamConnected = true;
@@ -426,12 +704,17 @@ class ResilientSubscriptionImpl {
         if (this.streamProducedBytes)
             return;
         this.streamProducedBytes = true;
+        this.streamEverProducedBytes = true;
         // The stream is demonstrably working — clear the failure history and
         // leave degraded mode. Doing this here rather than at connect keeps a
         // connect-then-close loop counted as the failure it is.
         this.consecutiveConnectFailures = 0;
-        this.authRetrySpent = false;
+        this.authCredit = 'available';
         this.degraded = false;
+        this.endDegradation();
+        // `onRecovered` may have stopped the subscription, which must stay 'stopped'.
+        if (this.stopped)
+            return;
         // Bytes on the wire are the only evidence that delivery works, so they are
         // what promotes the subscription to 'live' — from degraded polling, and
         // equally from the 'connecting' a byte-less stream is parked in after
@@ -441,6 +724,11 @@ class ResilientSubscriptionImpl {
         if (!this.reconciler.isHydrating) {
             this.setStatus('live');
         }
+        for (const listener of this.establishedListeners) {
+            if (this.stopped)
+                return;
+            this.runListener(listener, undefined);
+        }
     }
     /**
      * Move the reconnect cursor to where this frame leaves it.
@@ -499,8 +787,10 @@ class ResilientSubscriptionImpl {
         // every 15s polled between nearly every pair of events, forever, while a
         // fully idle one backed off to `deadmanIdleBackoff.maxMs`. A poll that
         // does find news still resets it, in `executePoll`.
-        if (outcome.deliveries.length > 0)
+        if (outcome.deliveries.length > 0) {
+            this.streamDeliveries += 1;
             this.armDeadman();
+        }
         if (outcome.duplicate) {
             this.diagnostics.onDuplicate?.(parsed.event ?? 'message');
         }
@@ -555,7 +845,39 @@ class ResilientSubscriptionImpl {
     // --------------------------------------------------------------------
     // Polling
     // --------------------------------------------------------------------
+    /**
+     * Enter the degraded state, from wherever the subscription came:
+     * `mode: 'poll-only'` at construction, enough consecutive connect failures,
+     * or a stream given up on a refusal. It caps the reconnect backoff and
+     * stops an accepted-but-silent connect from claiming `'live'`.
+     *
+     * With a synthesized snapshot it stops there. `'polling'` would name a
+     * channel that delivers nothing, so the status stays `'reconnecting'`: the
+     * stream being down IS the outage, and nothing covers it.
+     *
+     * `forcePoll` polls now instead of waiting for the deadman, which the
+     * callers with nothing else armed depend on.
+     */
+    degrade(opts) {
+        this.degraded = true;
+        if (!this.pollCanDeliver) {
+            this.setStatus('reconnecting');
+            return;
+        }
+        this.setStatus('polling');
+        if (opts.forcePoll) {
+            this.schedulePoll();
+        }
+        else {
+            this.armDeadman();
+        }
+    }
     schedulePoll() {
+        // A synthesized snapshot has no news in it: every caller here (hydration,
+        // the deadman, a gap repair, a dropped stream, `nudge`) is asking for
+        // reconciliation that only the stream can provide.
+        if (!this.pollCanDeliver)
+            return;
         if (this.stopped || this.reconciler.isTerminated)
             return;
         if (this.pollInFlight) {
@@ -594,11 +916,17 @@ class ResilientSubscriptionImpl {
                 if (this.stopped || this.reconciler.isTerminated)
                     return;
             }
-            const response = await this.transport.fetchSnapshot(this.binding.buildSnapshotRequest(this.params), { signal: pollAbort.signal });
+            const request = this.binding.buildSnapshotRequest(this.params);
+            const streamDeliveriesAtRequest = this.streamDeliveries;
+            const response = await this.transport.fetchSnapshot(request, { signal: pollAbort.signal });
             if (this.stopped || this.reconciler.isTerminated)
                 return;
             if (response.status < 200 || response.status >= 300) {
-                this.diagnostics.onPollError?.(new Error(`Snapshot poll failed with status ${response.status}`));
+                this.diagnostics.onPollError?.(new FallbackHttpError(`Snapshot poll failed with status ${response.status}`, {
+                    channel: 'poll',
+                    status: response.status,
+                    request,
+                }));
                 if (this.policy.unretryableStatuses.includes(response.status)) {
                     const recovered = await this.tryAuthChallenge(response.status, 'poll');
                     if (this.stopped || this.reconciler.isTerminated)
@@ -620,7 +948,14 @@ class ResilientSubscriptionImpl {
                 return;
             }
             this.pollFailures = 0;
-            this.authRetrySpent = false;
+            this.authCredit = 'available';
+            if (this.isSupersededByStream(streamDeliveriesAtRequest)) {
+                // Asked again rather than dropped: this may be the poll repairing an
+                // outage, and a fresh one reads a state at least as new as the event.
+                this.diagnostics.onStaleSnapshot?.();
+                this.pollQueued = true;
+                return;
+            }
             const outcome = this.reconciler.handleSnapshot(response.body);
             if (outcome.stale) {
                 this.diagnostics.onStaleSnapshot?.();
@@ -671,6 +1006,25 @@ class ResilientSubscriptionImpl {
             }
         }
     }
+    /**
+     * Whether a versionless snapshot was overtaken by the stream while it was
+     * in flight. Its body may predate the pushed event, and with no version to
+     * compare, delivering it would overwrite newer news with older.
+     */
+    isSupersededByStream(streamDeliveriesAtRequest) {
+        if (this.binding.config.version !== 'none')
+            return false;
+        if (this.streamDeliveries === streamDeliveriesAtRequest) {
+            this.supersededPolls = 0;
+            return false;
+        }
+        if (this.supersededPolls >= MAX_SUPERSEDED_POLLS) {
+            this.supersededPolls = 0;
+            return false;
+        }
+        this.supersededPolls += 1;
+        return true;
+    }
     /**
      * Offer an auth refusal to the application once, so an expired token can be
      * refreshed instead of killing the subscription.
@@ -693,17 +1047,22 @@ class ResilientSubscriptionImpl {
         const inFlight = this.authRefresh;
         if (inFlight)
             return await inFlight;
-        if (this.authRetrySpent)
+        if (this.authCredit !== 'available')
             return false;
-        this.authRetrySpent = true;
+        const spent = channel === 'stream' ? 'spent-by-stream' : 'spent-by-poll';
+        this.authCredit = spent;
         const refresh = (async () => {
+            let recovered = false;
             try {
-                return (await onAuthChallenge({ status, channel })) === true;
+                recovered = (await onAuthChallenge({ status, channel })) === true;
             }
             catch (error) {
                 this.diagnostics.onListenerError?.(error);
-                return false;
             }
+            // A request that succeeded meanwhile already started a new streak.
+            if (!recovered && this.authCredit === spent)
+                this.authCredit = 'declined';
+            return recovered;
         })();
         this.authRefresh = refresh;
         try {
@@ -711,7 +1070,7 @@ class ResilientSubscriptionImpl {
         }
         finally {
             // Only a refusal AFTER this refresh completed counts as the second
-            // failure, which is what `authRetrySpent` now gates.
+            // failure, which is what `authCredit` now gates.
             if (this.authRefresh === refresh)
                 this.authRefresh = undefined;
         }
@@ -758,6 +1117,8 @@ class ResilientSubscriptionImpl {
         return this.streamConnected ? 'connecting' : 'reconnecting';
     }
     armDeadman() {
+        if (!this.pollCanDeliver)
+            return;
         if (this.stopped || this.reconciler.isTerminated)
             return;
         if (this.degraded) {
@@ -849,6 +1210,20 @@ class ResilientSubscriptionImpl {
         });
     }
 }
+/**
+ * Reject the combinations that could only ever deliver nothing, at
+ * construction rather than as a subscription that looks alive.
+ */
+function assertPolicySuitsBinding(snapshotSource, policy) {
+    if (snapshotSource === 'endpoint')
+        return;
+    if (policy.mode === 'poll-only') {
+        throw new Error("mode: 'poll-only' requires snapshotSource: 'endpoint'. A synthesized snapshot is answered without asking the server, so a subscription that never opens a stream could not deliver anything.");
+    }
+    if (policy.streamRefusal === 'keep-polling') {
+        throw new Error("streamRefusal: 'keep-polling' requires snapshotSource: 'endpoint'. A synthesized snapshot is answered without asking the server, so polling on after a refused stream would report a healthy subscription that delivers nothing.");
+    }
+}
 /**
  * Create a resilient subscription: SSE as the low-latency channel, short
  * polls as the correctness backbone. See the package README for the state
@@ -864,7 +1239,11 @@ export function createResilientSubscription(binding, options) {
         get status() {
             return impl.status;
         },
+        get streamAbandoned() {
+            return impl.streamAbandoned;
+        },
         onStatusChange: (listener) => impl.onStatusChange(listener),
+        onStreamEstablished: (listener) => impl.onStreamEstablished(listener),
         get result() {
             return impl.result;
         },