@wildo-ai/saas-frontend-lib 1.0.1 → 1.1.0

package/dist/esm/core/requests/auth-refresh-resilience.frontend.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Token-refresh resilience helpers (shared by `WildoHttpClient`'s 401-renewal
+ * interceptor and `AuthSessionContext.tokenRenewalHandler`).
+ *
+ * Background — why this exists:
+ *   The refresh token travels in the `__wildo_refresh` `HttpOnly` cookie.
+ *   `AuthSessionContext.logout()` clears that cookie server-side, and the
+ *   cookie is SHARED across every tab of the same origin. Historically ANY
+ *   refresh failure triggered `logout()`, so a single non-authoritative blip
+ *   (the backend restarting during a dev recompile, a 5xx, a timeout, or a
+ *   racy revoke) did not merely fail one request — it DELETED the refresh
+ *   token, turning a recoverable hiccup into a permanent, cross-tab forced
+ *   logout. That is wrong in production (a backend blip must not log everyone
+ *   out) and catastrophic in development (constant recompiles → constant
+ *   "you need to sign in again").
+ *
+ * The fix splits refresh failures into two classes and only lets an
+ * AUTHORITATIVE rejection destroy the session.
+ */
+/**
+ * Was the renewal AUTHORITATIVELY rejected — i.e. did the backend explicitly
+ * refuse THIS refresh token, meaning the session is genuinely dead and the
+ * user must re-authenticate?
+ *
+ * AUTHORITATIVE (returns `true`) — destroy the session:
+ *   - `400` — the `__wildo_refresh` cookie was absent (no session to refresh).
+ *   - `401` — the refresh token failed verification / was revoked / all
+ *     sessions were invalidated.
+ *   - `403` — the refresh was forbidden.
+ *
+ * TRANSIENT (returns `false`) — preserve the session, retry on a later request:
+ *   - No HTTP response at all (`status` undefined) — network error,
+ *     `ECONNREFUSED` while the backend is restarting, DNS, CORS preflight fail.
+ *   - `>= 500` — a backend-side error (the backend is up but unhealthy /
+ *     mid-boot), unrelated to the validity of the refresh token.
+ *   - `408` — request timeout.
+ *   - Any other unexpected status — treated conservatively as transient so an
+ *     ambiguous code never silently destroys a valid session.
+ *
+ * The error shape is the enhanced axios error produced by
+ * `WildoHttpClient.responseErrorInterceptor`, which sets `error.httpStatus`
+ * only when the response carries a body; we therefore fall back to the raw
+ * `error.response.status` so a body-less 4xx/5xx refresh response is still
+ * classified by its status.
+ */
+export declare function isAuthoritativeRefreshRejection(error: unknown): boolean;
+/**
+ * Property the 401-renewal interceptor stamps on the ORIGINAL request error
+ * when a token renewal could not complete for a NON-authoritative reason
+ * (backend unreachable / 5xx / timeout). It lets a downstream recovery path
+ * (notably session restore) recognise that a resulting 401 reflects "renewal
+ * couldn't happen", not "the session is dead" — so it should be retried rather
+ * than logged out. Set only when the renewal failure was transient; a genuinely
+ * authoritative rejection is never tagged.
+ */
+export declare const RENEWAL_TRANSIENTLY_FAILED_MARKER = "__renewalTransientlyFailed";
+/**
+ * Should a failure be treated as a TRANSIENT backend problem that warrants
+ * preserving the session and retrying, rather than tearing it down?
+ *
+ * Returns `true` for:
+ *   - an error tagged {@link RENEWAL_TRANSIENTLY_FAILED_MARKER} (a 401 whose
+ *     in-flight renewal failed transiently — the session is not proven dead),
+ *   - `>= 500` / `408` (backend-side error / timeout), and
+ *   - a response-less error that is recognisably an HTTP/network-layer failure
+ *     (axios network error: `isAxiosError` / `request` / `config` / a string
+ *     `code`). A response-less error WITHOUT those markers is treated as
+ *     NON-transient — it is almost certainly a thrown code bug, and retrying it
+ *     forever would mask the bug and spin.
+ *
+ * Returns `false` for authoritative 4xx (400/401/403/etc.) and for non-HTTP
+ * exceptions, both of which must terminate rather than retry.
+ */
+export declare function isTransientBackendFailure(error: unknown): boolean;
+/**
+ * Is development-mode refresh leniency active?
+ *
+ * In `development` the backend is recompiled and restarted constantly by the
+ * dev watchers, which routinely produces authoritative-LOOKING `400`/`401`
+ * responses (e.g. the cookie momentarily cleared by a racing tab, or the
+ * session store transiently unavailable) even though the session is fine once
+ * the backend settles. To keep dev / AI-driven sessions alive we never
+ * hard-logout on a refresh failure in development — the session is preserved
+ * and the next request retries.
+ *
+ * Security note: this NEVER relaxes production. On any uncertainty (env not yet
+ * loaded, loader throws) we fail closed to strict production behavior.
+ */
+export declare function isRefreshDevLenient(): boolean;
+//# sourceMappingURL=auth-refresh-resilience.frontend.d.ts.map

package/dist/esm/core/requests/auth-refresh-resilience.frontend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-refresh-resilience.frontend.d.ts","sourceRoot":"","sources":["../../../../../src/core/requests/auth-refresh-resilience.frontend.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAWvE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iCAAiC,+BAA+B,CAAC;AAE9E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAyBjE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAM7C"}

package/dist/esm/core/requests/auth-refresh-resilience.frontend.js

@@ -0,0 +1,125 @@
+import { envLoader } from '../../core/runtime/env-variable-loader.frontend.service.js';
+/**
+ * Token-refresh resilience helpers (shared by `WildoHttpClient`'s 401-renewal
+ * interceptor and `AuthSessionContext.tokenRenewalHandler`).
+ *
+ * Background — why this exists:
+ *   The refresh token travels in the `__wildo_refresh` `HttpOnly` cookie.
+ *   `AuthSessionContext.logout()` clears that cookie server-side, and the
+ *   cookie is SHARED across every tab of the same origin. Historically ANY
+ *   refresh failure triggered `logout()`, so a single non-authoritative blip
+ *   (the backend restarting during a dev recompile, a 5xx, a timeout, or a
+ *   racy revoke) did not merely fail one request — it DELETED the refresh
+ *   token, turning a recoverable hiccup into a permanent, cross-tab forced
+ *   logout. That is wrong in production (a backend blip must not log everyone
+ *   out) and catastrophic in development (constant recompiles → constant
+ *   "you need to sign in again").
+ *
+ * The fix splits refresh failures into two classes and only lets an
+ * AUTHORITATIVE rejection destroy the session.
+ */
+/**
+ * Was the renewal AUTHORITATIVELY rejected — i.e. did the backend explicitly
+ * refuse THIS refresh token, meaning the session is genuinely dead and the
+ * user must re-authenticate?
+ *
+ * AUTHORITATIVE (returns `true`) — destroy the session:
+ *   - `400` — the `__wildo_refresh` cookie was absent (no session to refresh).
+ *   - `401` — the refresh token failed verification / was revoked / all
+ *     sessions were invalidated.
+ *   - `403` — the refresh was forbidden.
+ *
+ * TRANSIENT (returns `false`) — preserve the session, retry on a later request:
+ *   - No HTTP response at all (`status` undefined) — network error,
+ *     `ECONNREFUSED` while the backend is restarting, DNS, CORS preflight fail.
+ *   - `>= 500` — a backend-side error (the backend is up but unhealthy /
+ *     mid-boot), unrelated to the validity of the refresh token.
+ *   - `408` — request timeout.
+ *   - Any other unexpected status — treated conservatively as transient so an
+ *     ambiguous code never silently destroys a valid session.
+ *
+ * The error shape is the enhanced axios error produced by
+ * `WildoHttpClient.responseErrorInterceptor`, which sets `error.httpStatus`
+ * only when the response carries a body; we therefore fall back to the raw
+ * `error.response.status` so a body-less 4xx/5xx refresh response is still
+ * classified by its status.
+ */
+export function isAuthoritativeRefreshRejection(error) {
+    const e = error;
+    const rawStatus = e?.httpStatus ?? e?.response?.status;
+    const status = typeof rawStatus === 'number' ? rawStatus : undefined;
+    // No response → network / unreachable / timeout → transient.
+    if (status === undefined)
+        return false;
+    // Backend-side error or timeout → transient.
+    if (status >= 500 || status === 408)
+        return false;
+    // The backend authoritatively refused this refresh token.
+    return status === 400 || status === 401 || status === 403;
+}
+/**
+ * Property the 401-renewal interceptor stamps on the ORIGINAL request error
+ * when a token renewal could not complete for a NON-authoritative reason
+ * (backend unreachable / 5xx / timeout). It lets a downstream recovery path
+ * (notably session restore) recognise that a resulting 401 reflects "renewal
+ * couldn't happen", not "the session is dead" — so it should be retried rather
+ * than logged out. Set only when the renewal failure was transient; a genuinely
+ * authoritative rejection is never tagged.
+ */
+export const RENEWAL_TRANSIENTLY_FAILED_MARKER = '__renewalTransientlyFailed';
+/**
+ * Should a failure be treated as a TRANSIENT backend problem that warrants
+ * preserving the session and retrying, rather than tearing it down?
+ *
+ * Returns `true` for:
+ *   - an error tagged {@link RENEWAL_TRANSIENTLY_FAILED_MARKER} (a 401 whose
+ *     in-flight renewal failed transiently — the session is not proven dead),
+ *   - `>= 500` / `408` (backend-side error / timeout), and
+ *   - a response-less error that is recognisably an HTTP/network-layer failure
+ *     (axios network error: `isAxiosError` / `request` / `config` / a string
+ *     `code`). A response-less error WITHOUT those markers is treated as
+ *     NON-transient — it is almost certainly a thrown code bug, and retrying it
+ *     forever would mask the bug and spin.
+ *
+ * Returns `false` for authoritative 4xx (400/401/403/etc.) and for non-HTTP
+ * exceptions, both of which must terminate rather than retry.
+ */
+export function isTransientBackendFailure(error) {
+    const e = error;
+    if (e?.[RENEWAL_TRANSIENTLY_FAILED_MARKER] === true)
+        return true;
+    const rawStatus = e?.httpStatus ?? e?.response?.status;
+    const status = typeof rawStatus === 'number' ? rawStatus : undefined;
+    if (status !== undefined) {
+        return status >= 500 || status === 408;
+    }
+    // No HTTP status: transient only if it's recognisably an HTTP/network-layer
+    // error, never for an arbitrary thrown exception (which would retry forever).
+    return e?.isAxiosError === true
+        || e?.request !== undefined
+        || e?.config !== undefined
+        || typeof e?.code === 'string';
+}
+/**
+ * Is development-mode refresh leniency active?
+ *
+ * In `development` the backend is recompiled and restarted constantly by the
+ * dev watchers, which routinely produces authoritative-LOOKING `400`/`401`
+ * responses (e.g. the cookie momentarily cleared by a racing tab, or the
+ * session store transiently unavailable) even though the session is fine once
+ * the backend settles. To keep dev / AI-driven sessions alive we never
+ * hard-logout on a refresh failure in development — the session is preserved
+ * and the next request retries.
+ *
+ * Security note: this NEVER relaxes production. On any uncertainty (env not yet
+ * loaded, loader throws) we fail closed to strict production behavior.
+ */
+export function isRefreshDevLenient() {
+    try {
+        return envLoader.isDevelopment();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=auth-refresh-resilience.frontend.js.map

package/dist/esm/core/requests/auth-refresh-resilience.frontend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-refresh-resilience.frontend.js","sourceRoot":"","sources":["../../../../../src/core/requests/auth-refresh-resilience.frontend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uEAAuE,CAAC;AAElG;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,+BAA+B,CAAC,KAAc;IAC5D,MAAM,CAAC,GAAG,KAAqF,CAAC;IAChG,MAAM,SAAS,GAAG,CAAC,EAAE,UAAU,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC;IACvD,MAAM,MAAM,GAAG,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IAErE,6DAA6D;IAC7D,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACvC,6CAA6C;IAC7C,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IAClD,0DAA0D;IAC1D,OAAO,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,CAAC;AAC5D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,4BAA4B,CAAC;AAE9E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAAc;IACtD,MAAM,CAAC,GAAG,KAQU,CAAC;IAErB,IAAI,CAAC,EAAE,CAAC,iCAAiC,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAEjE,MAAM,SAAS,GAAG,CAAC,EAAE,UAAU,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC;IACvD,MAAM,MAAM,GAAG,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IACrE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,MAAM,IAAI,GAAG,IAAI,MAAM,KAAK,GAAG,CAAC;IACzC,CAAC;IAED,4EAA4E;IAC5E,8EAA8E;IAC9E,OAAO,CAAC,EAAE,YAAY,KAAK,IAAI;WAC1B,CAAC,EAAE,OAAO,KAAK,SAAS;WACxB,CAAC,EAAE,MAAM,KAAK,SAAS;WACvB,OAAO,CAAC,EAAE,IAAI,KAAK,QAAQ,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB;IACjC,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,aAAa,EAAE,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC","sourcesContent":["import { envLoader } from '~wildo-frontend-lib/core/runtime/env-variable-loader.frontend.service';\n\n/**\n * Token-refresh resilience helpers (shared by `WildoHttpClient`'s 401-renewal\n * interceptor and `AuthSessionContext.tokenRenewalHandler`).\n *\n * Background — why this exists:\n *   The refresh token travels in the `__wildo_refresh` `HttpOnly` cookie.\n *   `AuthSessionContext.logout()` clears that cookie server-side, and the\n *   cookie is SHARED across every tab of the same origin. Historically ANY\n *   refresh failure triggered `logout()`, so a single non-authoritative blip\n *   (the backend restarting during a dev recompile, a 5xx, a timeout, or a\n *   racy revoke) did not merely fail one request — it DELETED the refresh\n *   token, turning a recoverable hiccup into a permanent, cross-tab forced\n *   logout. That is wrong in production (a backend blip must not log everyone\n *   out) and catastrophic in development (constant recompiles → constant\n *   \"you need to sign in again\").\n *\n * The fix splits refresh failures into two classes and only lets an\n * AUTHORITATIVE rejection destroy the session.\n */\n\n/**\n * Was the renewal AUTHORITATIVELY rejected — i.e. did the backend explicitly\n * refuse THIS refresh token, meaning the session is genuinely dead and the\n * user must re-authenticate?\n *\n * AUTHORITATIVE (returns `true`) — destroy the session:\n *   - `400` — the `__wildo_refresh` cookie was absent (no session to refresh).\n *   - `401` — the refresh token failed verification / was revoked / all\n *     sessions were invalidated.\n *   - `403` — the refresh was forbidden.\n *\n * TRANSIENT (returns `false`) — preserve the session, retry on a later request:\n *   - No HTTP response at all (`status` undefined) — network error,\n *     `ECONNREFUSED` while the backend is restarting, DNS, CORS preflight fail.\n *   - `>= 500` — a backend-side error (the backend is up but unhealthy /\n *     mid-boot), unrelated to the validity of the refresh token.\n *   - `408` — request timeout.\n *   - Any other unexpected status — treated conservatively as transient so an\n *     ambiguous code never silently destroys a valid session.\n *\n * The error shape is the enhanced axios error produced by\n * `WildoHttpClient.responseErrorInterceptor`, which sets `error.httpStatus`\n * only when the response carries a body; we therefore fall back to the raw\n * `error.response.status` so a body-less 4xx/5xx refresh response is still\n * classified by its status.\n */\nexport function isAuthoritativeRefreshRejection(error: unknown): boolean {\n  const e = error as { httpStatus?: unknown; response?: { status?: unknown } } | null | undefined;\n  const rawStatus = e?.httpStatus ?? e?.response?.status;\n  const status = typeof rawStatus === 'number' ? rawStatus : undefined;\n\n  // No response → network / unreachable / timeout → transient.\n  if (status === undefined) return false;\n  // Backend-side error or timeout → transient.\n  if (status >= 500 || status === 408) return false;\n  // The backend authoritatively refused this refresh token.\n  return status === 400 || status === 401 || status === 403;\n}\n\n/**\n * Property the 401-renewal interceptor stamps on the ORIGINAL request error\n * when a token renewal could not complete for a NON-authoritative reason\n * (backend unreachable / 5xx / timeout). It lets a downstream recovery path\n * (notably session restore) recognise that a resulting 401 reflects \"renewal\n * couldn't happen\", not \"the session is dead\" — so it should be retried rather\n * than logged out. Set only when the renewal failure was transient; a genuinely\n * authoritative rejection is never tagged.\n */\nexport const RENEWAL_TRANSIENTLY_FAILED_MARKER = '__renewalTransientlyFailed';\n\n/**\n * Should a failure be treated as a TRANSIENT backend problem that warrants\n * preserving the session and retrying, rather than tearing it down?\n *\n * Returns `true` for:\n *   - an error tagged {@link RENEWAL_TRANSIENTLY_FAILED_MARKER} (a 401 whose\n *     in-flight renewal failed transiently — the session is not proven dead),\n *   - `>= 500` / `408` (backend-side error / timeout), and\n *   - a response-less error that is recognisably an HTTP/network-layer failure\n *     (axios network error: `isAxiosError` / `request` / `config` / a string\n *     `code`). A response-less error WITHOUT those markers is treated as\n *     NON-transient — it is almost certainly a thrown code bug, and retrying it\n *     forever would mask the bug and spin.\n *\n * Returns `false` for authoritative 4xx (400/401/403/etc.) and for non-HTTP\n * exceptions, both of which must terminate rather than retry.\n */\nexport function isTransientBackendFailure(error: unknown): boolean {\n  const e = error as {\n    [RENEWAL_TRANSIENTLY_FAILED_MARKER]?: unknown;\n    httpStatus?: unknown;\n    response?: { status?: unknown };\n    request?: unknown;\n    config?: unknown;\n    code?: unknown;\n    isAxiosError?: unknown;\n  } | null | undefined;\n\n  if (e?.[RENEWAL_TRANSIENTLY_FAILED_MARKER] === true) return true;\n\n  const rawStatus = e?.httpStatus ?? e?.response?.status;\n  const status = typeof rawStatus === 'number' ? rawStatus : undefined;\n  if (status !== undefined) {\n    return status >= 500 || status === 408;\n  }\n\n  // No HTTP status: transient only if it's recognisably an HTTP/network-layer\n  // error, never for an arbitrary thrown exception (which would retry forever).\n  return e?.isAxiosError === true\n    || e?.request !== undefined\n    || e?.config !== undefined\n    || typeof e?.code === 'string';\n}\n\n/**\n * Is development-mode refresh leniency active?\n *\n * In `development` the backend is recompiled and restarted constantly by the\n * dev watchers, which routinely produces authoritative-LOOKING `400`/`401`\n * responses (e.g. the cookie momentarily cleared by a racing tab, or the\n * session store transiently unavailable) even though the session is fine once\n * the backend settles. To keep dev / AI-driven sessions alive we never\n * hard-logout on a refresh failure in development — the session is preserved\n * and the next request retries.\n *\n * Security note: this NEVER relaxes production. On any uncertainty (env not yet\n * loaded, loader throws) we fail closed to strict production behavior.\n */\nexport function isRefreshDevLenient(): boolean {\n  try {\n    return envLoader.isDevelopment();\n  } catch {\n    return false;\n  }\n}\n"]}

package/dist/esm/core/requests/client-instance-id.frontend.service.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Client-install identification (`clientInstanceId`) — the browser half of the OPT-IN,
+ * DEFAULT-OFF capability decided in Fork D / SD9.
+ *
+ * A `clientInstanceId` answers "which browser/device install issued this request?" — the axis that
+ * lets an investigator group one actor's activity across sessions and logins, which the per-request
+ * `correlationId` and the static `frontendServiceName` cannot. Because it is stored on the user's
+ * terminal equipment it engages ePrivacy Art 5(3), so the framework never enables it on its own:
+ * each application authors `compliance.clientInstanceIdScope` and this module obeys it.
+ *
+ * **Why a module-level singleton rather than React state.** The HTTP clients are constructed during
+ * bootstrap, BEFORE the backend app-config (which carries the policy) has been fetched, and they live
+ * outside the React tree — so they cannot read `ApplicationContext`. This mirrors the established
+ * `envLoader` singleton + the "push state into the HTTP client" pattern already used for anonymous
+ * sessions and consumable tokens.
+ *
+ * **Fail-closed by construction.** The scope starts `DISABLED`, so between process start and the
+ * moment bootstrap calls {@link configureClientInstanceIdPolicy} nothing is minted, stored, or sent.
+ * An application that never opts in therefore never creates the identifier at all — and even if a
+ * client did send the header, the backend independently refuses to ingest it under the same policy.
+ */
+import { ClientInstanceIdScope } from '@wildo-ai/saas-models';
+/**
+ * Apply the application's authored policy. Called ONCE from bootstrap, after the backend app-config
+ * (which carries `compliance.clientInstanceIdScope`) has been fetched.
+ *
+ * - `DISABLED` → purges any stored id and sends nothing thereafter.
+ * - `SESSION` / `PERSISTENT` → reuses the id already held in that scope's storage, or mints one.
+ *
+ * Idempotent, and safe to call again with a DIFFERENT scope: the previous storage area is purged
+ * first, so narrowing the policy genuinely removes the wider-lifetime identifier.
+ *
+ * **No storage ⇒ no identifier.** If the scope's storage area is unavailable (a non-browser realm such
+ * as the companion's Node bridge or an SSR pass, or a browser refusing access in private mode), this
+ * mints NOTHING and the capability stays off. That is deliberate on two grounds. Correctness: this
+ * module's state is module-level, so an id minted in a shared Node process would be one identifier
+ * handed to every user that process serves — a cross-user identifier, the exact opposite of what a
+ * per-install id means. Value: the id exists to correlate activity ACROSS sessions, which an
+ * in-memory-only value cannot do, so the fallback bought nothing while carrying that risk.
+ */
+export declare function configureClientInstanceIdPolicy(scope: ClientInstanceIdScope): void;
+/**
+ * The id to stamp on outbound requests, or `undefined` when the application has not opted in.
+ * Read per request (never cached at client construction) so the policy takes effect the moment
+ * bootstrap applies it, on a client that was built before the config arrived.
+ */
+export declare function getClientInstanceId(): string | undefined;
+/** The policy currently in force — for diagnostics and transparency surfaces. */
+export declare function getClientInstanceIdScope(): ClientInstanceIdScope;
+/**
+ * Reset to the fail-closed default and erase stored ids. Used by tests, and available to an
+ * application that must honour a consent withdrawal without a reload.
+ */
+export declare function resetClientInstanceIdPolicy(): void;
+//# sourceMappingURL=client-instance-id.frontend.service.d.ts.map

package/dist/esm/core/requests/client-instance-id.frontend.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-instance-id.frontend.service.d.ts","sourceRoot":"","sources":["../../../../../src/core/requests/client-instance-id.frontend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAwE9D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI,CAqClF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,GAAG,SAAS,CAKxD;AAED,iFAAiF;AACjF,wBAAgB,wBAAwB,IAAI,qBAAqB,CAEhE;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAIlD"}

package/dist/esm/core/requests/client-instance-id.frontend.service.js

@@ -0,0 +1,165 @@
+/**
+ * Client-install identification (`clientInstanceId`) — the browser half of the OPT-IN,
+ * DEFAULT-OFF capability decided in Fork D / SD9.
+ *
+ * A `clientInstanceId` answers "which browser/device install issued this request?" — the axis that
+ * lets an investigator group one actor's activity across sessions and logins, which the per-request
+ * `correlationId` and the static `frontendServiceName` cannot. Because it is stored on the user's
+ * terminal equipment it engages ePrivacy Art 5(3), so the framework never enables it on its own:
+ * each application authors `compliance.clientInstanceIdScope` and this module obeys it.
+ *
+ * **Why a module-level singleton rather than React state.** The HTTP clients are constructed during
+ * bootstrap, BEFORE the backend app-config (which carries the policy) has been fetched, and they live
+ * outside the React tree — so they cannot read `ApplicationContext`. This mirrors the established
+ * `envLoader` singleton + the "push state into the HTTP client" pattern already used for anonymous
+ * sessions and consumable tokens.
+ *
+ * **Fail-closed by construction.** The scope starts `DISABLED`, so between process start and the
+ * moment bootstrap calls {@link configureClientInstanceIdPolicy} nothing is minted, stored, or sent.
+ * An application that never opts in therefore never creates the identifier at all — and even if a
+ * client did send the header, the backend independently refuses to ingest it under the same policy.
+ */
+import { ClientInstanceIdScope } from '@wildo-ai/saas-models';
+import { RUNTIME_SCOPED_STORAGE_KEYS } from '../../core/commons/local-storage.frontend.schemas.js';
+/**
+ * Storage key for the minted id — named in `RUNTIME_SCOPED_STORAGE_KEYS` (the registry for keys whose
+ * storage AREA is chosen at runtime), not in `LOCAL_STORAGE_KEYS`, because this value may live in
+ * either area depending on the authored scope.
+ */
+const CLIENT_INSTANCE_ID_STORAGE_KEY = RUNTIME_SCOPED_STORAGE_KEYS.CLIENT_INSTANCE_ID;
+/**
+ * The policy currently in force. `DISABLED` until bootstrap says otherwise — see "fail-closed" above.
+ */
+let activeScope = ClientInstanceIdScope.DISABLED;
+/** In-memory cache so the per-request read in the axios interceptor never touches storage. */
+let cachedClientInstanceId;
+/**
+ * The Web Storage area a scope stores its id in. `SESSION` uses `sessionStorage` so the id dies with
+ * the tab; `PERSISTENT` uses `localStorage` so it survives restarts and logouts. `DISABLED` has none.
+ *
+ * **Probes availability instead of sniffing for `window`.** `engine/CLAUDE.md` requires frontend libs to
+ * stay pure-frontend with no `typeof window` checks, and the check would be the wrong question anyway:
+ * what this module needs to know is whether a STORAGE AREA exists, which is also false in a browser with
+ * storage blocked (private mode, disabled cookies, a sandboxed cross-origin frame). Reading through
+ * `globalThis` inside try/catch answers exactly that in one expression — `undefined` in a non-browser
+ * realm, a throw when the browser refuses access, a `Storage` otherwise.
+ */
+function storageForScope(scope) {
+    try {
+        const area = scope === ClientInstanceIdScope.SESSION ? globalThis.sessionStorage
+            : scope === ClientInstanceIdScope.PERSISTENT ? globalThis.localStorage
+                : undefined;
+        return area ?? undefined;
+    }
+    catch {
+        // The browser refused access to the area. Treated as unavailable — see the mint rule below.
+        return undefined;
+    }
+}
+/**
+ * Erase any previously stored id from BOTH storage areas.
+ *
+ * Called on every policy application, which is what makes the control reversible: turning the policy
+ * OFF (or NARROWING `PERSISTENT` → `SESSION`) must not leave the old identifier sitting on the user's
+ * device. Without this, a persistent id would silently outlive the consent or the decision that
+ * created it — the practical form of the Art-17 erasure obligation on this field.
+ *
+ * assurance-control: WILDO.PRIVACY.DATA_MINIMIZATION — withdrawing or narrowing the client-install
+ * policy erases the identifier from the user's device rather than merely ceasing to send it.
+ */
+function purgeStoredClientInstanceIds() {
+    for (const scope of [ClientInstanceIdScope.SESSION, ClientInstanceIdScope.PERSISTENT]) {
+        try {
+            storageForScope(scope)?.removeItem(CLIENT_INSTANCE_ID_STORAGE_KEY);
+        }
+        catch {
+            // Unavailable storage — nothing to purge there.
+        }
+    }
+}
+function mintClientInstanceId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    // Fallback for environments without the WebCrypto UUID helper. This value is a correlation token,
+    // never a secret or an authorization input, so a non-cryptographic fallback is acceptable.
+    return `ci-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
+}
+/**
+ * Apply the application's authored policy. Called ONCE from bootstrap, after the backend app-config
+ * (which carries `compliance.clientInstanceIdScope`) has been fetched.
+ *
+ * - `DISABLED` → purges any stored id and sends nothing thereafter.
+ * - `SESSION` / `PERSISTENT` → reuses the id already held in that scope's storage, or mints one.
+ *
+ * Idempotent, and safe to call again with a DIFFERENT scope: the previous storage area is purged
+ * first, so narrowing the policy genuinely removes the wider-lifetime identifier.
+ *
+ * **No storage ⇒ no identifier.** If the scope's storage area is unavailable (a non-browser realm such
+ * as the companion's Node bridge or an SSR pass, or a browser refusing access in private mode), this
+ * mints NOTHING and the capability stays off. That is deliberate on two grounds. Correctness: this
+ * module's state is module-level, so an id minted in a shared Node process would be one identifier
+ * handed to every user that process serves — a cross-user identifier, the exact opposite of what a
+ * per-install id means. Value: the id exists to correlate activity ACROSS sessions, which an
+ * in-memory-only value cannot do, so the fallback bought nothing while carrying that risk.
+ */
+export function configureClientInstanceIdPolicy(scope) {
+    activeScope = scope;
+    cachedClientInstanceId = undefined;
+    if (scope === ClientInstanceIdScope.DISABLED) {
+        purgeStoredClientInstanceIds();
+        return;
+    }
+    const storage = storageForScope(scope);
+    if (!storage) {
+        // See "No storage ⇒ no identifier" above. `activeScope` is left as authored so a transparency
+        // surface still reports the app's posture truthfully; `getClientInstanceId()` returns undefined
+        // because nothing was minted.
+        return;
+    }
+    let existing = null;
+    try {
+        existing = storage.getItem(CLIENT_INSTANCE_ID_STORAGE_KEY);
+    }
+    catch {
+        existing = null;
+    }
+    // Purge AFTER reading so the id is carried across a same-scope re-configure, but the OTHER area's
+    // stale copy (from a previously wider scope) is still removed.
+    purgeStoredClientInstanceIds();
+    const id = existing || mintClientInstanceId();
+    try {
+        storage.setItem(CLIENT_INSTANCE_ID_STORAGE_KEY, id);
+    }
+    catch {
+        // The area existed a moment ago but refused the write (quota, eviction). Do not cache an id we
+        // could not persist — it would be per-page-load only, i.e. the case ruled out above.
+        return;
+    }
+    cachedClientInstanceId = id;
+}
+/**
+ * The id to stamp on outbound requests, or `undefined` when the application has not opted in.
+ * Read per request (never cached at client construction) so the policy takes effect the moment
+ * bootstrap applies it, on a client that was built before the config arrived.
+ */
+export function getClientInstanceId() {
+    if (activeScope === ClientInstanceIdScope.DISABLED) {
+        return undefined;
+    }
+    return cachedClientInstanceId;
+}
+/** The policy currently in force — for diagnostics and transparency surfaces. */
+export function getClientInstanceIdScope() {
+    return activeScope;
+}
+/**
+ * Reset to the fail-closed default and erase stored ids. Used by tests, and available to an
+ * application that must honour a consent withdrawal without a reload.
+ */
+export function resetClientInstanceIdPolicy() {
+    activeScope = ClientInstanceIdScope.DISABLED;
+    cachedClientInstanceId = undefined;
+    purgeStoredClientInstanceIds();
+}
+//# sourceMappingURL=client-instance-id.frontend.service.js.map

package/dist/esm/core/requests/client-instance-id.frontend.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-instance-id.frontend.service.js","sourceRoot":"","sources":["../../../../../src/core/requests/client-instance-id.frontend.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Client-install identification (`clientInstanceId`) — the browser half of the OPT-IN,\n * DEFAULT-OFF capability decided in Fork D / SD9.\n *\n * A `clientInstanceId` answers \"which browser/device install issued this request?\" — the axis that\n * lets an investigator group one actor's activity across sessions and logins, which the per-request\n * `correlationId` and the static `frontendServiceName` cannot. Because it is stored on the user's\n * terminal equipment it engages ePrivacy Art 5(3), so the framework never enables it on its own:\n * each application authors `compliance.clientInstanceIdScope` and this module obeys it.\n *\n * **Why a module-level singleton rather than React state.** The HTTP clients are constructed during\n * bootstrap, BEFORE the backend app-config (which carries the policy) has been fetched, and they live\n * outside the React tree — so they cannot read `ApplicationContext`. This mirrors the established\n * `envLoader` singleton + the \"push state into the HTTP client\" pattern already used for anonymous\n * sessions and consumable tokens.\n *\n * **Fail-closed by construction.** The scope starts `DISABLED`, so between process start and the\n * moment bootstrap calls {@link configureClientInstanceIdPolicy} nothing is minted, stored, or sent.\n * An application that never opts in therefore never creates the identifier at all — and even if a\n * client did send the header, the backend independently refuses to ingest it under the same policy.\n */\nimport { ClientInstanceIdScope } from '@wildo-ai/saas-models';\nimport { RUNTIME_SCOPED_STORAGE_KEYS } from '~wildo-frontend-lib/core/commons/local-storage.frontend.schemas';\n\n/**\n * Storage key for the minted id — named in `RUNTIME_SCOPED_STORAGE_KEYS` (the registry for keys whose\n * storage AREA is chosen at runtime), not in `LOCAL_STORAGE_KEYS`, because this value may live in\n * either area depending on the authored scope.\n */\nconst CLIENT_INSTANCE_ID_STORAGE_KEY = RUNTIME_SCOPED_STORAGE_KEYS.CLIENT_INSTANCE_ID;\n\n/**\n * The policy currently in force. `DISABLED` until bootstrap says otherwise — see \"fail-closed\" above.\n */\nlet activeScope: ClientInstanceIdScope = ClientInstanceIdScope.DISABLED;\n\n/** In-memory cache so the per-request read in the axios interceptor never touches storage. */\nlet cachedClientInstanceId: string | undefined;\n\n/**\n * The Web Storage area a scope stores its id in. `SESSION` uses `sessionStorage` so the id dies with\n * the tab; `PERSISTENT` uses `localStorage` so it survives restarts and logouts. `DISABLED` has none.\n *\n * **Probes availability instead of sniffing for `window`.** `engine/CLAUDE.md` requires frontend libs to\n * stay pure-frontend with no `typeof window` checks, and the check would be the wrong question anyway:\n * what this module needs to know is whether a STORAGE AREA exists, which is also false in a browser with\n * storage blocked (private mode, disabled cookies, a sandboxed cross-origin frame). Reading through\n * `globalThis` inside try/catch answers exactly that in one expression — `undefined` in a non-browser\n * realm, a throw when the browser refuses access, a `Storage` otherwise.\n */\nfunction storageForScope(scope: ClientInstanceIdScope): Storage | undefined {\n  try {\n    const area: Storage | undefined =\n      scope === ClientInstanceIdScope.SESSION ? globalThis.sessionStorage\n      : scope === ClientInstanceIdScope.PERSISTENT ? globalThis.localStorage\n      : undefined;\n    return area ?? undefined;\n  } catch {\n    // The browser refused access to the area. Treated as unavailable — see the mint rule below.\n    return undefined;\n  }\n}\n\n/**\n * Erase any previously stored id from BOTH storage areas.\n *\n * Called on every policy application, which is what makes the control reversible: turning the policy\n * OFF (or NARROWING `PERSISTENT` → `SESSION`) must not leave the old identifier sitting on the user's\n * device. Without this, a persistent id would silently outlive the consent or the decision that\n * created it — the practical form of the Art-17 erasure obligation on this field.\n *\n * assurance-control: WILDO.PRIVACY.DATA_MINIMIZATION — withdrawing or narrowing the client-install\n * policy erases the identifier from the user's device rather than merely ceasing to send it.\n */\nfunction purgeStoredClientInstanceIds(): void {\n  for (const scope of [ClientInstanceIdScope.SESSION, ClientInstanceIdScope.PERSISTENT]) {\n    try {\n      storageForScope(scope)?.removeItem(CLIENT_INSTANCE_ID_STORAGE_KEY);\n    } catch {\n      // Unavailable storage — nothing to purge there.\n    }\n  }\n}\n\nfunction mintClientInstanceId(): string {\n  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {\n    return crypto.randomUUID();\n  }\n  // Fallback for environments without the WebCrypto UUID helper. This value is a correlation token,\n  // never a secret or an authorization input, so a non-cryptographic fallback is acceptable.\n  return `ci-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;\n}\n\n/**\n * Apply the application's authored policy. Called ONCE from bootstrap, after the backend app-config\n * (which carries `compliance.clientInstanceIdScope`) has been fetched.\n *\n * - `DISABLED` → purges any stored id and sends nothing thereafter.\n * - `SESSION` / `PERSISTENT` → reuses the id already held in that scope's storage, or mints one.\n *\n * Idempotent, and safe to call again with a DIFFERENT scope: the previous storage area is purged\n * first, so narrowing the policy genuinely removes the wider-lifetime identifier.\n *\n * **No storage ⇒ no identifier.** If the scope's storage area is unavailable (a non-browser realm such\n * as the companion's Node bridge or an SSR pass, or a browser refusing access in private mode), this\n * mints NOTHING and the capability stays off. That is deliberate on two grounds. Correctness: this\n * module's state is module-level, so an id minted in a shared Node process would be one identifier\n * handed to every user that process serves — a cross-user identifier, the exact opposite of what a\n * per-install id means. Value: the id exists to correlate activity ACROSS sessions, which an\n * in-memory-only value cannot do, so the fallback bought nothing while carrying that risk.\n */\nexport function configureClientInstanceIdPolicy(scope: ClientInstanceIdScope): void {\n  activeScope = scope;\n  cachedClientInstanceId = undefined;\n\n  if (scope === ClientInstanceIdScope.DISABLED) {\n    purgeStoredClientInstanceIds();\n    return;\n  }\n\n  const storage = storageForScope(scope);\n  if (!storage) {\n    // See \"No storage ⇒ no identifier\" above. `activeScope` is left as authored so a transparency\n    // surface still reports the app's posture truthfully; `getClientInstanceId()` returns undefined\n    // because nothing was minted.\n    return;\n  }\n\n  let existing: string | null = null;\n  try {\n    existing = storage.getItem(CLIENT_INSTANCE_ID_STORAGE_KEY);\n  } catch {\n    existing = null;\n  }\n\n  // Purge AFTER reading so the id is carried across a same-scope re-configure, but the OTHER area's\n  // stale copy (from a previously wider scope) is still removed.\n  purgeStoredClientInstanceIds();\n\n  const id = existing || mintClientInstanceId();\n  try {\n    storage.setItem(CLIENT_INSTANCE_ID_STORAGE_KEY, id);\n  } catch {\n    // The area existed a moment ago but refused the write (quota, eviction). Do not cache an id we\n    // could not persist — it would be per-page-load only, i.e. the case ruled out above.\n    return;\n  }\n  cachedClientInstanceId = id;\n}\n\n/**\n * The id to stamp on outbound requests, or `undefined` when the application has not opted in.\n * Read per request (never cached at client construction) so the policy takes effect the moment\n * bootstrap applies it, on a client that was built before the config arrived.\n */\nexport function getClientInstanceId(): string | undefined {\n  if (activeScope === ClientInstanceIdScope.DISABLED) {\n    return undefined;\n  }\n  return cachedClientInstanceId;\n}\n\n/** The policy currently in force — for diagnostics and transparency surfaces. */\nexport function getClientInstanceIdScope(): ClientInstanceIdScope {\n  return activeScope;\n}\n\n/**\n * Reset to the fail-closed default and erase stored ids. Used by tests, and available to an\n * application that must honour a consent withdrawal without a reload.\n */\nexport function resetClientInstanceIdPolicy(): void {\n  activeScope = ClientInstanceIdScope.DISABLED;\n  cachedClientInstanceId = undefined;\n  purgeStoredClientInstanceIds();\n}\n"]}

package/dist/esm/core/requests/network-backoff.frontend.utils.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared jittered-backoff + staggered-release helpers for the frontend network
+ * layer.
+ *
+ * These centralise the anti-thundering-herd ("auto-DDOS") math so every recovery
+ * path de-synchronises the same way: the HTTP retry backoff, the offline-queue
+ * drain, the API-readiness gate, and the WebSocket readiness poll all import from
+ * here. The problem they solve: when a backend outage ends, EVERY stuck client
+ * would otherwise fire its backlog — plus its WS reconnect — in the same instant,
+ * re-overloading the server the moment it comes back.
+ *
+ * What jitter fixes is SYNCHRONISATION, not per-client volume. Full jitter has a
+ * mean of ~window/2 vs. a deterministic window, so an individual client actually
+ * polls/retries somewhat MORE often on average — but the retries of N clients are
+ * de-correlated, so the server sees a smooth spread instead of a synchronised
+ * spike every backoff step. The spike is what melts a recovering backend, so this
+ * is the right trade (the probed endpoints — /health/ready — are cheap). If
+ * per-client probe rate ever becomes the concern, switch to "equal jitter"
+ * (half-fixed + half-random) to lift the mean back toward ~3·window/4.
+ *
+ * Design rationale (why not a token bucket): the HTTP client already caps
+ * in-flight requests via `maxConcurrentRequests`, so bounding the RATE is already
+ * handled. All that's missing is de-correlating WHEN each request/client fires,
+ * which random jitter achieves with zero additional state. See
+ * `.claude/plans/network-resilience-organization.md` (decision D3).
+ */
+/**
+ * AWS "full jitter" exponential backoff: a uniformly random delay in
+ * `[0, min(capMs, baseDelayMs · 2^attempt)]`.
+ *
+ * Full jitter (as opposed to raw exponential, or "equal jitter") gives the best
+ * cross-client de-synchronisation — two clients that failed on the same round
+ * pick independent delays, so their retries spread out instead of colliding again
+ * on every subsequent round. The randomness is the whole point; do not replace it
+ * with a deterministic curve.
+ *
+ * @param attempt      Zero-based attempt index (0 = first retry).
+ * @param baseDelayMs  Base unit of backoff before doubling.
+ * @param capMs        Hard ceiling on the pre-jitter window.
+ * @returns            A jittered delay in milliseconds.
+ */
+export declare function fullJitterBackoffMs(attempt: number, baseDelayMs: number, capMs: number): number;
+/**
+ * A fresh per-recovery offset in `[0, maxMs]`, rolled on each call.
+ *
+ * Applied ONCE per recovery event (the first offline→online drain, or the moment
+ * the readiness gate flips healthy after an outage). Because each client rolls an
+ * independent value, N clients that were all blocked on the same outage release
+ * at N different instants instead of stampeding together. Rolled fresh per
+ * recovery (not cached for the tab's lifetime) so a client that draws a large
+ * offset on one outage isn't perpetually last on every future one.
+ *
+ * @param maxMs  Upper bound on the offset (defaults to 2000ms).
+ */
+export declare function recoveryOffsetMs(maxMs?: number): number;
+/**
+ * A small randomised gap between successive releases when draining a backlog
+ * (offline queue, readiness-gate waiters). Spreads a burst over time WITHIN a
+ * single client. Combined with {@link recoveryOffsetMs} (which de-syncs clients
+ * from each other), this de-syncs a single client's own queued requests.
+ *
+ * @param minMs  Lower bound of the gap (defaults to 25ms).
+ * @param maxMs  Upper bound of the gap (defaults to 250ms).
+ */
+export declare function staggerGapMs(minMs?: number, maxMs?: number): number;
+/** Promise-based sleep used by the staggered-release helpers. */
+export declare function sleep(ms: number): Promise<void>;
+//# sourceMappingURL=network-backoff.frontend.utils.d.ts.map

package/dist/esm/core/requests/network-backoff.frontend.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-backoff.frontend.utils.d.ts","sourceRoot":"","sources":["../../../../../src/core/requests/network-backoff.frontend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AASH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAI/F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,GAAE,MAAuC,GAAG,MAAM,CAEvF;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,KAAK,GAAE,MAA+B,EACtC,KAAK,GAAE,MAA+B,GACrC,MAAM,CAER;AAED,iEAAiE;AACjE,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/dist/esm/core/requests/network-backoff.frontend.utils.js

@@ -0,0 +1,84 @@
+/**
+ * Shared jittered-backoff + staggered-release helpers for the frontend network
+ * layer.
+ *
+ * These centralise the anti-thundering-herd ("auto-DDOS") math so every recovery
+ * path de-synchronises the same way: the HTTP retry backoff, the offline-queue
+ * drain, the API-readiness gate, and the WebSocket readiness poll all import from
+ * here. The problem they solve: when a backend outage ends, EVERY stuck client
+ * would otherwise fire its backlog — plus its WS reconnect — in the same instant,
+ * re-overloading the server the moment it comes back.
+ *
+ * What jitter fixes is SYNCHRONISATION, not per-client volume. Full jitter has a
+ * mean of ~window/2 vs. a deterministic window, so an individual client actually
+ * polls/retries somewhat MORE often on average — but the retries of N clients are
+ * de-correlated, so the server sees a smooth spread instead of a synchronised
+ * spike every backoff step. The spike is what melts a recovering backend, so this
+ * is the right trade (the probed endpoints — /health/ready — are cheap). If
+ * per-client probe rate ever becomes the concern, switch to "equal jitter"
+ * (half-fixed + half-random) to lift the mean back toward ~3·window/4.
+ *
+ * Design rationale (why not a token bucket): the HTTP client already caps
+ * in-flight requests via `maxConcurrentRequests`, so bounding the RATE is already
+ * handled. All that's missing is de-correlating WHEN each request/client fires,
+ * which random jitter achieves with zero additional state. See
+ * `.claude/plans/network-resilience-organization.md` (decision D3).
+ */
+/** Default ceiling on the per-client recovery offset (ms). */
+const DEFAULT_RECOVERY_OFFSET_MAX_MS = 2000;
+/** Default lower bound for the inter-release stagger gap (ms). */
+const DEFAULT_STAGGER_MIN_MS = 25;
+/** Default upper bound for the inter-release stagger gap (ms). */
+const DEFAULT_STAGGER_MAX_MS = 250;
+/**
+ * AWS "full jitter" exponential backoff: a uniformly random delay in
+ * `[0, min(capMs, baseDelayMs · 2^attempt)]`.
+ *
+ * Full jitter (as opposed to raw exponential, or "equal jitter") gives the best
+ * cross-client de-synchronisation — two clients that failed on the same round
+ * pick independent delays, so their retries spread out instead of colliding again
+ * on every subsequent round. The randomness is the whole point; do not replace it
+ * with a deterministic curve.
+ *
+ * @param attempt      Zero-based attempt index (0 = first retry).
+ * @param baseDelayMs  Base unit of backoff before doubling.
+ * @param capMs        Hard ceiling on the pre-jitter window.
+ * @returns            A jittered delay in milliseconds.
+ */
+export function fullJitterBackoffMs(attempt, baseDelayMs, capMs) {
+    const safeAttempt = Math.max(0, attempt);
+    const window = Math.min(capMs, baseDelayMs * Math.pow(2, safeAttempt));
+    return Math.floor(Math.random() * Math.max(0, window));
+}
+/**
+ * A fresh per-recovery offset in `[0, maxMs]`, rolled on each call.
+ *
+ * Applied ONCE per recovery event (the first offline→online drain, or the moment
+ * the readiness gate flips healthy after an outage). Because each client rolls an
+ * independent value, N clients that were all blocked on the same outage release
+ * at N different instants instead of stampeding together. Rolled fresh per
+ * recovery (not cached for the tab's lifetime) so a client that draws a large
+ * offset on one outage isn't perpetually last on every future one.
+ *
+ * @param maxMs  Upper bound on the offset (defaults to 2000ms).
+ */
+export function recoveryOffsetMs(maxMs = DEFAULT_RECOVERY_OFFSET_MAX_MS) {
+    return Math.floor(Math.random() * Math.max(0, maxMs));
+}
+/**
+ * A small randomised gap between successive releases when draining a backlog
+ * (offline queue, readiness-gate waiters). Spreads a burst over time WITHIN a
+ * single client. Combined with {@link recoveryOffsetMs} (which de-syncs clients
+ * from each other), this de-syncs a single client's own queued requests.
+ *
+ * @param minMs  Lower bound of the gap (defaults to 25ms).
+ * @param maxMs  Upper bound of the gap (defaults to 250ms).
+ */
+export function staggerGapMs(minMs = DEFAULT_STAGGER_MIN_MS, maxMs = DEFAULT_STAGGER_MAX_MS) {
+    return minMs + Math.floor(Math.random() * Math.max(0, maxMs - minMs));
+}
+/** Promise-based sleep used by the staggered-release helpers. */
+export function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=network-backoff.frontend.utils.js.map