@ultimat3/http 30.8.0 → 31.0.0

package/src/index.ts

@@ -41,35 +41,17 @@ export {
   useRequestHeaders,
   withAnonymousRequest,
 } from './context';
-export type { InboundCorrelation } from './correlation';
 export type { CorsConfig } from './cors';
-export { allowedOrigin, corsHeaders, DEFAULT_CORS, originListed, preflight } from './cors';
+export { allowedOrigin, DEFAULT_CORS, originListed, preflight } from './cors';
 export type { CsrfCheckInput, CsrfConfig, CsrfMode, CsrfVerdict } from './csrf';
 export { checkCsrf, csrfBlocked, selfOrigin } from './csrf';
 export type { Deadline } from './deadline';
 export { resolveTimeoutMs, startDeadline } from './deadline';
 export type { ErrorFacts, ProblemDocument } from './error-facts';
-export {
-  factsOf,
-  problemTypeFor,
-  renderErrorLines,
-  retryAfterOf,
-  toProblem,
-} from './error-facts';
+export { factsOf, problemTypeFor, renderErrorLines, retryAfterOf, toProblem } from './error-facts';
 export { ERROR_STATUS } from './error-map';
-export type {
-  ErrorPageAction,
-  ErrorPageCopy,
-  ErrorPageGroup,
-  ErrorPageInput,
-  ErrorPageOptions,
-} from './error-page';
-export {
-  ERROR_PAGE_LINKS,
-  errorPageResponse,
-  renderErrorPage,
-  resolveErrorPageCopy,
-} from './error-page';
+export type { ErrorPageInput } from './error-page';
+export { ERROR_PAGE_LINKS, renderErrorPage } from './error-page';
 export {
   DEFAULT_STATUS,
   declaredStatusFor,
@@ -79,11 +61,9 @@ export {
 } from './error-status';
 export type { HttpErrorCode } from './errors';
 export {
-  bearerMountInvalid,
   bodyInvalid,
   buildSkew,
   draining,
-  errorStatusInvalid,
   finalizeFailed,
   forbidden,
   HTTP_ERROR_CODES,
@@ -92,30 +72,21 @@ export {
   methodNotAllowed,
   noRequest,
   overloaded,
-  pathInvalid,
-  pipelineNoResponse,
   requestTimedOut,
-  routeCacheInvalid,
-  routeConflict,
   routeNotFound,
-  serverNotStarted,
-  trustProxyUnset,
   unauthenticated,
-  webhookSignatureInvalid,
-  webhookSignatureStale,
 } from './errors';
 export type { ForwardedInput, ForwardedSplit } from './forwarded';
+export { clientAddress, forwardedElement } from './forwarded';
+export type { Authenticator, AuthenticatorOptions, AuthzDecision, ServerHooks } from './hooks';
 export {
-  clientAddress,
-  forwardedElement,
-} from './forwarded';
-export type { Authenticator, AuthzDecision, ServerHooks } from './hooks';
-export { configureAuthenticator, configuredAuthenticator, resetAuthenticator } from './hooks';
-export {
-  BUN_MAX_IDLE_TIMEOUT_S,
-  IDLE_TIMEOUT_MARGIN_S,
-  socketIdleTimeoutSeconds,
-} from './idle-timeout';
+  configureAuthenticator,
+  configuredAuthenticator,
+  configuredCredentialTtlMs,
+  MAX_CREDENTIAL_TTL_MS,
+  resetAuthenticator,
+} from './hooks';
+export { socketIdleTimeoutSeconds } from './idle-timeout';
 export type { LocaleConfig, TimeZoneConfig } from './locale';
 export { DEFAULT_LOCALE_CONFIG, DEFAULT_TZ_CONFIG } from './locale';
 export type { RequestAddress } from './locale-prefix';
@@ -137,13 +108,12 @@ export type {
   ServableObject,
 } from './object-response';
 export { notModified, objectResponse } from './object-response';
-export type { OverlayMeta, OverlayNotice } from './overlay';
-export { overlayResponse, wantsOverlay } from './overlay';
+export type { OverlayNotice } from './overlay';
+export { wantsOverlay } from './overlay';
 export { OVERLAY_STYLE } from './overlay-style';
 export type { PeerIdentity } from './peer-identity';
-export { peerIdentity } from './peer-identity';
 export type { HandleInit, Pipeline, PipelineDeps } from './pipeline';
-export { httpPipeline, PIPELINE_STAGES } from './pipeline';
+export { httpPipeline, PIPELINE_STAGES, REQUEST_ID_ATTRIBUTE } from './pipeline';
 export type { ProblemMeta, ProblemMetaDeclaration, ProblemMetaValue } from './problem-meta';
 export { MAX_PROBLEM_META_BYTES, registerProblemMeta } from './problem-meta';
 export type {
@@ -151,7 +121,6 @@ export type {
   MemoryRateLimitStore,
   RateLimitConfig,
   RateLimitDecision,
-  RateLimitDeclaration,
   RateLimiter,
   RateLimitKeyParts,
   RateLimitScope,
@@ -161,42 +130,27 @@ export type {
 export {
   assertRateLimitScope,
   DEFAULT_MAX_RATE_LIMIT_KEYS,
-  DEFAULT_RATE_LIMIT,
   memoryRateLimitStore,
   rateLimitDecision,
   rateLimiter,
   rateLimitSpends,
-  resolveRateLimitConfig,
-  toBucket,
 } from './rate-limit';
 export { assertRouteBuckets, withRouteBuckets } from './rate-limit-buckets';
-export {
-  rateLimitBucketConflict,
-  rateLimitBucketUnbound,
-  rateLimited,
-  rateLimitInvalid,
-  rateLimitNotShared,
-  rateLimitScopeUnset,
-  rateLimitStoreUnavailable,
-  tenantBucketUnknown,
-} from './rate-limit-errors';
+export type { RateLimitDeclaration } from './rate-limit-config';
+export { DEFAULT_RATE_LIMIT, resolveRateLimitConfig, toBucket } from './rate-limit-config';
+export { rateLimited, rateLimitInvalid } from './rate-limit-errors';
 export { publishRateLimit, rateLimitHeaders } from './rate-limit-headers';
-export type { AdoptRateLimitStoreOptions } from './rate-limit-installed';
-export {
-  adoptRateLimitStore,
-  assertInstalledRateLimitScope,
-  installedRateLimitStore,
-  installRateLimitStore,
-  resetRateLimitStore,
-  withScratchRateLimitStore,
-} from './rate-limit-installed';
+export { assertInstalledRateLimitScope, installedRateLimitStore } from './rate-limit-installed';
 export type { RateLimitPeek } from './rate-limit-peek';
 export { rateLimitPeek, refilledTokens } from './rate-limit-peek';
 export type { PostgresRateLimitStore, PostgresRateLimitStoreOptions } from './rate-limit-postgres';
-export {
-  postgresRateLimitStore,
-  SQL_RATE_LIMIT_TABLE,
-} from './rate-limit-postgres';
+export { postgresRateLimitStore, SQL_RATE_LIMIT_TABLE } from './rate-limit-postgres';
+export type {
+  RedisRateLimitClient,
+  RedisRateLimitStore,
+  RedisRateLimitStoreOptions,
+} from './rate-limit-redis';
+export { redisRateLimitStore } from './rate-limit-redis';
 export { RATE_LIMIT_STORE_DEADLINE_MS } from './rate-limit-store-deadline';
 export { setRedirect, takeRedirect } from './redirect';
 export type { QueryValues } from './request';
@@ -212,7 +166,6 @@ export {
   html,
   jsonResponse,
   NO_STORE,
-  noContent,
   problem,
   redirect,
   stream,
@@ -231,12 +184,7 @@ export type {
   RouteParams,
   RouteTable,
 } from './router';
-export {
-  describeRoutes,
-  HTTP_METHODS,
-  httpRouter,
-  matchRoute,
-} from './router';
+export { describeRoutes, httpRouter, matchRoute } from './router';
 export type { SecurityConfig } from './security-headers';
 export { buildCsp, cspHashSource, DEFAULT_SECURITY, securityHeaders } from './security-headers';
 export type {
@@ -258,9 +206,6 @@ export { formatIssue, validateBody, validateSync } from './validate';
 export type { BodyHmacOptions, VerifiedBody } from './webhook-hmac';
 export { verifyBodyHmac } from './webhook-hmac';
 export type { VerifiedWebhook, WebhookVerifyOptions } from './webhook-verify';
-export {
-  DEFAULT_WEBHOOK_BODY_LIMIT,
-  DEFAULT_WEBHOOK_TOLERANCE_MS,
-  verifyWebhookSignature,
-} from './webhook-verify';
-export { type JoinedWebSocketMounts, joinWebSocketMounts } from './websocket-mounts';
+export { DEFAULT_WEBHOOK_BODY_LIMIT, verifyWebhookSignature } from './webhook-verify';
+export type { JoinedWebSocketMounts } from './websocket-mounts';
+export { joinWebSocketMounts } from './websocket-mounts';

package/src/locale.ts

@@ -4,7 +4,7 @@
 // lived here and all three disagreed with their owner about the same request.
 
 import { LOCALE_COOKIE } from '@ultimat3/i18n';
-import { TIMEZONE_DETECTED_COOKIE, TIMEZONE_HEADER } from '@ultimat3/time';
+import { TIMEZONE_COOKIE, TIMEZONE_DETECTED_COOKIE, TIMEZONE_HEADER } from '@ultimat3/time';
 
 export interface LocaleConfig {
   /** Cookie the client sets when the user picks a locale explicitly. */
@@ -32,6 +32,6 @@ export const DEFAULT_LOCALE_CONFIG: LocaleConfig = {
 /** The default zone is `configureTime({ defaultZone })`'s, so a process has one answer, not two. */
 export const DEFAULT_TZ_CONFIG: TimeZoneConfig = {
   header: TIMEZONE_HEADER,
-  cookie: 'x_timezone',
+  cookie: TIMEZONE_COOKIE,
   detectedCookie: TIMEZONE_DETECTED_COOKIE,
 };

package/src/pipeline.ts

@@ -3,7 +3,15 @@
 // middleware stack, so nothing can skip a stage and `/_x` and `pipeline.test.ts` can both read it.
 // The other two thirds of the lifecycle are siblings: `stages.ts` owns what each stage does, and
 // `finalize.ts` owns the promise that the tail always answers rather than rejecting.
-import { beginWork, recordRequest, runWithContext, withSpan } from '@ultimat3/core';
+import {
+  beginWork,
+  instrument,
+  recordRequest,
+  runWithContext,
+  SEMCONV,
+  subscribed,
+  withSpan,
+} from '@ultimat3/core';
 import { defineHttpConfig, type HttpConfig } from './config';
 import { asCtx, elapsedMs, type RequestContext, requestContext } from './context';
 import { readCorrelation } from './correlation';
@@ -115,8 +123,8 @@ export interface PipelineDeps {
   readonly hooks?: ServerHooks;
   readonly middleware?: readonly Middleware[];
   /**
-   * A limiter built elsewhere — `httpServer({ rateLimitStore })` is the one supported way, and
-   * it hands over a limiter built from the SAME merged config this constructor would have built.
+   * A limiter built elsewhere — `httpServer` is the one supported way, and it hands over a
+   * limiter over the INSTALLED store built from the SAME merged config this constructor would.
    * One passed from anywhere else resolves bucket names against the table IT closed over, which
    * is why `assertRouteBuckets` compares that table against the routes' declarations and refuses
    * a limiter that cannot enforce one (`X_RATE_LIMIT_BUCKET_UNBOUND`) rather than letting the
@@ -141,6 +149,9 @@ export interface Pipeline {
   handle(request: Request, init: HandleInit): Promise<Response>;
 }
 
+/** The request span's id attribute: framework-specific, so `ultimate.*` — `x dev` joins on it. */
+export const REQUEST_ID_ATTRIBUTE = 'ultimate.request_id';
+
 export const httpPipeline = (deps: PipelineDeps): Pipeline => {
   // Routes first, config second, and the merge here: `defineHttpConfig` cannot see a route, so a
   // bucket a route declares only becomes real at the construction that holds both. Idempotent, so
@@ -294,23 +305,29 @@ export const httpPipeline = (deps: PipelineDeps): Pipeline => {
             // rejection nothing here predicted still counts, at the 500 such a request gets from
             // the caller either way.
             let status = 500;
+            let failure: { readonly error: unknown } | undefined;
             try {
               const response = await execute(request, ctx, deadline);
               status = response.status;
               span.updateName(routeSpanName(ctx.method, ctx.route?.path));
               // The root span of every request carried no attributes at all, so an exporter got a
               // name and a duration and nothing to correlate: which request, which outcome. These
-              // four are what a reader joins on — `x-request-id` off the response, the status the
-              // client saw, and the method/path split out of the span name.
+              // are what a reader joins on — `x-request-id` off the response, the status the client
+              // saw, and the method/route split out of the span name. OpenTelemetry's STABLE http server names (v31). `url.path` is deliberately absent:
+              // it is the concrete path, and a capability URL (`/r/<token>`) would put the token
+              // in every trace store this span is exported to — `http.route` carries the pattern.
               span.setAttributes({
-                'http.request_id': ctx.requestId,
-                'http.method': ctx.method,
-                // The PATTERN (`/r/:token`), the OpenTelemetry meaning of `http.route` — the
-                // concrete path leaked every token a URL carries into the trace store.
-                'http.route': ctx.route?.path ?? UNMATCHED_ROUTE,
-                'http.status_code': response.status,
+                [REQUEST_ID_ATTRIBUTE]: ctx.requestId,
+                [SEMCONV.httpRequestMethod]: ctx.method,
+                [SEMCONV.httpRoute]: ctx.route?.path ?? UNMATCHED_ROUTE,
+                [SEMCONV.httpResponseStatusCode]: response.status,
+                [SEMCONV.urlScheme]: ctx.https ? 'https' : 'http',
+                [SEMCONV.serverAddress]: url.hostname,
               });
               return response;
+            } catch (error) {
+              failure = { error };
+              throw error;
             } finally {
               // The route PATTERN (`/posts/:id`), exactly as the span above is named: a metric is
               // a stored series per label set, and a concrete path is attacker-chosen and may
@@ -325,6 +342,18 @@ export const httpPipeline = (deps: PipelineDeps): Pipeline => {
               // A live timer keeps the event loop from going idle, so a process that answered
               // every request would still refuse to exit for the length of one timeout.
               deadline.clear();
+              // The bus event, last so a throwing (strict) subscriber cannot leak the timer. Every
+              // request, sampled or not — the span reaches an exporter only when sampled. `route`
+              // is the PATTERN, or `undefined` when nothing matched.
+              if (subscribed('http.request')) {
+                instrument('http.request', {
+                  method: ctx.method,
+                  route: ctx.route?.path,
+                  status,
+                  durationMs: elapsedMs(ctx),
+                  ...failure,
+                });
+              }
             }
           },
           {

package/src/problem-meta.ts

@@ -41,13 +41,14 @@ export type ProblemMeta = Readonly<Record<string, ProblemMetaValue>>;
 export const MAX_PROBLEM_META_BYTES = 4096;
 
 /**
- * A key is spelled the way a code's `meta` key is spelled in source. `issues` is refused by name
- * because it already has a top-level home (`ProblemDocument.issues`, parsed and bounded on its
- * own terms), and a second copy under `meta.issues` is two places for a client to read one fact.
+ * A key is spelled the way a code's `meta` key is spelled in source. `issues` and `issuesTruncated`
+ * are refused by name because each already has a top-level home (`ProblemDocument.issues`, parsed
+ * and bounded on its own terms, and the mark that qualifies it), and a second copy under `meta` is
+ * two places for a client to read one fact.
  * `__proto__` is refused because `JSON.parse` on the receiving side mints it as a real own key.
  */
 const KEY = /^[A-Za-z_$][\w$]*$/;
-const RESERVED_KEYS: ReadonlySet<string> = new Set(['issues', '__proto__']);
+const RESERVED_KEYS: ReadonlySet<string> = new Set(['issues', 'issuesTruncated', '__proto__']);
 
 /**
  * Why `key` may not ride a document, or `undefined` when it may. The one rule for both halves: an
@@ -56,7 +57,9 @@ const RESERVED_KEYS: ReadonlySet<string> = new Set(['issues', '__proto__']);
 export function metaKeyRefusal(key: unknown): string | undefined {
   if (typeof key !== 'string' || !KEY.test(key))
     return `${renderCauseValue(key)} is not a meta key`;
-  if (key === 'issues') return '`issues` already rides at the top level of the document';
+  if (key === 'issues' || key === 'issuesTruncated') {
+    return `\`${key}\` already rides at the top level of the document`;
+  }
   if (RESERVED_KEYS.has(key)) return `\`${key}\` is not a key a document may carry`;
   return undefined;
 }

package/src/rate-limit-buckets.ts

@@ -15,6 +15,17 @@ import type { Route } from './router';
 const same = (a: Bucket, b: Bucket): boolean =>
   a.capacity === b.capacity && a.refillPerSecond === b.refillPerSecond;
 
+/**
+ * A bucket table is indexed by an author-written name, so it is read through `Object.hasOwn` and
+ * written through `defineProperty` — the same rule `rateLimiter`'s `declared` reads by. Plain
+ * `[name]` answers `Object` for 'constructor', and `[name] =` makes '__proto__' the prototype.
+ */
+const own = (
+  table: Readonly<Record<string, Bucket>> | undefined,
+  name: string,
+): Bucket | undefined =>
+  table !== undefined && Object.hasOwn(table, name) ? table[name] : undefined;
+
 /**
  * The config with every route-declared bucket registered under the name that route selects.
  *
@@ -55,7 +66,7 @@ export const withRouteBuckets = (config: HttpConfig, routes: readonly Route[]):
     // Numbers with no name to file them under enforce nothing; `toRoute` always sets both.
     if (bucket === undefined || name === undefined) continue;
     const prior = declared.get(name);
-    const configured = config.rateLimit.buckets[name];
+    const configured = own(config.rateLimit.buckets, name);
     if (prior !== undefined && !same(prior.bucket, bucket)) {
       throw rateLimitBucketConflict({
         bucket: name,
@@ -78,7 +89,14 @@ export const withRouteBuckets = (config: HttpConfig, routes: readonly Route[]):
   }
   if (declared.size === 0) return config;
   const buckets: Record<string, Bucket> = { ...config.rateLimit.buckets };
-  for (const [name, entry] of declared) buckets[name] = entry.bucket;
+  for (const [name, entry] of declared) {
+    Object.defineProperty(buckets, name, {
+      value: entry.bucket,
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  }
   return { ...config, rateLimit: { ...config.rateLimit, buckets } };
 };
 
@@ -98,7 +116,7 @@ export const assertRouteBuckets = (limiter: RateLimiter, routes: readonly Route[
     const bucket = route.meta.rateLimitBucket;
     const name = route.meta.rateLimit;
     if (bucket === undefined || name === undefined) continue;
-    const found = limiter.buckets?.[name];
+    const found = own(limiter.buckets, name);
     if (found !== undefined && same(found, bucket)) continue;
     throw rateLimitBucketUnbound({
       bucket: name,

package/src/rate-limit-config.ts

@@ -0,0 +1,123 @@
+// The rate limit as DECLARED: the shipped bucket table, the resolver `defineHttpConfig` runs over
+// an app's half, and `toBucket`, the one conversion from `{ limit, windowMs }` to a `Bucket`. Every
+// refusal is raised here, where an author can act on it, never on the first request.
+import { httpCountInvalid } from './errors';
+import type { Bucket, RateLimitConfig } from './rate-limit';
+import { rateLimitInvalid, rateLimitScopeUnset, tenantBucketUnknown } from './rate-limit-errors';
+
+/**
+ * Everything the framework can decide on its own. `scope` is NOT here: one process is the only
+ * thing a framework can promise without being told, and defaulting to it made "we did not ask"
+ * indistinguishable from "the app said one replica" — so the chart's `replicas: 3` enforced every
+ * number three times over, silently, and the boot check that exists for this
+ * (`assertRateLimitScope`) never fired because it only reads a `'shared'` declaration. The
+ * comment that used to sit here was right about the fact and wrong about the conclusion: ask.
+ */
+export const DEFAULT_RATE_LIMIT: Omit<RateLimitConfig, 'scope'> = {
+  enabled: true,
+  defaultBucket: 'default',
+  tenantBucket: null,
+  buckets: {
+    default: { capacity: 120, refillPerSecond: 2 },
+    // Login/signup style endpoints: slow, no burst.
+    auth: { capacity: 10, refillPerSecond: 0.2 },
+    mutation: { capacity: 30, refillPerSecond: 1 },
+  },
+};
+
+/**
+ * `toBucket`'s rule, for a bucket written as numbers: at least one whole request held, and a
+ * finite refill above zero. A refill of 0 never forgets a key — on a shared store one entry held
+ * forever per caller, minted without bound by a caller rotating its IPv6 /64s.
+ */
+const assertBucket = (name: string, bucket: Bucket): void => {
+  if (!Number.isFinite(bucket.capacity) || bucket.capacity < 1) {
+    throw httpCountInvalid(
+      `rateLimit.buckets.${name}.capacity`,
+      bucket.capacity,
+      'a finite number of at least 1 request',
+      `rateLimit: { buckets: { ${name}: { capacity: 10, refillPerSecond: 0.2 } } }`,
+    );
+  }
+  if (!Number.isFinite(bucket.refillPerSecond) || bucket.refillPerSecond <= 0) {
+    throw httpCountInvalid(
+      `rateLimit.buckets.${name}.refillPerSecond`,
+      bucket.refillPerSecond,
+      'a finite number of tokens per second above 0',
+      `rateLimit: { buckets: { ${name}: { capacity: ${String(bucket.capacity)}, refillPerSecond: 0.2 } } }`,
+    );
+  }
+};
+
+/**
+ * `defineHttpConfig`'s one resolver for this slice, so the refusal happens where an author can
+ * act on it rather than at the first request. A limiter that is switched off has nothing to be
+ * wrong about, so `enabled: false` needs no declaration — and reads as `'process'`.
+ */
+export const resolveRateLimitConfig = (
+  input: Partial<RateLimitConfig> | undefined,
+): RateLimitConfig => {
+  const merged = { ...DEFAULT_RATE_LIMIT, ...input };
+  for (const [name, bucket] of Object.entries(merged.buckets)) assertBucket(name, bucket);
+  // Here and not at the first request, for `assertRateLimitScope`'s reason: an unknown name falls
+  // through `bucketFor` to `default`, so a tenant allowance somebody wrote as 5,000 would silently
+  // be the 120-burst read bucket — looser than what the author declared, and invisible.
+  if (merged.tenantBucket !== null && !Object.hasOwn(merged.buckets, merged.tenantBucket)) {
+    throw tenantBucketUnknown(merged.tenantBucket, Object.keys(merged.buckets));
+  }
+  if (input?.scope !== undefined) return { ...merged, scope: input.scope };
+  if (!merged.enabled) return { ...merged, scope: 'process' };
+  throw rateLimitScopeUnset();
+};
+
+/** How a route, an action or a query spells a limit before it becomes a `Bucket`. */
+export interface RateLimitDeclaration {
+  /** The burst a caller may spend at once. */
+  readonly limit: number;
+  /** The window that refills it. */
+  readonly windowMs: number;
+}
+
+/**
+ * `{ limit, windowMs }` as the limiter's own vocabulary: `5 / 600_000ms` is five held, one back
+ * every two minutes. The only conversion between a declaration and the enforcement, so the
+ * numbers an OpenAPI operation publishes and the numbers `withRouteBuckets` registers cannot
+ * drift. It lives HERE, beside `Bucket` and the maths, because `@ultimat3/action` and
+ * `@ultimat3/query` are the same tier and can never import each other — a copy in one of them is
+ * a second answer to "what does this limit mean" for the other.
+ *
+ * **The COMPUTED rate is validated, not just the two declared halves.** The division is where a
+ * pair that reads fine becomes one the limiter cannot run on, in both directions:
+ * `{ limit: Number.MAX_VALUE, windowMs: 1 }` computes to `Infinity` — a bucket that never empties,
+ * which is the same "declared a limit, enforced nothing" as `windowMs: 0` — and a tiny limit over
+ * a huge window underflows to `0`, a bucket that never refills, so the endpoint is closed after
+ * its first burst rather than limited.
+ */
+export const toBucket = (owner: string, declared: RateLimitDeclaration): Bucket => {
+  const refuse = (reason: string): never => {
+    throw rateLimitInvalid({
+      owner,
+      limit: declared.limit,
+      windowMs: declared.windowMs,
+      reason,
+    });
+  };
+  // A capacity under one token cannot admit a single request, so the endpoint is closed, not
+  // limited — a policy's job, never a rate limit's.
+  if (!Number.isFinite(declared.limit) || declared.limit < 1) {
+    refuse('limit must be a finite number of at least 1 request');
+  }
+  if (!Number.isFinite(declared.windowMs) || declared.windowMs <= 0) {
+    refuse('windowMs must be finite and greater than zero');
+  }
+  const refillPerSecond = declared.limit / (declared.windowMs / 1000);
+  // Kept though the two checks above make it unreachable today: with `limit >= 1` and a finite
+  // window the smallest rate is ~5.6e-306, which is normal, not zero. It is the guard that has to
+  // move first if `limit >= 1` is ever relaxed.
+  if (!Number.isFinite(refillPerSecond) || refillPerSecond <= 0) {
+    refuse(
+      `the refill rate it computes to is ${refillPerSecond} per second, which is a bucket that never empties — nothing would be enforced`,
+    );
+  }
+  return { capacity: declared.limit, refillPerSecond };
+};

package/src/rate-limit-degrade.ts

@@ -21,6 +21,7 @@
 import { isUltimateError, logger } from '@ultimat3/core';
 import type { RateLimitStore } from './rate-limit';
 import { memoryRateLimitStore } from './rate-limit';
+import type { SharedStoreOwner } from './rate-limit-store-deadline';
 
 /**
  * Codes `@ultimat3/db` raises when no connection could run the statement at all, and the store's
@@ -64,7 +65,23 @@ export interface DegradedFallback {
  * decision. The warn is throttled on the CALLER's clock — the one every take is measured against —
  * so a frozen test clock and a real one both get one line per window, never one per request.
  */
-export function degradedFallback(): DegradedFallback {
+/** What each shared store's degraded line says is down, and the command that checks it. */
+const degradedLine = (owner: SharedStoreOwner): { readonly cause: string; readonly fix: string } =>
+  owner === 'redisRateLimitStore'
+    ? {
+        cause:
+          'the shared rate-limit store could not reach Redis, so this pod is counting limits in its own memory until it can — each limit is per pod, not per fleet, meanwhile',
+        fix: 'redis-cli -u "$REDIS_URL" PING   # the client reconnects on its own once it answers PONG',
+      }
+    : {
+        cause:
+          'the shared rate-limit store could not reach the database, so this pod is counting limits in its own memory until it can — each limit is per pod, not per fleet, meanwhile',
+        fix: 'x doctor --json   # names the database binding this pod cannot reach',
+      };
+
+export function degradedFallback(
+  owner: SharedStoreOwner = 'postgresRateLimitStore',
+): DegradedFallback {
   const store = memoryRateLimitStore();
   let lastWarnMs: number | undefined;
   return {
@@ -74,9 +91,7 @@ export function degradedFallback(): DegradedFallback {
       lastWarnMs = nowMs;
       logger.warn('http.rate_limit.degraded', {
         code: isUltimateError(error) ? error.code : 'unknown',
-        cause:
-          'the shared rate-limit store could not reach the database, so this pod is counting limits in its own memory until it can — each limit is per pod, not per fleet, meanwhile',
-        fix: 'x doctor --json   # names the database binding this pod cannot reach',
+        ...degradedLine(owner),
       });
     },
   };

package/src/rate-limit-errors.ts

@@ -35,8 +35,8 @@ export const rateLimitNotShared = (found: 'process' | 'disabled' | 'installed'):
           : "http.rateLimit.scope is 'shared' but the installed store keeps its counters in this process, so each replica would enforce the full bucket on its own",
     fix:
       found === 'installed'
-        ? 'installRateLimitStore(rateLimitStore) at boot, with the same postgresRateLimitStore({ executor }) passed to httpServer({ routes, rateLimitStore })'
-        : "httpServer({ routes, rateLimitStore: postgresRateLimitStore({ executor: { query: (text, values) => db().query({ text, values }) } }) }) — or defineHttpConfig({ rateLimit: { scope: 'process' } }) to accept per-replica limits",
+        ? "defineHttpConfig({ rateLimit: { scope: 'process' } })   # to accept per-replica limits — or delete rateLimitStore from apps/<app>/runtime.ts so the boot installs postgresRateLimitStore over the pool it opened, or name a store whose scope is 'shared'"
+        : "export const runtime = { rateLimitStore: postgresRateLimitStore({ executor: { query: (text, values) => db().query({ text, values }) } }) }   # apps/<app>/runtime.ts — or defineHttpConfig({ rateLimit: { scope: 'process' } }) to accept per-replica limits",
   });
 
 /**
@@ -135,7 +135,7 @@ export const rateLimitBucketUnbound = (input: {
         ? 'does not hold that bucket, so the route would run on the default one'
         : `holds ${numbers(input.found)} for it`
     }`,
-    fix: 'pass the STORE and let the pipeline build the limiter — httpServer({ routes, rateLimitStore }) — so the bucket table is the one the routes registered',
+    fix: 'httpServer({ routes })   # drop PipelineDeps.limiter: the server builds the limiter over the installed store (rateLimitStore in apps/<app>/runtime.ts), so the bucket table is the one the routes registered',
   });
 
 /**
@@ -151,7 +151,7 @@ export const rateLimitScopeUnset = (): HttpError =>
     code: 'X_RATE_LIMIT_SCOPE_UNSET',
     cause:
       'http.rateLimit is enabled and the deployment has not declared http.rateLimit.scope, so the numbers below it are per replica rather than per fleet',
-    fix: "defineHttpConfig({ rateLimit: { scope: 'process' } }) if this app runs as ONE replica, or scope: 'shared' plus httpServer({ routes, rateLimitStore: postgresRateLimitStore({ executor }) }) for a fleet-wide limit — a process booted by x dev or apps/web/server.ts derives it from the store it installed and never declares it",
+    fix: "defineHttpConfig({ rateLimit: { scope: 'process' } }) if this app runs as ONE replica, or scope: 'shared' plus rateLimitStore: postgresRateLimitStore({ executor }) in apps/<app>/runtime.ts for a fleet-wide limit — a process booted by x dev or apps/web/server.ts derives it from the store it installed and never declares it",
   });
 
 /**