@estiva-app/platform 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @estiva-app/platform
 
+## 0.4.0
+
+One read a tab holds on to, and reads again when it fails (FOL-5). Additive.
+
+`createRetryingRead` is Peek's FOL-42 `useFolders` without React or a relay:
+a failure is read again on a backoff (5 s doubling to 60 s, or the relay's own
+`retry in Ns` for a quota refusal), a failure never replaces a good answer, and
+the answer is held past the component that asked. Ship's Folder listing read
+once and turned one failure into an empty list for the session, which dropped
+every project out of its team until a reload.
+
+- `createRetryingRead<T>({ retryable?, firstRetryMs?, maxRetryMs?, freshMs?, now?, timers? })`
+  → `{ snapshot, subscribe, ensure(load), reload(load), dispose, clear }`.
+  Wrap it with `useSyncExternalStore(read.subscribe, read.snapshot)`. Retries
+  run only while something is subscribed; `clear()` forgets the answer, and a
+  read in flight across it writes nothing.
+- `retryDelayMs(failures, error)`, `RETRY_FIRST_MS`, `RETRY_MAX_MS`.
+
 ## 0.3.1
 
 Subscribers on one interval share one timer (PER-6). No API change.

package/dist/index.d.ts

@@ -22,5 +22,6 @@
 export { MAX_FOLDERS_PER_SUBSCRIPTION, createLiveClient, createLiveClientHolder, type FolderWatch, type LiveClient, type LiveClientHolder, type LiveClientObservers, type LiveClientOptions, } from './live-client.js';
 export { createFolderActivity, type FolderActivity, type FolderListener, } from './folder-activity.js';
 export { assumeOnline, browserOnlineSource, type OnlineSource, type OnlineTarget } from './online.js';
+export { RETRY_FIRST_MS, RETRY_MAX_MS, createRetryingRead, retryDelayMs, type RetryTimers, type RetryingRead, type RetryingReadOptions, type RetryingReadSnapshot, } from './retrying-read.js';
 export { DEFAULT_BACKOFF_MS, DEFAULT_MERGE_MS, MIN_BACKOFF_MS, createRefreshScheduler, createRelayBudget, isRateLimited, retryHintMs, type BudgetChannel, type FocusTarget, type RefreshScheduler, type RefreshSchedulerOptions, type RefreshSubscription, type RelayBudget, type RelayBudgetOptions, type SchedulerClock, type VisibilityTarget, } from './refresh.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,4BAA4B,EAC5B,gBAAgB,EAChB,sBAAsB,EACtB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AACrG,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,4BAA4B,EAC5B,gBAAgB,EAChB,sBAAsB,EACtB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AACrG,OAAO,EACL,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -22,5 +22,6 @@
 export { MAX_FOLDERS_PER_SUBSCRIPTION, createLiveClient, createLiveClientHolder, } from './live-client.js';
 export { createFolderActivity, } from './folder-activity.js';
 export { assumeOnline, browserOnlineSource } from './online.js';
+export { RETRY_FIRST_MS, RETRY_MAX_MS, createRetryingRead, retryDelayMs, } from './retrying-read.js';
 export { DEFAULT_BACKOFF_MS, DEFAULT_MERGE_MS, MIN_BACKOFF_MS, createRefreshScheduler, createRelayBudget, isRateLimited, retryHintMs, } from './refresh.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,4BAA4B,EAC5B,gBAAgB,EAChB,sBAAsB,GAMvB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,oBAAoB,GAGrB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAwC,MAAM,aAAa,CAAA;AACrG,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACb,WAAW,GAUZ,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,4BAA4B,EAC5B,gBAAgB,EAChB,sBAAsB,GAMvB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,oBAAoB,GAGrB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAwC,MAAM,aAAa,CAAA;AACrG,OAAO,EACL,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,YAAY,GAKb,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACb,WAAW,GAUZ,MAAM,cAAc,CAAA"}

package/dist/retrying-read.d.ts

@@ -0,0 +1,62 @@
+/** The first wait before reading a failed read again. Peek's `FOLDERS_RETRY_FIRST_MS`. */
+export declare const RETRY_FIRST_MS = 5000;
+/** The longest wait between re-reads while a read keeps failing. */
+export declare const RETRY_MAX_MS = 60000;
+/** Declared here because this package compiles with neither the DOM nor the Node lib. */
+export interface RetryTimers {
+    setTimeout(run: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export interface RetryingReadOptions {
+    /**
+     * Whether this failure could answer differently next time. Default: every
+     * failure is. A caller that can tell a refusal (`not_a_member`, `refused`)
+     * from an outage says so, and the refusal is not asked again.
+     */
+    retryable?: (error: unknown) => boolean;
+    firstRetryMs?: number;
+    maxRetryMs?: number;
+    /**
+     * How long an answer is fresh enough that {@link RetryingRead.ensure} does
+     * not ask again. Default: for ever — read once per tab, which is what a
+     * navigation listing wants; {@link RetryingRead.reload} always asks.
+     */
+    freshMs?: number;
+    now?: () => number;
+    /** Looked up on every call when absent, so a test's fake timers apply. */
+    timers?: RetryTimers;
+}
+/** Replaced, never mutated: a stable snapshot for `useSyncExternalStore` between changes. */
+export interface RetryingReadSnapshot<T> {
+    /** The last answer, once any read has succeeded. */
+    value?: T;
+    /** Why the last read failed — only while there is no value to keep. */
+    error?: unknown;
+    /** A re-read is scheduled: a failure shown now is not the final word. */
+    retrying: boolean;
+}
+export interface RetryingRead<T> {
+    snapshot(): RetryingReadSnapshot<T>;
+    subscribe(listener: () => void): () => void;
+    /**
+     * Read, unless an answer fresher than `freshMs` is held, a read is in
+     * flight, or a retry is already scheduled. What a mount calls.
+     *
+     * Retries run only while something is subscribed: the last unsubscribe
+     * cancels a scheduled one, and the next `ensure` reads in its place.
+     */
+    ensure(load: () => Promise<T>): Promise<void>;
+    /** Read now, whatever is held; a scheduled retry is replaced by this read. */
+    reload(load: () => Promise<T>): Promise<void>;
+    /** Cancel a scheduled retry. The held answer stays. */
+    dispose(): void;
+    /**
+     * Forget everything held — for a new viewer, or between test cases. A read
+     * in flight across it neither writes its answer nor schedules a retry.
+     */
+    clear(): void;
+}
+/** The wait before the next attempt, after `failures` consecutive retryable failures. */
+export declare function retryDelayMs(failures: number, error: unknown, first?: number, max?: number): number;
+export declare function createRetryingRead<T>(options?: RetryingReadOptions): RetryingRead<T>;
+//# sourceMappingURL=retrying-read.d.ts.map

package/dist/retrying-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrying-read.d.ts","sourceRoot":"","sources":["../src/retrying-read.ts"],"names":[],"mappings":"AA2BA,0FAA0F;AAC1F,eAAO,MAAM,cAAc,OAAQ,CAAA;AACnC,oEAAoE;AACpE,eAAO,MAAM,YAAY,QAAS,CAAA;AAElC,yFAAyF;AACzF,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,GAAG,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;IAChD,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAA;CACpC;AAID,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;IACvC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,6FAA6F;AAC7F,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,oDAAoD;IACpD,KAAK,CAAC,EAAE,CAAC,CAAA;IACT,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,yEAAyE;IACzE,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,QAAQ,IAAI,oBAAoB,CAAC,CAAC,CAAC,CAAA;IACnC,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IAC3C;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C,8EAA8E;IAC9E,MAAM,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C,uDAAuD;IACvD,OAAO,IAAI,IAAI,CAAA;IACf;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAA;CACd;AAED,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,SAAiB,EAAE,GAAG,SAAe,GAAG,MAAM,CAOjH;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,GAAE,mBAAwB,GAAG,YAAY,CAAC,CAAC,CAAC,CA2FxF"}

package/dist/retrying-read.js

@@ -0,0 +1,141 @@
+/**
+ * One read a tab holds on to, and reads again when it fails (FOL-5).
+ *
+ * Came from Peek's `useFolders` (FOL-42), which Ship needed word for word.
+ * Ship's read the Folder listing once and turned a failure into an empty list
+ * for the rest of the session: on production one refused read dropped every
+ * project out of its team until a reload. Peek had already paid for that
+ * lesson — a refused read left a project's channel unplaced and its team's dot
+ * dark — and fixed it with three rules, which are the whole of this object:
+ *
+ * 1. **A failure is read again**, on a backoff from `firstRetryMs` doubling to
+ *    `maxRetryMs`, until one succeeds. A quota refusal waits the relay's own
+ *    stated time instead ({@link retryHintMs}), never less than
+ *    {@link MIN_BACKOFF_MS}. A failure the caller says will answer the same
+ *    way (`retryable`) is not retried.
+ * 2. **A failure never replaces a good answer.** The last value stays; the
+ *    failure is reported only while there is nothing else to show.
+ * 3. **Held past the component that asked.** Every page mounts its own
+ *    sidebar; one of these per tab means a page change draws the answer the
+ *    tab already has rather than a skeleton (Peek's SID-2).
+ *
+ * No React, no relay: the app hands in the read and wraps the object in its
+ * own hook — `useSyncExternalStore(read.subscribe, read.snapshot)` — so the
+ * package stays framework-free (ADR 0002 §10), as `createRefreshScheduler` is.
+ */
+import { MIN_BACKOFF_MS, isRateLimited, retryHintMs } from './refresh.js';
+/** The first wait before reading a failed read again. Peek's `FOLDERS_RETRY_FIRST_MS`. */
+export const RETRY_FIRST_MS = 5_000;
+/** The longest wait between re-reads while a read keeps failing. */
+export const RETRY_MAX_MS = 60_000;
+const host = globalThis;
+/** The wait before the next attempt, after `failures` consecutive retryable failures. */
+export function retryDelayMs(failures, error, first = RETRY_FIRST_MS, max = RETRY_MAX_MS) {
+    const text = error instanceof Error ? error.message : String(error);
+    if (isRateLimited(text)) {
+        const hint = retryHintMs(text);
+        if (hint !== undefined)
+            return Math.max(MIN_BACKOFF_MS, hint);
+    }
+    return Math.min(first * 2 ** Math.max(0, failures - 1), max);
+}
+export function createRetryingRead(options = {}) {
+    const retryable = options.retryable ?? (() => true);
+    const first = options.firstRetryMs ?? RETRY_FIRST_MS;
+    const max = options.maxRetryMs ?? RETRY_MAX_MS;
+    const freshMs = options.freshMs ?? Number.POSITIVE_INFINITY;
+    // Taken when the object is made, as Peek's listing cache did: freshness is
+    // wall-clock, and a test's fake `Date` must not make a held answer look
+    // fresh (or stale) to the next test. Pass `now` to control it.
+    const now = options.now ?? Date.now;
+    const timers = () => options.timers ?? host;
+    let snapshot = { retrying: false };
+    let answeredAt = 0;
+    let failures = 0;
+    let inflight;
+    let timer;
+    const listeners = new Set();
+    const set = (next) => {
+        snapshot = next;
+        for (const listener of [...listeners])
+            listener();
+    };
+    const cancel = () => {
+        if (timer === undefined)
+            return;
+        timers().clearTimeout(timer);
+        timer = undefined;
+    };
+    /* Bumped by `clear`, so a read in flight across it cannot write the old
+       answer back or schedule a retry for it. */
+    let generation = 0;
+    const run = (load) => {
+        if (inflight)
+            return inflight;
+        cancel();
+        const started = generation;
+        inflight = (async () => {
+            try {
+                const value = await load();
+                if (started !== generation)
+                    return;
+                failures = 0;
+                answeredAt = now();
+                set({ value, retrying: false });
+            }
+            catch (error) {
+                if (started !== generation)
+                    return;
+                const again = retryable(error);
+                if (again) {
+                    failures += 1;
+                    timer = timers().setTimeout(() => {
+                        timer = undefined;
+                        void run(load);
+                    }, retryDelayMs(failures, error, first, max));
+                }
+                // A good answer outlives any failure after it.
+                set(snapshot.value !== undefined ? { value: snapshot.value, retrying: again } : { error, retrying: again });
+            }
+            finally {
+                if (started === generation)
+                    inflight = undefined;
+            }
+        })();
+        return inflight;
+    };
+    return {
+        snapshot: () => snapshot,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+                // Nobody is looking: a retry would spend the relay's budget on an
+                // answer no one draws. The snapshot still says a retry is due, and
+                // the next `ensure` makes it.
+                if (listeners.size === 0)
+                    cancel();
+            };
+        },
+        ensure(load) {
+            if (inflight)
+                return inflight;
+            if (timer !== undefined)
+                return Promise.resolve();
+            if (snapshot.value !== undefined && now() - answeredAt < freshMs)
+                return Promise.resolve();
+            return run(load);
+        },
+        reload: run,
+        dispose: cancel,
+        clear() {
+            generation += 1;
+            cancel();
+            inflight = undefined;
+            failures = 0;
+            answeredAt = 0;
+            set({ retrying: false });
+        },
+    };
+}
+//# sourceMappingURL=retrying-read.js.map

package/dist/retrying-read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrying-read.js","sourceRoot":"","sources":["../src/retrying-read.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/platform",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Browser lifecycle two Estiva apps share: the one live relay socket a tab should hold, its credential read per connect, the network coming back, and when a tab re-reads.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -35,6 +35,16 @@ export {
   type FolderListener,
 } from './folder-activity.js'
 export { assumeOnline, browserOnlineSource, type OnlineSource, type OnlineTarget } from './online.js'
+export {
+  RETRY_FIRST_MS,
+  RETRY_MAX_MS,
+  createRetryingRead,
+  retryDelayMs,
+  type RetryTimers,
+  type RetryingRead,
+  type RetryingReadOptions,
+  type RetryingReadSnapshot,
+} from './retrying-read.js'
 export {
   DEFAULT_BACKOFF_MS,
   DEFAULT_MERGE_MS,

package/src/retrying-read.ts

@@ -0,0 +1,194 @@
+/**
+ * One read a tab holds on to, and reads again when it fails (FOL-5).
+ *
+ * Came from Peek's `useFolders` (FOL-42), which Ship needed word for word.
+ * Ship's read the Folder listing once and turned a failure into an empty list
+ * for the rest of the session: on production one refused read dropped every
+ * project out of its team until a reload. Peek had already paid for that
+ * lesson — a refused read left a project's channel unplaced and its team's dot
+ * dark — and fixed it with three rules, which are the whole of this object:
+ *
+ * 1. **A failure is read again**, on a backoff from `firstRetryMs` doubling to
+ *    `maxRetryMs`, until one succeeds. A quota refusal waits the relay's own
+ *    stated time instead ({@link retryHintMs}), never less than
+ *    {@link MIN_BACKOFF_MS}. A failure the caller says will answer the same
+ *    way (`retryable`) is not retried.
+ * 2. **A failure never replaces a good answer.** The last value stays; the
+ *    failure is reported only while there is nothing else to show.
+ * 3. **Held past the component that asked.** Every page mounts its own
+ *    sidebar; one of these per tab means a page change draws the answer the
+ *    tab already has rather than a skeleton (Peek's SID-2).
+ *
+ * No React, no relay: the app hands in the read and wraps the object in its
+ * own hook — `useSyncExternalStore(read.subscribe, read.snapshot)` — so the
+ * package stays framework-free (ADR 0002 §10), as `createRefreshScheduler` is.
+ */
+import { MIN_BACKOFF_MS, isRateLimited, retryHintMs } from './refresh.js'
+
+/** The first wait before reading a failed read again. Peek's `FOLDERS_RETRY_FIRST_MS`. */
+export const RETRY_FIRST_MS = 5_000
+/** The longest wait between re-reads while a read keeps failing. */
+export const RETRY_MAX_MS = 60_000
+
+/** Declared here because this package compiles with neither the DOM nor the Node lib. */
+export interface RetryTimers {
+  setTimeout(run: () => void, ms: number): unknown
+  clearTimeout(handle: unknown): void
+}
+
+const host = globalThis as unknown as RetryTimers
+
+export interface RetryingReadOptions {
+  /**
+   * Whether this failure could answer differently next time. Default: every
+   * failure is. A caller that can tell a refusal (`not_a_member`, `refused`)
+   * from an outage says so, and the refusal is not asked again.
+   */
+  retryable?: (error: unknown) => boolean
+  firstRetryMs?: number
+  maxRetryMs?: number
+  /**
+   * How long an answer is fresh enough that {@link RetryingRead.ensure} does
+   * not ask again. Default: for ever — read once per tab, which is what a
+   * navigation listing wants; {@link RetryingRead.reload} always asks.
+   */
+  freshMs?: number
+  now?: () => number
+  /** Looked up on every call when absent, so a test's fake timers apply. */
+  timers?: RetryTimers
+}
+
+/** Replaced, never mutated: a stable snapshot for `useSyncExternalStore` between changes. */
+export interface RetryingReadSnapshot<T> {
+  /** The last answer, once any read has succeeded. */
+  value?: T
+  /** Why the last read failed — only while there is no value to keep. */
+  error?: unknown
+  /** A re-read is scheduled: a failure shown now is not the final word. */
+  retrying: boolean
+}
+
+export interface RetryingRead<T> {
+  snapshot(): RetryingReadSnapshot<T>
+  subscribe(listener: () => void): () => void
+  /**
+   * Read, unless an answer fresher than `freshMs` is held, a read is in
+   * flight, or a retry is already scheduled. What a mount calls.
+   *
+   * Retries run only while something is subscribed: the last unsubscribe
+   * cancels a scheduled one, and the next `ensure` reads in its place.
+   */
+  ensure(load: () => Promise<T>): Promise<void>
+  /** Read now, whatever is held; a scheduled retry is replaced by this read. */
+  reload(load: () => Promise<T>): Promise<void>
+  /** Cancel a scheduled retry. The held answer stays. */
+  dispose(): void
+  /**
+   * Forget everything held — for a new viewer, or between test cases. A read
+   * in flight across it neither writes its answer nor schedules a retry.
+   */
+  clear(): void
+}
+
+/** The wait before the next attempt, after `failures` consecutive retryable failures. */
+export function retryDelayMs(failures: number, error: unknown, first = RETRY_FIRST_MS, max = RETRY_MAX_MS): number {
+  const text = error instanceof Error ? error.message : String(error)
+  if (isRateLimited(text)) {
+    const hint = retryHintMs(text)
+    if (hint !== undefined) return Math.max(MIN_BACKOFF_MS, hint)
+  }
+  return Math.min(first * 2 ** Math.max(0, failures - 1), max)
+}
+
+export function createRetryingRead<T>(options: RetryingReadOptions = {}): RetryingRead<T> {
+  const retryable = options.retryable ?? (() => true)
+  const first = options.firstRetryMs ?? RETRY_FIRST_MS
+  const max = options.maxRetryMs ?? RETRY_MAX_MS
+  const freshMs = options.freshMs ?? Number.POSITIVE_INFINITY
+  // Taken when the object is made, as Peek's listing cache did: freshness is
+  // wall-clock, and a test's fake `Date` must not make a held answer look
+  // fresh (or stale) to the next test. Pass `now` to control it.
+  const now = options.now ?? Date.now
+  const timers = () => options.timers ?? host
+
+  let snapshot: RetryingReadSnapshot<T> = { retrying: false }
+  let answeredAt = 0
+  let failures = 0
+  let inflight: Promise<void> | undefined
+  let timer: unknown
+  const listeners = new Set<() => void>()
+
+  const set = (next: RetryingReadSnapshot<T>) => {
+    snapshot = next
+    for (const listener of [...listeners]) listener()
+  }
+  const cancel = () => {
+    if (timer === undefined) return
+    timers().clearTimeout(timer)
+    timer = undefined
+  }
+
+  /* Bumped by `clear`, so a read in flight across it cannot write the old
+     answer back or schedule a retry for it. */
+  let generation = 0
+
+  const run = (load: () => Promise<T>): Promise<void> => {
+    if (inflight) return inflight
+    cancel()
+    const started = generation
+    inflight = (async () => {
+      try {
+        const value = await load()
+        if (started !== generation) return
+        failures = 0
+        answeredAt = now()
+        set({ value, retrying: false })
+      } catch (error: unknown) {
+        if (started !== generation) return
+        const again = retryable(error)
+        if (again) {
+          failures += 1
+          timer = timers().setTimeout(() => {
+            timer = undefined
+            void run(load)
+          }, retryDelayMs(failures, error, first, max))
+        }
+        // A good answer outlives any failure after it.
+        set(snapshot.value !== undefined ? { value: snapshot.value, retrying: again } : { error, retrying: again })
+      } finally {
+        if (started === generation) inflight = undefined
+      }
+    })()
+    return inflight
+  }
+
+  return {
+    snapshot: () => snapshot,
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+        // Nobody is looking: a retry would spend the relay's budget on an
+        // answer no one draws. The snapshot still says a retry is due, and
+        // the next `ensure` makes it.
+        if (listeners.size === 0) cancel()
+      }
+    },
+    ensure(load) {
+      if (inflight) return inflight
+      if (timer !== undefined) return Promise.resolve()
+      if (snapshot.value !== undefined && now() - answeredAt < freshMs) return Promise.resolve()
+      return run(load)
+    },
+    reload: run,
+    dispose: cancel,
+    clear() {
+      generation += 1
+      cancel()
+      inflight = undefined
+      failures = 0
+      answeredAt = 0
+      set({ retrying: false })
+    },
+  }
+}