@ultimat3/core 29.4.0 → 30.0.0

package/src/retry.ts

@@ -1,165 +1,67 @@
-// Single responsibility: run work again, on the framework's own terms. The executor
-// `error-retry.ts` never had — that module declares `terminal | retryable | retry-after` and
-// nothing in the tree consulted it before deciding to try again, so four packages each shipped
-// their own loop and only `@ultimat3/jobs`' asked the classification at all.
+// Single responsibility: run work again, on the framework's own terms AND within its caller's
+// lifetime. The executor `error-retry.ts` never had — that module declares `terminal | retryable |
+// retry-after` and nothing in the tree consulted it before deciding to try again, so four packages
+// each shipped their own loop and only `@ultimat3/jobs`' asked the classification at all.
 
-import {
-  type BackoffCurve,
-  backoffDelay,
-  type JitterMode,
-  jitterStatedDelay,
-  type Random,
-} from './backoff';
-import { systemClock } from './clock';
-import { classifyThrown, type ErrorRetry, statedDelayMs } from './error-retry';
-import { finiteCount, finiteOption } from './finite-option';
-
-export interface RetryPolicy {
-  /** Total attempts INCLUDING the first. `attempts: 1` means no retry. */
-  readonly attempts: number;
-  /** The first delay, in ms. */
-  readonly base: number;
-  /**
-   * Ceiling for any single delay, in ms. A `retry-after` the responder named is clamped to it
-   * too, and then gets its spread on top — at most half again, so a burst told one delay does
-   * not wake together (`jitterStatedDelay`).
-   */
-  readonly max: number;
-  /**
-   * Required, unlike `backoffDelay`'s, and that is the point: a retry loop with no jitter is the
-   * thundering herd itself, so the mode is a decision each caller makes rather than one it can
-   * inherit without noticing.
-   */
-  readonly jitter: JitterMode;
-  readonly curve?: BackoffCurve | undefined;
-  readonly factor?: number | undefined;
-  /**
-   * Wall-clock budget for the WHOLE loop, waits included. A wait that would end past it is never
-   * started — the caller's own deadline outranks the attempts it was allowed.
-   */
-  readonly timeBudgetMs?: number | undefined;
-}
+import type { Random } from './backoff';
+import type { Ctx } from './context';
+import { tryUseContext } from './context';
+import type { RetryPolicy } from './retry-loop';
+import { retryLoop } from './retry-loop';
 
 export interface RetryDeps {
-  /** Injected so a retry schedule is provable without waiting for one. */
-  sleep(ms: number): Promise<void>;
-  /** Monotonic ms, read only when `timeBudgetMs` is set. Defaults to the system clock. */
+  /** Injected so a retry schedule is provable without waiting for one. Defaults to a timer. */
+  sleep?: ((ms: number) => Promise<void>) | undefined;
+  /** Monotonic ms, read only when a time budget applies. Defaults to the system clock. */
   now?: (() => number) | undefined;
   random?: Random | undefined;
 }
 
-/** Why the loop stopped. Absent while it is still retrying. */
-export type RetryStopReason = 'terminal' | 'attempts-exhausted' | 'budget-exhausted';
-
-export interface RetryDecision {
-  readonly retry: boolean;
-  readonly delayMs: number;
-  readonly attempt: number;
-  readonly nextAttempt: number;
-  /** The classification consulted, or `undefined` when nobody classified the thrown code. */
-  readonly classification: ErrorRetry | undefined;
-  readonly stoppedBy: RetryStopReason | undefined;
-}
+/** A timer an abort lets go of, so a retry abandoned mid-wait holds nothing for the full delay. */
+const abortableTimer = (ms: number, signal: AbortSignal | undefined): Promise<void> =>
+  new Promise<void>((done) => {
+    const finish = (): void => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', finish);
+      done();
+    };
+    const timer = setTimeout(finish, ms);
+    signal?.addEventListener('abort', finish, { once: true });
+  });
 
 /**
- * Retry, stop, and when — pure, so a caller can print the schedule and a test can pin it without a
- * loop. `terminal` stops on the attempt that failed: the same code run again is the same answer,
- * and the attempts left are a queue slot, a provider bill, or three more wrong passwords at a site
- * that locks the account after three. Everything else keeps the attempt count in charge, and
- * `retry-after` replaces only the DELAY, never the ceiling.
+ * The request's deadline as the loop's budget, when it is the tighter of the two. Not
+ * `remainingBudgetMs`: that answers `undefined` for a spent budget as well as for no deadline,
+ * which is right for a header and here would lift the bound exactly when it has run out.
  */
-export function retryDecision(
-  policy: RetryPolicy,
-  attempt: number,
-  error: unknown,
-  random?: Random,
-): RetryDecision {
-  // Screened HERE and not only in `retry()`: this function is exported so a caller can write its
-  // own loop, and `attempt >= NaN` is false for every attempt — the loop that asks it never ends.
-  const attempts = finiteCount('a retry policy', 'attempts', policy.attempts);
-  const classification = classifyThrown(error);
-  const stop = (stoppedBy: RetryStopReason): RetryDecision => ({
-    retry: false,
-    delayMs: 0,
-    attempt,
-    nextAttempt: attempt,
-    classification,
-    stoppedBy,
-  });
-
-  if (classification === 'terminal') return stop('terminal');
-  if (attempt >= attempts) return stop('attempts-exhausted');
-
-  const computed = backoffDelay({
-    attempt,
-    base: policy.base,
-    max: policy.max,
-    factor: policy.factor,
-    curve: policy.curve,
-    jitter: policy.jitter,
-    random,
-  });
-  const stated = classification === 'retry-after' ? statedDelayMs(error) : undefined;
-  return {
-    retry: true,
-    // The stated delay is a FLOOR plus a spread (`jitterStatedDelay`), never the bare number: a
-    // shedding server tells a whole burst `Retry-After: 1`, and waiting exactly that replays the
-    // burst in lockstep every second. The floor is clamped by the policy's own ceiling, which is
-    // what `max` is for — a responder naming a day is still a responder this deployment has not
-    // agreed to wait a day for — and the spread on top is at most half of it.
-    // `jitter: 'none'` is honoured here too — the caller's one decision, for a test or a printable
-    // schedule — and only that mode gets the bare floor.
-    delayMs:
-      stated === undefined
-        ? computed
-        : policy.jitter === 'none'
-          ? Math.min(stated, policy.max)
-          : jitterStatedDelay(Math.min(stated, policy.max), policy.max, random),
-    attempt,
-    nextAttempt: attempt + 1,
-    classification,
-    stoppedBy: undefined,
-  };
+function withinDeadline(policy: RetryPolicy, ctx: Ctx | undefined): RetryPolicy {
+  if (ctx === undefined || ctx.deadlineAt === null) return policy;
+  const left = ctx.deadlineAt - ctx.now().getTime();
+  const timeBudgetMs =
+    policy.timeBudgetMs === undefined ? left : Math.min(policy.timeBudgetMs, left);
+  return { ...policy, timeBudgetMs };
 }
 
 /**
- * Run `work` until it succeeds, the policy runs out, the classification says stop, or the time
- * budget does. `work` is handed the 1-based attempt number.
+ * Run `work` until it succeeds, the policy runs out, the classification says stop, the time budget
+ * does, or the ambient caller is gone. Ambient and not an option, because a required `signal` is
+ * the argument an agent forgets, and after the budget a forgotten one keeps sending to a vendor.
  *
- * The LAST error reaches the caller unchanged — never wrapped. An `UltimateError` carries a code, a
- * cause and a runnable `fix:`, and a wrapper would replace all three with the fact that something
- * was retried, which no reader can act on.
+ * The one place a retry loop meets its caller's lifetime. Work that must outlive its caller runs
+ * inside `runToCompletion(fn)`, where the signal is live and the deadline null, so nothing clamps;
+ * `retry()` has no opt-out of its own. The last error, or the signal's reason when no attempt ran,
+ * reaches the caller unchanged.
  */
 export async function retry<T>(
   work: (attempt: number) => Promise<T>,
   policy: RetryPolicy,
-  deps: RetryDeps,
+  deps: RetryDeps = {},
 ): Promise<T> {
-  // Both bounds are refused BEFORE the first try: a policy that cannot stop the loop is a defect in
-  // the call, and running the work once first would report it as the work's own failure.
-  // `finiteOption` for the budget, not `finiteCount`: it is a duration a caller computes from a
-  // monotonic clock, so a fraction is real and a spent (negative) one means "do not wait at all".
-  // Zero stays legal and means what it always did — one try, no retry (`retry.test.ts` pins it).
-  finiteCount('a retry policy', 'attempts', policy.attempts);
-  const budget =
-    policy.timeBudgetMs === undefined
-      ? undefined
-      : finiteOption('a retry policy', 'timeBudgetMs', policy.timeBudgetMs);
-  const now = deps.now ?? ((): number => systemClock.monotonic());
-  // Read once even when no budget is set: a clock call per attempt would be a cost the common case
-  // does not owe. `startedAt` is only compared against when `timeBudgetMs` is present.
-  const startedAt = now();
-
-  for (let attempt = 1; ; attempt += 1) {
-    try {
-      return await work(attempt);
-    } catch (error) {
-      const decision = retryDecision(policy, attempt, error, deps.random);
-      if (!decision.retry) throw error;
-      // Decided BEFORE the wait, never after: a loop that sleeps and then discovers it is out of
-      // budget has already spent the caller's deadline on a wait nobody could use.
-      if (budget !== undefined && now() - startedAt + decision.delayMs > budget) throw error;
-      await deps.sleep(decision.delayMs);
-    }
-  }
+  const ctx = tryUseContext();
+  return await retryLoop(work, withinDeadline(policy, ctx), {
+    sleep: deps.sleep ?? abortableTimer,
+    now: deps.now,
+    random: deps.random,
+    signal: ctx?.signal,
+  });
 }

package/src/roles.ts

@@ -13,7 +13,7 @@ export const DEFAULT_ROLE: Role = 'web';
 export type ScalingSignal =
   | 'rps'
   | 'ws-connections'
-  | 'queue-depth'
+  | 'queue-demand'
   | 'singleton'
   | 'run-once'
   | 'per-database';
@@ -29,7 +29,7 @@ export interface RoleInfo {
 export const ROLE_INFO = Object.freeze<Record<Role, RoleInfo>>({
   web: { role: 'web', scalesOn: 'rps', maxReplicas: null, stateful: false },
   sync: { role: 'sync', scalesOn: 'ws-connections', maxReplicas: null, stateful: false },
-  worker: { role: 'worker', scalesOn: 'queue-depth', maxReplicas: null, stateful: false },
+  worker: { role: 'worker', scalesOn: 'queue-demand', maxReplicas: null, stateful: false },
   scheduler: { role: 'scheduler', scalesOn: 'singleton', maxReplicas: 1, stateful: false },
   migrate: { role: 'migrate', scalesOn: 'run-once', maxReplicas: 1, stateful: false },
   replicator: { role: 'replicator', scalesOn: 'per-database', maxReplicas: 1, stateful: true },

package/src/route-path-merge.ts

@@ -0,0 +1,55 @@
+// Single responsibility: the URL's `:param` values merged into a request's input, and the one
+// refusal when the two disagree (`X_HTTP_PATH_INPUT_CONFLICT`). Server-side only: the template
+// helpers it reads are `route-path-template.ts`, which a browser client loads without this.
+
+import { UltimateError } from './errors';
+import { templateParams } from './route-path-template';
+
+/**
+ * The URL disagreed with the body (or search string) about one key. Never resolved by letting
+ * either win: a policy reading one id while the handler reads another is the bug this refuses.
+ */
+export class HttpPathInputConflictError extends UltimateError {
+  constructor(input: { readonly owner: string; readonly template: string; readonly key: string }) {
+    super({
+      code: 'X_HTTP_PATH_INPUT_CONFLICT',
+      cause: `${input.owner} is served at ${input.template}, and the request sent ${input.key} both as the URL's :${input.key} and, with a different value, in its body or query string`,
+      fix: `{} — the body (or query string) without ${input.key}: the URL already carries it; or send the identical value in both`,
+      meta: { key: input.key, path: input.template },
+    });
+  }
+}
+
+/**
+ * The input `invoke`/`runQuery` parses: the template's params, taken from the router's DECODED
+ * `params`, merged into `raw`. A key both carry must agree exactly, else
+ * `X_HTTP_PATH_INPUT_CONFLICT`. A `raw` that is not a keyed object is handed on untouched — the
+ * input's own schema refuses it with the code every surface answers.
+ */
+export function mergePathParams(input: {
+  readonly owner: string;
+  readonly template: string;
+  readonly params: Readonly<Record<string, string>>;
+  readonly raw: unknown;
+}): unknown {
+  const names = templateParams(input.template);
+  if (names.length === 0) return input.raw;
+  const { raw } = input;
+  if (raw !== undefined && raw !== null && (typeof raw !== 'object' || Array.isArray(raw))) {
+    return raw;
+  }
+  const fields: Record<string, unknown> = { ...(raw ?? {}) };
+  for (const name of names) {
+    const fromUrl = input.params[name];
+    if (fromUrl === undefined) continue;
+    if (Object.hasOwn(fields, name) && fields[name] !== fromUrl) {
+      throw new HttpPathInputConflictError({
+        owner: input.owner,
+        template: input.template,
+        key: name,
+      });
+    }
+    fields[name] = fromUrl;
+  }
+  return fields;
+}

package/src/route-path-template.ts

@@ -0,0 +1,124 @@
+// Single responsibility: an `http.path` TEMPLATE (`/orders/:id/refund`) — shape, params, the input
+// keys they must name, filling, OpenAPI spelling. Here because `@ultimat3/action` and `@ultimat3/query`
+// share a tier. Imports nothing, so a browser client fills a URL without an error class; the merge
+// and its refusal are `route-path-merge.ts`.
+
+/** Lowercase static segments or `:camelName` params; no wildcard, no trailing slash. */
+const PATH_TEMPLATE = /^(\/([a-z0-9][a-z0-9._~-]*|:[a-z][A-Za-z0-9]*))+$/;
+
+/**
+ * Why `path` cannot be a pin, or `undefined` when it can. A reason, not a throw: each package
+ * refuses with its own code (`X_ACTION_HTTP_PATH_INVALID`, `X_QUERY_HTTP_PATH_INVALID`).
+ */
+export function pathTemplateProblem(path: unknown): string | undefined {
+  if (typeof path !== 'string') return 'is not a string';
+  // Before the pattern, which refuses `_` too: the namespace is the reason a reader can act on.
+  if (path === '/_x' || path.startsWith('/_x/')) return 'claims /_x, the framework namespace';
+  if (!PATH_TEMPLATE.test(path)) {
+    return 'is not a lowercase path of static segments and :camelCase params (an uppercase letter, a *wildcard or a trailing slash)';
+  }
+  const seen = new Set<string>();
+  for (const param of templateParams(path)) {
+    if (seen.has(param)) return `repeats :${param}, and one URL cannot carry two values for it`;
+    seen.add(param);
+  }
+  return undefined;
+}
+
+/** `/orgs/:orgId/posts/:postId` → `['orgId', 'postId']`, in order. */
+export function templateParams(path: string): readonly string[] {
+  return path
+    .split('/')
+    .filter((segment) => segment.startsWith(':'))
+    .map((segment) => segment.slice(1));
+}
+
+/** `:id` → `{id}`: OpenAPI's spelling of the same template. A static path is unchanged. */
+export function toOpenApiPath(path: string): string {
+  return path.replace(/:([a-z][A-Za-z0-9]*)/g, '{$1}');
+}
+
+/** The slice of an introspected input member the key rule reads — `@ultimat3/schema`'s node. */
+export interface TemplateKeyNode {
+  readonly kind?: string;
+  readonly optional?: boolean | undefined;
+  readonly hasDefault?: boolean | undefined;
+}
+
+/**
+ * Why `params` cannot be filled from an input with these top-level `properties`, or `undefined`.
+ * Every param must be a REQUIRED string key: the value is merged into the input before it is
+ * parsed, so the input's own schema validates it — an optional key would be a URL with a hole.
+ */
+export function templateKeyProblem(
+  params: readonly string[],
+  properties: Readonly<Record<string, TemplateKeyNode>> | undefined,
+): string | undefined {
+  if (params.length === 0) return undefined;
+  if (properties === undefined) {
+    return 'names a :param, and input: cannot be introspected to prove it carries that key';
+  }
+  for (const param of params) {
+    const node = Object.hasOwn(properties, param) ? properties[param] : undefined;
+    if (node === undefined) return `names :${param}, which is not a key of input:`;
+    if (node.kind !== 'string') return `names :${param}, whose input: member is not a string`;
+    if (node.optional === true || node.hasDefault === true) {
+      return `names :${param}, whose input: member is optional — a URL cannot omit a segment`;
+    }
+  }
+  return undefined;
+}
+
+export type FilledTemplate =
+  | { readonly ok: true; readonly path: string }
+  | {
+      readonly ok: false;
+      /** The `:param` that could not be filled. */
+      readonly missing: string;
+      /** Why, as a phrase that follows the param's name: `:id <reason>`. */
+      readonly reason: string;
+    };
+
+/**
+ * `.` and `..` survive `encodeURIComponent` untouched, and a URL resolver (`fetch`, `new URL`)
+ * walks them — `/posts/../edit` is `/edit` — as it does their `%2E` spellings, so no encoding
+ * keeps one inside its segment. Refused, never sent.
+ */
+const DOT_SEGMENTS: ReadonlySet<string> = new Set(['.', '..']);
+
+/**
+ * The template with every `:param` replaced by `input[param]`, `encodeURIComponent`-ed so a `/` in
+ * a value stays inside its one segment — the router decodes it back into the same one param.
+ * A missing, empty or non-string value, or a dot-segment, is named rather than spelled into a
+ * different URL.
+ */
+export function fillTemplate(path: string, input: unknown): FilledTemplate {
+  const values = typeof input === 'object' && input !== null ? input : {};
+  const out: string[] = [];
+  for (const segment of path.split('/')) {
+    if (!segment.startsWith(':')) {
+      out.push(segment);
+      continue;
+    }
+    const name = segment.slice(1);
+    const value = Object.hasOwn(values, name)
+      ? (values as Record<string, unknown>)[name]
+      : undefined;
+    if (typeof value !== 'string' || value === '') {
+      return {
+        ok: false,
+        missing: name,
+        reason: 'needs a non-empty string, and the input has none',
+      };
+    }
+    if (DOT_SEGMENTS.has(value)) {
+      return {
+        ok: false,
+        missing: name,
+        reason: `is '${value}', a dot-segment the URL resolver would walk out of its one segment`,
+      };
+    }
+    out.push(encodeURIComponent(value));
+  }
+  return { ok: true, path: out.join('/') };
+}

package/src/runtime-metrics.ts

@@ -17,7 +17,9 @@ import type { ScalingSignal } from './roles';
 export const SCALING_METRICS = Object.freeze<Record<ScalingSignal, string | null>>({
   rps: 'http_requests_total',
   'ws-connections': 'connections',
-  'queue-depth': 'queue_depth',
+  // Not `queue_depth`, the backlog: ready-only, it reads 0 while a fleet holds every job it has, and
+  // the HPA shrinks the fleet mid-job. `queue_demand` is held plus due (`@ultimat3/jobs`'s gauge).
+  'queue-demand': 'queue_demand',
   singleton: null,
   'run-once': null,
   'per-database': null,
@@ -99,3 +101,16 @@ export function recordJob(queue: string, outcome: 'ok' | 'failed' | 'dead'): voi
 export function recordLeaseLost(queue: string): void {
   leasesLost.add(1, { queue });
 }
+
+export const breakerTransitions: Counter = counter('breaker_transitions_total', {
+  unit: '{transition}',
+  description: 'Circuit breaker state changes, by breaker name and the state entered',
+});
+
+/**
+ * One per state change of a `breaker()`, called only by `breaker.ts`. `name` is a label the app
+ * chose in code (bounded), never a tenant or a URL, so the series count is the breaker count × 3.
+ */
+export function recordBreakerTransition(name: string, to: 'closed' | 'open' | 'half-open'): void {
+  breakerTransitions.add(1, { name, to });
+}

package/src/same-origin.ts

@@ -6,6 +6,9 @@
 /** The complete `Sec-Fetch-Site` vocabulary. Anything else was written by a non-browser. */
 const KNOWN_SITES = new Set(['same-origin', 'same-site', 'cross-site', 'none']);
 
+/** What `Origin` carries, and `URL.origin` answers, when there is no origin to name. */
+const OPAQUE_ORIGIN = 'null';
+
 export interface OriginEvidence {
   /** The origins this app is reached on. More than one when the scheme is not knowable here. */
   readonly selfOrigins: readonly string[];
@@ -27,13 +30,20 @@ export type OriginVerdict =
  * `Origin` second, so an app that lists a sibling origin keeps working. `same-site` is NOT proof:
  * a sibling subdomain is same-site, and a `SameSite=Lax` cookie rides its requests. A request with
  * neither header is refused — "we could not tell" is the case this exists for.
+ *
+ * `Origin: null` matches nothing, whatever a list holds: a sandboxed iframe, a `data:` page and a
+ * cross-origin redirect all send it, so it names everybody. It reaches a list by accident too —
+ * `URL.parse('localhost:3000').origin` is that same string.
  */
 export function proveSameOrigin(evidence: OriginEvidence): OriginVerdict {
   const site = evidence.secFetchSite;
   if (site === 'same-origin' || site === 'none') return { ok: true };
   const origin = evidence.origin;
-  if (origin !== null && evidence.selfOrigins.includes(origin)) return { ok: true };
-  if (origin !== null && evidence.listed(origin)) return { ok: true };
+  const opaque = origin === OPAQUE_ORIGIN;
+  if (origin !== null && !opaque) {
+    if (evidence.selfOrigins.includes(origin)) return { ok: true };
+    if (evidence.listed(origin)) return { ok: true };
+  }
   // Only the four values a browser can send are quoted back. Anything else is a client that
   // wrote the header itself, and echoing what it wrote is how a rejected value reaches the log
   // store and the response body.
@@ -41,6 +51,12 @@ export function proveSameOrigin(evidence: OriginEvidence): OriginVerdict {
     const known = KNOWN_SITES.has(site) ? site : 'a value no browser sends';
     return { ok: false, reason: `the request reported sec-fetch-site: ${known}` };
   }
+  if (opaque) {
+    return {
+      ok: false,
+      reason: 'the request declared the opaque origin null, which no list can vouch for',
+    };
+  }
   return {
     ok: false,
     reason:

package/src/session-lost.ts

@@ -0,0 +1,115 @@
+/**
+ * "This page's session is gone", said once. A tab past its session otherwise asks for a 401
+ * forever; every poll and every scheduled refresh reads this one flag and stops. The flag lives on
+ * the page handle (`record-sink.ts`) because every island chunk carries its own copy of core.
+ */
+
+import { onRescope } from './client-scope';
+import { sessionLostCell } from './record-sink';
+
+/** The two codes that mean the credential this page was rendered with no longer resolves. */
+const LOSS_CODES: ReadonlySet<string> = new Set(['X_UNAUTHENTICATED', 'X_SESSION_EXPIRED']);
+
+/** Whether a refusal has said this page's session is gone. `rescope()` clears it. */
+export function sessionIsLost(): boolean {
+  return sessionLostCell().lost;
+}
+
+/**
+ * Called once per page when the session is lost; at once for a subscriber that arrives after.
+ * Returns the unsubscribe. The sign-in UI is the app's: the framework says "lost", nothing more.
+ */
+export function onSessionLost(fn: () => void): () => void {
+  const cell = sessionLostCell();
+  if (cell.lost) {
+    fn();
+    return (): void => {};
+  }
+  // Wrapped, so one function subscribed twice is two subscriptions with two unsubscribes.
+  const entry = (): void => fn();
+  cell.listeners.add(entry);
+  return (): void => {
+    cell.listeners.delete(entry);
+  };
+}
+
+/**
+ * Internal, the pollers': `start` runs while the page holds a session — now, unless it is already
+ * lost — and its returned stop is called on a loss. The next rescope to a signed-in principal
+ * starts it again, fresh: a poll stopped by a 401 is not one stopped for good once the visitor
+ * signs back in. A rescope to `null` keeps waiting, since an anonymous page's 401 never stops it.
+ * Returns the idempotent disposer, which stops a running `start` too.
+ */
+export function whileSessionHeld(start: () => () => void): () => void {
+  let stopRun: (() => void) | undefined;
+  let offLost = (): void => {};
+  let disposed = false;
+  const pause = (): void => {
+    const stop = stopRun;
+    stopRun = undefined;
+    stop?.();
+  };
+  const begin = (): void => {
+    stopRun = start();
+    offLost = onSessionLost(pause);
+  };
+  const offScope = onRescope((next) => {
+    if (stopRun === undefined && typeof next.principal === 'string') begin();
+  });
+  if (!sessionIsLost()) begin();
+  return (): void => {
+    if (disposed) return;
+    disposed = true;
+    offScope();
+    offLost();
+    pause();
+  };
+}
+
+/** The refusal as `client-dispatch.ts` saw it: the answer's status, its URL and its code. */
+export interface Refusal {
+  readonly status: number;
+  readonly url: string;
+  readonly code: string;
+}
+
+/**
+ * Internal, `client-dispatch.ts`'s: a refusal answered to a page acting for `principal`. Only a
+ * page that HAD a principal can lose one — an anonymous page's 401 is a wrong password — and only
+ * a 401 from this page's own origin speaks for the cookie it was rendered with: another origin's
+ * 401 is about that origin's credential.
+ */
+export function noteRefusal(refusal: Refusal, principal: string | null | undefined): void {
+  if (typeof principal !== 'string' || refusal.status !== 401) return;
+  if (!LOSS_CODES.has(refusal.code) || !isPageOrigin(refusal.url)) return;
+  const cell = sessionLostCell();
+  if (cell.lost) return;
+  cell.lost = true;
+  const listeners = [...cell.listeners];
+  cell.listeners.clear();
+  for (const listener of listeners) {
+    try {
+      listener();
+    } catch (error) {
+      // Re-raised off this stack: the caller is mid-refusal, and a listener's bug must neither
+      // replace that refusal nor silence the listeners after it. The page's error hook sees it.
+      queueMicrotask(() => {
+        throw error;
+      });
+    }
+  }
+}
+
+/** Stands in for the page's origin where there is none (a server, a test): only a relative URL is. */
+const NO_ORIGIN = 'http://page-origin.invalid';
+
+/** Whether `url` resolves to the page's origin; relative URLs always do. */
+function isPageOrigin(url: string): boolean {
+  const location: unknown = Reflect.get(globalThis, 'location');
+  const stated =
+    typeof location === 'object' && location !== null ? Reflect.get(location, 'origin') : undefined;
+  // `'null'` is an opaque origin (a sandboxed frame): no absolute URL can match it.
+  const base = typeof stated === 'string' && stated !== 'null' ? stated : NO_ORIGIN;
+  if (!URL.canParse(url, base)) return false;
+  return new URL(url, base).origin === new URL(base).origin;
+}