@capxul/sdk 4.20.0-beta.35 → 4.20.0-beta.37

package/dist/{production-DdjhwgRC.mjs → production-PGbIhEG0.mjs}

@@ -1,10 +1,10 @@
-import { c as OrgPortTag, l as deserializeCapxulError, n as makeOrgMethods, r as makeBankingMethods, s as ConvexOrganizationAdapter, t as ConvexOrganizationSetupAdapter } from "./organizations-BmX52Uev.mjs";
-import { $r as CAPXUL_ERROR_CODES, $t as version, A as registerProductTelemetryInvocation, An as details, B as makePaymentsMethods, Bi as isCapxulError, Br as askIdentity, Bt as failureEvidenceProps, C as AccountReadPortTag, Ci as AuthClientError, Cn as CLI_INVOCATION_KINDS, D as convexCallErrorFromCapxul, Dn as isCapxulOperation, Dr as ChainIdSchema, Dt as normalizeSafeSaltEmail, E as ConvexCallPortTag, Ei as globalLocalStorage, En as CAPXUL_OPERATIONS, Fi as toEmail, Gt as observationContextProps, H as makeDestinationsMethods, Hi as isFailureMode, Hr as runIdentityFacade, Ht as postHogFailureObservation, Jn as ORGANIZATION_SETUP_REASONS, K as makeTargetsMethods, Ki as AuthCachePortTag, Kr as runCapxulEffect, Kt as withCapturedAttemptContext, L as makeAccountMethods, Lt as asCapxulError, M as makeApprovalsMethods, Mi as toEpochMs, Nr as isEvmAddress, On as normalizeCapxulOperation, Pi as toAuthUserId, Pr as toAddress, Pt as callOperation, Qr as formatTraceparent, Ri as Errors, Rt as toPublicError, Sn as CLI_COMMAND_NAMES, Sr as EpochMsSchema, T as TelemetryPortTag, Ti as detectAuthCacheAdapter, Tn as stampTelemetryEnvelope, Ui as isRecord, Ur as runPortEffect, Ut as observeFailedResult, Vi as FAILURE_MODES, Vr as publicIdentityFailure, W as makeCheckoutMethods, Wi as readField, Wn as setups, Wr as sessionFromActor, Wt as observeSdkClient, Yn as ORGANIZATION_SETUP_STATUSES, Zn as decodeChainCause, Zr as toCapxulResult, _i as redactUrlSecrets, ai as SystemClockLayer, an as isSignerNotReadySignal, bn as redactTelemetryProps, c as makePaymentDocumentsMethods, cn as signerFailure, cr as AppIdSchema, d as SmartAccountPortTag, di as observationRequestHeaders, dn as makeClientRequestMethods, fi as attachInvocationObservation, fn as toCountryCode, g as ConvexAccountLayer, gi as redactSecrets, gn as toHandle, h as makeAccountsMethods, hi as sanitizeObservationContext, in as isEcdsaSignatureHex, jn as onboardings, jt as BASE_SEPOLIA_CHAIN_ID, k as bindProductTelemetryInvocation, kn as OPERATIONS, l as makeSmartAccountMethods, li as BetterAuthNodeLayer, lr as images, m as PonderIndexerAdapter, mi as readInvocationObservation, mn as toTesterKind, mr as isBytes32, n as bootIdentityFlow, ni as carryInvocationParentSpan, nn as causeChain, on as openfortSignerNotReadyCode, p as makeHoldingsMethods, pi as copyInvocationObservation, pn as toKycTier, q as makeVerificationMethods, r as makeMeMethods, s as makeActivityMethods, si as ClockPortTag, sn as recoverRawDigestSigner, sr as diagnostics, t as executeIdentityProductObservation, ti as ActorFailure, tn as UNOBSERVABLE_SIGNER_STATUS, u as ConvexSmartAccountLayer, ui as BetterAuthBrowserLayer, un as makeCurrentUserMethods, vi as isCredentialField, vn as validateHandle, wi as AuthClientPortTag, xi as toPublishableKey, xn as CLI_CAPABILITIES, xr as DurationMsSchema, yi as toAllowedOrigin, zi as CapxulError, zr as makeAuthMethods, zt as failureDetail } from "./access-DpPt-SvA.mjs";
+import { c as OrgPortTag, n as makeOrgMethods, r as makeBankingMethods, s as ConvexOrganizationAdapter, t as ConvexOrganizationSetupAdapter } from "./organizations-DPpyjjx2.mjs";
+import { $i as PROVIDERS, $n as copyInvocationObservation, A as bindProductTelemetryInvocation, Ai as redactUrlSecrets, An as runPortEffect, Bn as ActorFailure, Bt as toPublicError, C as AccountReadPortTag, Ci as toAddress, D as ConvexCallPortTag, Dn as noSessionError, E as ConvexCallError, En as askIdentity, G as makeCheckoutMethods, Gi as toEpochMs, Gt as observeFailedResult, Ht as failureEvidenceProps, Ii as AuthClientError, Ir as decodeChainCause, It as callOperation, J as makeVerificationMethods, Ji as toEmail, Jr as diagnostics, Jt as withCapturedAttemptContext, Kn as ClockPortTag, Kt as observeSdkClient, Li as AuthClientPortTag, Lr as CAPXUL_ERROR_CODES, Mi as toAllowedOrigin, N as makeApprovalsMethods, Nn as runCapxulEffect, Nr as ORGANIZATION_SETUP_REASONS, Nt as BASE_SEPOLIA_CHAIN_ID, O as convexCallErrorFromCapxul, Oi as sanitizeObservationContext, On as publicIdentityFailure, Pi as toPublishableKey, Pr as ORGANIZATION_SETUP_STATUSES, Qi as providerStatusFailure, Qn as attachInvocationObservation, R as makeAccountMethods, Ri as detectAuthCacheAdapter, Rn as toCapxulResult, Si as isEvmAddress, Sn as toHandle, T as TelemetryPortTag, Tn as makeAuthMethods, U as makeDestinationsMethods, V as makePaymentsMethods, Vn as carryInvocationParentSpan, Vt as failureDetail$1, Wn as SystemClockLayer, Wt as postHogFailureObservation, Xn as BetterAuthBrowserLayer, Xr as images, Y as withheld, Yn as BetterAuthNodeLayer, Yr as AppIdSchema, Zi as Errors, Zn as observationRequestHeaders, _n as makeClientRequestMethods, aa as isFailureMode, ar as CLI_COMMAND_NAMES, bn as toTesterKind, c as makePaymentDocumentsMethods, cn as httpStatusOf, d as SmartAccountPortTag, di as EpochMsSchema, dn as isSignerNotReadySignal, dr as CAPXUL_OPERATIONS, ea as PROVIDER_PROBLEMS, fn as openfortSignerNotReadyCode, fr as isCapxulOperation, g as ConvexAccountLayer, gi as ChainIdSchema, gn as makeCurrentUserMethods, gr as onboardings, h as makeAccountsMethods, hn as signerPathFailure, hr as details, ia as FAILURE_MODES, in as maskedMessage, ir as CLI_CAPABILITIES, j as registerProductTelemetryInvocation, ji as isCredentialField, jn as sessionFromActor, ki as redactSecrets, kn as runIdentityFacade, kr as setups, kt as normalizeSafeSaltEmail, l as makeSmartAccountMethods, la as AuthCachePortTag, m as PonderIndexerAdapter, mn as signerFailure, mr as OPERATIONS, n as bootIdentityFlow, na as CapxulError, nn as version, oa as isRecord, on as UNOBSERVABLE_SIGNER_STATUS, or as CLI_INVOCATION_KINDS, p as makeHoldingsMethods, pn as recoverRawDigestSigner, pr as normalizeCapxulOperation, q as makeTargetsMethods, qi as toAuthUserId, qt as observationContextProps, r as makeMeMethods, ra as isCapxulError, rn as deserializeCapxulError, rr as redactTelemetryProps, s as makeActivityMethods, sa as readField, sn as causeChain, sr as FAILURE_CLASSES, t as executeIdentityProductObservation, ta as httpStatusMode, ti as isBytes32, tr as readInvocationObservation, u as ConvexSmartAccountLayer, ui as DurationMsSchema, un as isEcdsaSignatureHex, ur as stampTelemetryEnvelope, vn as toCountryCode, wn as validateHandle, yn as toKycTier, zi as globalLocalStorage, zn as formatTraceparent, zt as asCapxulError } from "./access-aMjL10vw.mjs";
 import { Cause, Clock, Context, Data, Deferred, Duration, Effect, Exit, FiberSet, Layer, Logger, Metric, Option, Predicate, References, Result, Schedule, Schema, SchemaIssue, SchemaParser, Scope, Stream, Tracer } from "effect";
 import { getFunctionName } from "convex/server";
 import { keccak256, stringToHex } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
-import { AccountTypeEnum, ChainTypeEnum, EmbeddedState, Openfort, RecoveryMethod, ThirdPartyOAuthProvider } from "@openfort/openfort-js";
+import { AccountTypeEnum, AuthenticationError, AuthorizationError, ChainTypeEnum, EmbeddedState, IframeHandshakeTimeoutError, IframeRpcTimeoutError, OPENFORT_AUTH_ERROR_CODES, Openfort, OpenfortError, RecoveryMethod, SessionError, ThirdPartyOAuthProvider } from "@openfort/openfort-js";
 import { ConvexClient, ConvexHttpClient } from "convex/browser";
 import { FetchHttpClient, Headers, HttpBody, HttpClient, HttpClientError, HttpClientResponse } from "effect/http";
 import { OtlpExporter, OtlpLogger, OtlpMetrics, OtlpSerialization, OtlpTracer } from "effect/observability";
@@ -160,29 +160,117 @@ function embeddedSigner(input) {
 }
 //#endregion
 //#region src/signing/openfort-failures.ts
-function httpStatusOf(link) {
-	for (const status of [
-		readField(link.response, "status"),
-		link.statusCode,
-		link.status,
-		readField(link.details, "httpStatus")
-	]) if (typeof status === "number") return status;
-}
+/**
+* The codes of Openfort's two auth-refusal classes, `AuthenticationError` and
+* `AuthorizationError` (`extractApiError` in `@openfort/openfort-js` 2.6.1).
+* `AuthorizationError` always sets `error` to the lower-case word.
+*/
+const OPENFORT_AUTH_REFUSAL_CODES = /* @__PURE__ */ new Set([
+	OPENFORT_AUTH_ERROR_CODES.INVALID_CREDENTIALS,
+	OPENFORT_AUTH_ERROR_CODES.INVALID_EMAIL,
+	OPENFORT_AUTH_ERROR_CODES.INVALID_PASSWORD,
+	OPENFORT_AUTH_ERROR_CODES.INVALID_TOKEN,
+	OPENFORT_AUTH_ERROR_CODES.PROVIDER_DISABLED,
+	OPENFORT_AUTH_ERROR_CODES.EMAIL_NOT_VERIFIED,
+	OPENFORT_AUTH_ERROR_CODES.USER_NOT_AUTHORIZED,
+	"user_not_authorized"
+]);
+/**
+* The `SessionError` codes that say Openfort refused the credential. Only an
+* expired session does. The other codes of that class name an Openfort fault
+* (`FAILED_TO_CREATE_SESSION`, `FAILED_TO_GET_SESSION`), local Openfort state
+* (`NOT_LOGGED_IN`, `ALREADY_LOGGED_IN`) or a refresh that the third-party
+* flow does not do (`REFRESH_TOKEN_ERROR`).
+*/
+const OPENFORT_SESSION_REFUSAL_CODES = /* @__PURE__ */ new Set([OPENFORT_AUTH_ERROR_CODES.SESSION_EXPIRED]);
+/**
+* True when a link that has no HTTP status says Openfort refused the
+* credential: Openfort's auth-refusal class or code, or a `SessionError` for an
+* expired session. Openfort keeps the status on every error that it decodes
+* from an answer, so an answered refusal is named by its status first; this
+* reads the errors that the Openfort client makes itself, such as the
+* `AuthenticationError` it throws when the token callback gives it no access
+* token.
+*/
 function isUnauthorizedCause(cause) {
-	for (const link of causeChain(cause)) if (httpStatusOf(link) === 401) return true;
+	for (const link of causeChain(cause)) {
+		if (link instanceof AuthenticationError || link instanceof AuthorizationError) return true;
+		if (link instanceof SessionError && OPENFORT_SESSION_REFUSAL_CODES.has(link.error)) return true;
+		if (OPENFORT_AUTH_REFUSAL_CODES.has(link.error) || OPENFORT_AUTH_REFUSAL_CODES.has(link.code)) return true;
+	}
 	return false;
 }
+/**
+* The steps that send Openfort API requests: the wallet `configure`, which
+* starts with the token check (`POST /iam/v2/user/third_party`), and the
+* wallet read, in the readiness cycle (`get`) and behind `getAddress`.
+*/
+const OPENFORT_REQUEST_STEPS = /* @__PURE__ */ new Set([
+	"configure",
+	"get",
+	"getAddress"
+]);
+/**
+* The mode that Openfort's typed error fields name. `@openfort/openfort-js`
+* 2.6.1 sets `statusCode` on every error that it decodes from an answer, and
+* `requestId` on every error from an API request. The status names the mode by
+* `httpStatusMode`, and `signerPathFailure` keeps the status beside it. A
+* `requestId` with no status means that no answer arrived. That is a network
+* failure or Openfort's 30 s request timeout, and only the message text tells
+* them apart, so both are `upstream-down`. Openfort's iframe timeout classes
+* are `timeout`. The result is `undefined` when no typed field names a mode.
+*/
+function openfortRequestMode(cause) {
+	for (const link of causeChain(cause)) {
+		const httpStatus = httpStatusOf(link);
+		if (httpStatus !== void 0) return httpStatusMode(httpStatus);
+		if (link instanceof IframeRpcTimeoutError || link instanceof IframeHandshakeTimeoutError) return "timeout";
+		if (link instanceof OpenfortError && typeof link.requestId === "string") return "upstream-down";
+	}
+}
 function openfortProviderError(operation, cause) {
 	if (cause instanceof CapxulError) return cause;
-	const failure_mode = operation === "configure" && isUnauthorizedCause(cause) ? "unauthorized" : "unknown";
-	return Errors.providerError("openfort", operation, cause, { failure_mode });
+	const requestMode = OPENFORT_REQUEST_STEPS.has(operation) ? openfortRequestMode(cause) : void 0;
+	if (requestMode !== void 0 && requestMode !== "unknown") return failOpenfort(operation, requestMode, cause);
+	return failOpenfort(operation, operation === "configure" && isUnauthorizedCause(cause) ? "unauthorized" : "unknown", cause);
 }
-function openfortFailureMode(error) {
-	return error.mode ?? "unknown";
+/**
+* What the trace of a failed Openfort step says about its error: the failure
+* mode, or the code and the field when the error has no mode.
+* `PROVIDER_RESPONSE_INVALID` has no mode, and its code and field already say
+* what happened, so the trace does not report it as `unknown`.
+*/
+function openfortFailureDetail(error) {
+	if (error.mode !== void 0) return { failure_mode: error.mode };
+	const field = error.details?.field;
+	return {
+		error_code: error.code,
+		...typeof field === "string" ? { field } : {}
+	};
 }
-/** Build a named PROVIDER_ERROR. The assembled Core SDK boundary reports it. */
-function failOpenfort(operation, failure_mode, cause) {
-	return Errors.providerError("openfort", operation, cause, { failure_mode });
+/**
+* Build a named PROVIDER_ERROR. The assembled Core SDK boundary reports it.
+* An HTTP status anywhere in the cause chain rides beside the mode.
+*/
+function failOpenfort(operation, mode, cause) {
+	return signerPathFailure({
+		provider: "openfort",
+		operation,
+		mode,
+		cause
+	});
+}
+/**
+* Build a named PROVIDER_RESPONSE_INVALID: the answer arrived, and Capxul
+* cannot use it. `field` and `reason` are Capxul's own words. Nothing from
+* the answer enters the error, because the answer can hold a credential: a
+* cause that quotes the answer arrives `withheld`.
+*/
+function openfortAnswerInvalid(input) {
+	return Errors.providerResponseInvalid({
+		provider: "openfort",
+		...input
+	});
 }
 /**
 * True when the browser cannot perform Web Crypto — sandboxed iframes, headless
@@ -197,14 +285,128 @@ function isInsecureBrowserContext() {
 //#region src/signing/openfort-credentials.ts
 const sinceCycleStart = (clock) => clock.cycleStartedAt === null ? void 0 : Date.now() - clock.cycleStartedAt;
 /**
-* The auth server's token reply: `token` from the OIDC endpoint, `session.token`
-* from better-auth. A reply of any other shape fails the token read.
+* The auth server's replies. The OIDC endpoint answers `{ token }`.
+* better-auth's `get-session` answers `{ session: { token } }`, and `null` or
+* `{ session: null }` when nobody is signed in. The encryption-session
+* endpoint answers `{ sessionId }`. A reply of any other shape, `{}` included,
+* is an answer Capxul cannot use.
 */
-const AccessTokenBody = Schema.Struct({
-	token: Schema.optional(Schema.NullOr(Schema.String)),
-	session: Schema.optional(Schema.NullOr(Schema.Struct({ token: Schema.optional(Schema.NullOr(Schema.String)) })))
+const OidcTokenBody = Schema.NullOr(Schema.Struct({ token: Schema.NullOr(Schema.String) }));
+const BetterAuthSessionBody = Schema.NullOr(Schema.Struct({ session: Schema.NullOr(Schema.Struct({ token: Schema.String })) }));
+const EncryptionSessionBody = Schema.Struct({ sessionId: Schema.String });
+const MISSING$1 = "missing";
+const WRONG_TYPE$1 = "not the expected type";
+/**
+* The Schema issues of a reply, each with a fixed reason. The Schema's own
+* message can quote the reply, and the reply can hold a credential.
+*/
+const replyIssues = SchemaIssue.makeFormatterStandardSchemaV1({
+	leafHook: (issue) => issue._tag === "MissingKey" ? MISSING$1 : WRONG_TYPE$1,
+	checkHook: () => WRONG_TYPE$1
 });
 /**
+* A reply that fails its Schema, named by the path of the first field that
+* fails, or `body` when the whole reply has the wrong shape.
+*/
+function unusableReply(operation, issue, httpStatus) {
+	const first = replyIssues(issue).issues[0];
+	const path = first?.path?.map((segment) => String(typeof segment === "object" ? segment.key : segment)) ?? [];
+	const missing = first?.message === MISSING$1;
+	return openfortAnswerInvalid({
+		operation,
+		field: path.length === 0 ? "body" : path.join("."),
+		problem: missing ? "missing" : "invalid",
+		reason: missing ? MISSING$1 : WRONG_TYPE$1,
+		httpStatus
+	});
+}
+/**
+* An answer with no token: the host or the auth server has no signed-in
+* session to give Openfort. That refuses the credential, so it is
+* `unauthorized`, the mode Openfort's own refusal of a missing token takes
+* during `configure`.
+*/
+function accessTokenRead(token) {
+	return token === void 0 || token === null || token.length === 0 ? {
+		token: null,
+		failure: failOpenfort("token", "unauthorized")
+	} : { token };
+}
+/**
+* How long one auth-server request may wait for its answer. It is below the
+* SDK's 30 s identity invoke deadline (`DEFAULT_INVOKE_TIMEOUT_MS` in
+* `platform/production.ts`), so a request that never answers fails here as
+* its own `timeout`, with its trace, before that deadline ends the attempt.
+*/
+const AUTH_SERVER_REQUEST_TIMEOUT_MS = 15e3;
+/**
+* No answer arrived. The request's deadline is `timeout`; a network failure,
+* or the page tearing the request down on a reload, is `upstream-down`. The
+* deadline's own state decides, because a body read it stops can reject with
+* `AbortError` rather than the deadline's `TimeoutError`.
+*/
+function noAnswer(operation, deadline, cause) {
+	return failOpenfort(operation, deadline.aborted || readField(cause, "name") === "TimeoutError" ? "timeout" : "upstream-down", cause);
+}
+/**
+* Send one auth-server request with its deadline as the signal. The same
+* deadline stops a body that does not arrive (`readJson`). `fetch` rejects
+* only when no answer arrived. No caller passes its own signal: a caller abort
+* needs its own mode before it can join the deadline.
+*/
+async function send(operation, url, init, deadline) {
+	try {
+		return await fetch(url, {
+			...init,
+			signal: deadline
+		});
+	} catch (cause) {
+		throw noAnswer(operation, deadline, cause);
+	}
+}
+/** A failure named by its HTTP status. The body is never read: it can carry provider detail. */
+function statusFailure(operation, status) {
+	return providerStatusFailure({
+		provider: "openfort",
+		operation,
+		httpStatus: status
+	});
+}
+/**
+* Read a 2xx body. A body that is not JSON arrived, and Capxul cannot use it:
+* `PROVIDER_RESPONSE_INVALID` on `body`. The parser's own error quotes the
+* body, so only its name is kept. A body that fails in transit, or that
+* the request's deadline stops, is no answer, the same as a `fetch` that
+* rejects.
+*/
+async function readJson(operation, response, deadline) {
+	try {
+		return await response.json();
+	} catch (cause) {
+		if (cause instanceof SyntaxError) throw openfortAnswerInvalid({
+			operation,
+			field: "body",
+			problem: "invalid",
+			reason: "not JSON",
+			httpStatus: response.status,
+			cause: withheld(cause, "the parser's error quotes the body")
+		});
+		throw noAnswer(operation, deadline, cause);
+	}
+}
+/**
+* The trace detail of a failed credential step: its mode (its code and field
+* when it has no mode), and the HTTP status when one answered.
+*/
+function failureDetail(error) {
+	const httpStatus = error.details?.httpStatus;
+	return {
+		ok: false,
+		...typeof httpStatus === "number" ? { httpStatus } : {},
+		...openfortFailureDetail(error)
+	};
+}
+/**
 * The two credentials Openfort needs from the signed-in session: the access
 * token it verifies, and an encryption session for automatic recovery. A host
 * that owns login passes `auth`; otherwise both come from the auth server.
@@ -217,70 +419,80 @@ function makeOpenfortCredentials(input) {
 	function encryptionSessionUrl() {
 		return `${authBaseUrl}/encryption-session`;
 	}
-	async function fetchBetterAuthAccessToken() {
+	/** The token from the host, or from the auth server; a refusal when it has none. */
+	async function requestAccessToken() {
+		if (auth !== void 0) return accessTokenRead((await auth.getAccessToken())?.trim());
+		const deadline = AbortSignal.timeout(AUTH_SERVER_REQUEST_TIMEOUT_MS);
+		const response = await send("token", accessTokenUrl(), {
+			credentials: "include",
+			cache: "no-store"
+		}, deadline);
+		if (!response.ok) return {
+			token: null,
+			failure: statusFailure("token", response.status)
+		};
+		const body = await readJson("token", response, deadline);
+		const token = authProvider === "oidc" ? Result.map(Schema.decodeUnknownResult(OidcTokenBody)(body), (reply) => reply?.token) : Result.map(Schema.decodeUnknownResult(BetterAuthSessionBody)(body), (reply) => reply?.session?.token);
+		if (Result.isFailure(token)) throw unusableReply("token", token.failure.issue, response.status);
+		return accessTokenRead(token.success?.trim());
+	}
+	/** Read the access token Openfort verifies. Each read leaves one `openfort.token` trace. */
+	async function readAccessToken() {
 		clock.tokenCalls += 1;
 		const tokenStartedAt = Date.now();
-		try {
-			if (auth !== void 0) {
-				const token = (await auth.getAccessToken())?.trim() ?? "";
-				diagnostic?.trace("openfort.token", {
-					ok: token.length > 0,
-					tokenPresent: token.length > 0,
-					provider: authProvider,
-					call: clock.tokenCalls,
-					duration_ms: Date.now() - tokenStartedAt,
-					elapsed_ms: sinceCycleStart(clock)
-				});
-				return token.length === 0 ? null : token;
-			}
-			const response = await fetch(accessTokenUrl(), {
-				credentials: "include",
-				cache: "no-store"
-			});
-			if (!response.ok) {
-				diagnostic?.trace("openfort.token", {
-					ok: false,
-					tokenPresent: false,
-					httpStatus: response.status,
-					failure_mode: "unknown"
-				});
-				return null;
-			}
-			const body = Schema.decodeUnknownSync(AccessTokenBody)(await response.json());
-			const token = (authProvider === "oidc" ? body.token : body.session?.token)?.trim();
-			if (token === void 0 || token.length === 0) {
-				diagnostic?.trace("openfort.token", {
-					ok: false,
-					tokenPresent: false,
-					failure_mode: "unknown"
-				});
-				return null;
-			}
+		const trace = (detail) => {
 			diagnostic?.trace("openfort.token", {
-				ok: true,
-				tokenPresent: true,
+				...detail,
 				provider: authProvider,
 				call: clock.tokenCalls,
 				duration_ms: Date.now() - tokenStartedAt,
 				elapsed_ms: sinceCycleStart(clock)
 			});
-			return token;
+		};
+		let read;
+		try {
+			read = await requestAccessToken();
 		} catch (cause) {
-			diagnostic?.trace("openfort.token", {
-				ok: false,
+			const error = openfortProviderError("token", cause);
+			trace({
 				tokenPresent: false,
-				failure_mode: "unknown"
+				...failureDetail(error)
 			});
-			throw openfortProviderError("token", cause);
+			throw error;
 		}
+		trace(read.token === null ? {
+			tokenPresent: false,
+			...failureDetail(read.failure)
+		} : {
+			ok: true,
+			tokenPresent: true
+		});
+		return read;
+	}
+	/**
+	* Openfort's token callback. A signed-out session is `null`, as Openfort
+	* expects. Any other refusal is thrown: Openfort passes a callback's throw on
+	* unchanged, so `configure` keeps the refusal's own mode instead of the
+	* `INVALID_TOKEN` refusal that Openfort makes from `null`.
+	*/
+	async function fetchBetterAuthAccessToken() {
+		const read = await readAccessToken();
+		if (read.token !== null || read.failure.mode === "unauthorized") return read.token;
+		throw read.failure;
 	}
 	async function createEncryptionSession(accessToken) {
 		if (auth !== void 0) {
 			const sessionId = (await auth.createEncryptionSession(accessToken)).trim();
-			if (sessionId.length === 0) throw Errors.providerError("openfort", "encryptionSession", /* @__PURE__ */ new Error("Openfort encryption session response missing sessionId"), { failure_mode: "unknown" });
+			if (sessionId.length === 0) throw openfortAnswerInvalid({
+				operation: "encryptionSession",
+				field: "sessionId",
+				problem: "missing",
+				reason: "empty"
+			});
 			return { sessionId };
 		}
-		const response = await fetch(encryptionSessionUrl(), {
+		const deadline = AbortSignal.timeout(AUTH_SERVER_REQUEST_TIMEOUT_MS);
+		const response = await send("encryptionSession", encryptionSessionUrl(), {
 			method: "POST",
 			credentials: "include",
 			headers: {
@@ -288,15 +500,17 @@ function makeOpenfortCredentials(input) {
 				"Content-Type": "application/json"
 			},
 			body: JSON.stringify({})
-		});
-		if (!response.ok) throw Errors.providerError("openfort", "encryptionSession", /* @__PURE__ */ new Error(`Openfort encryption session failed (${response.status})`), {
-			httpStatus: response.status,
-			failure_mode: "unknown"
-		});
-		const sessionId = readField(await response.json(), "sessionId");
-		if (typeof sessionId !== "string" || sessionId.length === 0) throw Errors.providerError("openfort", "encryptionSession", /* @__PURE__ */ new Error("Openfort encryption session response missing sessionId"), {
-			httpStatus: response.status,
-			failure_mode: "unknown"
+		}, deadline);
+		if (!response.ok) throw statusFailure("encryptionSession", response.status);
+		const reply = Schema.decodeUnknownResult(EncryptionSessionBody)(await readJson("encryptionSession", response, deadline));
+		if (Result.isFailure(reply)) throw unusableReply("encryptionSession", reply.failure.issue, response.status);
+		const sessionId = reply.success.sessionId.trim();
+		if (sessionId.length === 0) throw openfortAnswerInvalid({
+			operation: "encryptionSession",
+			field: "sessionId",
+			problem: "missing",
+			reason: "empty",
+			httpStatus: response.status
 		});
 		return {
 			sessionId,
@@ -304,6 +518,7 @@ function makeOpenfortCredentials(input) {
 		};
 	}
 	return {
+		readAccessToken,
 		fetchBetterAuthAccessToken,
 		createEncryptionSession
 	};
@@ -357,9 +572,11 @@ const STALE_USER_ERROR_CODES = /* @__PURE__ */ new Set(["USER_NOT_FOUND"]);
 * `isTransportError` walks it in the Convex transport adapter.
 *
 * Known ceiling (#1435): a 401 that carries no recognized code is NOT healed.
-* `extractApiError` keeps the status only on `AuthenticationError`, so such a
-* payload is reachable. Add the code a live payload shows; do not add a message
-* match, because that trades one bug class for an ADR-0023 R4 violation.
+* `extractApiError` keeps the 401 on every error it decodes, but the status
+* alone does not name the stale user, so such a payload stays outside the
+* heal and is named `unauthorized`. Add the code a live payload shows; do not
+* add a message match, because that trades one bug class for an ADR-0023 R4
+* violation.
 */
 function isStaleUserSignal(cause) {
 	for (const link of causeChain(cause)) if (typeof link.error === "string" && STALE_USER_ERROR_CODES.has(link.error) || typeof link.code === "string" && STALE_USER_ERROR_CODES.has(link.code)) return true;
@@ -396,7 +613,7 @@ function makeWalletReadyCycle(input) {
 			ok: false,
 			failure_mode: "no-secure-context"
 		});
-		throw failOpenfort("configure", "no-secure-context", /* @__PURE__ */ new Error("Web Crypto unavailable: browser is not a secure context"));
+		throw failOpenfort("configure", "no-secure-context");
 	}
 	async function configureEmbeddedWallet(encryptionSession) {
 		await openfort.embeddedWallet.configure({
@@ -440,21 +657,22 @@ function makeWalletReadyCycle(input) {
 			if (isInsecureBrowserContext()) failNoSecureContext();
 			await openfort.waitForInitialization();
 			step("initialize");
-			const accessToken = await credentials.fetchBetterAuthAccessToken();
-			if (accessToken === null) throw openfortProviderError("token", /* @__PURE__ */ new Error("Better Auth access token unavailable for Openfort"));
+			const accessToken = await credentials.readAccessToken();
+			if (accessToken.token === null) throw accessToken.failure;
 			step("token");
 			let encryption;
 			try {
-				encryption = await credentials.createEncryptionSession(accessToken);
+				encryption = await credentials.createEncryptionSession(accessToken.token);
 			} catch (cause) {
+				const error = openfortProviderError("encryptionSession", cause);
 				let httpStatus;
 				for (const link of causeChain(cause)) httpStatus ??= httpStatusOf(link);
 				diagnostic?.trace("openfort.encryptionSession", {
 					ok: false,
 					...httpStatus === void 0 ? {} : { httpStatus },
-					failure_mode: "unknown"
+					...openfortFailureDetail(error)
 				});
-				throw openfortProviderError("encryptionSession", cause);
+				throw error;
 			}
 			diagnostic?.trace("openfort.encryptionSession", {
 				ok: true,
@@ -467,11 +685,12 @@ function makeWalletReadyCycle(input) {
 				diagnostic?.trace("openfort.embeddedState", { state: embeddedState });
 				step("embeddedState", { state: embeddedState });
 			} catch (cause) {
+				const error = openfortProviderError("embeddedState", cause);
 				diagnostic?.trace("openfort.embeddedState", {
 					ok: false,
-					failure_mode: "unknown"
+					...openfortFailureDetail(error)
 				});
-				throw openfortProviderError("embeddedState", cause);
+				throw error;
 			}
 			if (embeddedState !== EmbeddedState.READY) {
 				clearStaleOpenfortBrowserStorage(publishableKey);
@@ -484,7 +703,7 @@ function makeWalletReadyCycle(input) {
 					const error = openfortProviderError("configure", cause);
 					diagnostic?.trace("openfort.configure", {
 						ok: false,
-						failure_mode: openfortFailureMode(error)
+						...openfortFailureDetail(error)
 					});
 					throw error;
 				}
@@ -495,11 +714,12 @@ function makeWalletReadyCycle(input) {
 				step("get");
 			} catch (cause) {
 				if (!isStaleUserSignal(cause)) {
+					const error = openfortProviderError("get", cause);
 					diagnostic?.trace("openfort.get", {
 						ok: false,
-						failure_mode: "unknown"
+						...openfortFailureDetail(error)
 					});
-					throw openfortProviderError("get", cause);
+					throw error;
 				}
 				diagnostic?.trace("openfort.get", {
 					ok: false,
@@ -521,16 +741,18 @@ function makeWalletReadyCycle(input) {
 /**
 * Sign once; when Openfort reports the signer not ready, reset readiness, run
 * one fresh readiness cycle and sign again. A rejection by the person is never
-* retried, and a second not-ready answer is a named `signer-not-ready` failure.
+* retried. A failure the readiness cycle already named (a mode, or an answer
+* Capxul cannot use) is thrown as itself; any other second failure is a named
+* `signer-not-ready` failure.
 */
 function recoveringSign(input) {
 	return async (hash) => {
 		try {
 			return await input.sign(hash);
 		} catch (cause) {
-			const providerErrorCode = openfortSignerNotReadyCode(cause);
+			const signerNotReadyCode = openfortSignerNotReadyCode(cause);
 			const normalized = signerFailure("openfort-embedded", "signUserOpHash", cause);
-			if (normalized.code === "SIGNER_REJECTED" || providerErrorCode === void 0) throw normalized;
+			if (normalized.code === "SIGNER_REJECTED" || signerNotReadyCode === void 0) throw normalized;
 			input.diagnostic?.trace("openfort.signerRecovery", {
 				outcome: "started",
 				attempt: 1,
@@ -549,23 +771,44 @@ function recoveringSign(input) {
 			} catch (retryCause) {
 				const retryFailure = signerFailure("openfort-embedded", "signUserOpHash", retryCause);
 				if (retryFailure.code === "SIGNER_REJECTED") throw retryFailure;
+				const named = namedReadinessFailure(retryCause);
+				if (named !== void 0) {
+					input.diagnostic?.trace("openfort.signerRecovery", {
+						outcome: "failed",
+						attempt: 1,
+						...openfortFailureDetail(named)
+					});
+					throw named;
+				}
 				if (isSignerNotReadySignal(retryCause)) input.markUnavailable();
 				input.diagnostic?.trace("openfort.signerRecovery", {
 					outcome: "failed",
 					attempt: 1,
 					failure_mode: isSignerNotReadySignal(retryCause) ? "signer-not-ready" : "unknown"
 				});
-				throw Errors.providerError("openfort", "signerRecovery", retryCause, {
-					failure_mode: "signer-not-ready",
+				throw Errors.providerUnavailable({
+					provider: "openfort",
+					operation: "signerRecovery",
+					mode: "signer-not-ready",
+					cause: retryCause,
 					details: {
 						provider_error_source: "openfort",
-						provider_error_code: providerErrorCode
+						provider_error_code: signerNotReadyCode
 					}
 				});
 			}
 		}
 	};
 }
+/**
+* A failure the readiness cycle already named: an answer Capxul cannot use, or
+* a provider failure with a mode other than `signer-not-ready`.
+*/
+function namedReadinessFailure(cause) {
+	if (!(cause instanceof CapxulError)) return void 0;
+	if (cause.code === "PROVIDER_RESPONSE_INVALID") return cause;
+	return cause.code === "PROVIDER_ERROR" && cause.mode !== void 0 && cause.mode !== "signer-not-ready" ? cause : void 0;
+}
 //#endregion
 //#region src/signing/openfort-browser.ts
 function isolatedDiagnostic(diagnostic) {
@@ -688,11 +931,12 @@ function createOpenfortBrowserSignerFromBootstrap(bootstrap, options = {}) {
 				});
 				return address;
 			} catch (cause) {
+				const error = openfortProviderError("getAddress", cause);
 				diagnostic?.trace("openfort.address", {
 					ok: false,
-					failure_mode: "unknown"
+					...openfortFailureDetail(error)
 				});
-				throw openfortProviderError("getAddress", cause);
+				throw error;
 			}
 		},
 		resetSession: resetReadiness
@@ -762,8 +1006,8 @@ function readSessionEmail(storage) {
 	let session;
 	try {
 		session = JSON.parse(raw);
-	} catch {
-		throw new Error("devPrivateKeySigner: cached session is not valid JSON");
+	} catch (cause) {
+		throw new Error("devPrivateKeySigner: cached session is not valid JSON", { cause });
 	}
 	if (session === null) throw new Error("devPrivateKeySigner: cached session is not valid JSON");
 	const email = readField(session, "email");
@@ -970,8 +1214,10 @@ const EngineeringTelemetryBootstrapPolicy = Schema.Struct({
 *
 * - `protocol`: discriminator that lets future protocols coexist on the
 *   same endpoint without a wire-shape conflict.
-* - `version`: numeric version inside the protocol. Unknown versions MUST
-*   fail decode with an INVALID_INPUT-class `CapxulError` at the SDK seam.
+* - `version`: numeric version inside the protocol. An unknown or missing
+*   version MUST fail decode at the SDK seam as `PROVIDER_RESPONSE_INVALID`
+*   (ADR-0039 D3) on field `version`, with problem `invalid` or `missing`:
+*   the backend answered, and Capxul cannot use the answer.
 * - `state`: the resolved bootstrap payload. Field shape matches the
 *   `BootstrapResolution` port; the SDK consumer can pass `state`
 *   directly (after `normalizeRuntimeUrl` on the two URL fields) into
@@ -1001,11 +1247,13 @@ const BootstrapEnvelope = Schema.Struct({
 //#endregion
 //#region src/applications/bootstrap-envelope.ts
 /**
-* Decode a bootstrap body. A body the envelope refuses throws INVALID_INPUT
-* (#119 AC1): unknown `version` literals, missing fields and brand-rule
-* failures all land there. The engineering telemetry policy decodes on its
-* own, so a policy the SDK does not admit turns SDK telemetry off instead of
-* failing the bootstrap.
+* Decode a bootstrap body. The backend answered, so a body the envelope
+* refuses is the backend's answer that Capxul cannot use, not the caller's
+* input: it throws PROVIDER_RESPONSE_INVALID (ADR-0039 D3), named by the first
+* field that fails. Unknown `version` literals, missing fields, brand-rule
+* failures and runtime URLs that are not http or https all land there. The
+* engineering telemetry policy decodes on its own, so a policy the SDK does
+* not admit turns SDK telemetry off instead of failing the bootstrap.
 */
 function decodeBootstrapBody(body) {
 	const state = readField(body, "state");
@@ -1014,7 +1262,7 @@ function decodeBootstrapBody(body) {
 		...body,
 		state: withoutPolicy(state)
 	} : body);
-	if (Result.isFailure(decoded)) throw Errors.invalidInput("bootstrapEnvelope", SchemaIssue.makeFormatterDefault()(decoded.failure));
+	if (Result.isFailure(decoded)) throw refusedEnvelope(decoded.failure);
 	const { state: decodedState } = decoded.success;
 	const decodedEngineeringTelemetry = rawEngineeringTelemetry === void 0 ? void 0 : SchemaParser.decodeUnknownResult(EngineeringTelemetryBootstrapPolicy)(rawEngineeringTelemetry, { onExcessProperty: "error" });
 	return {
@@ -1033,6 +1281,40 @@ function decodeBootstrapBody(body) {
 		...engineeringTelemetryOf(decodedEngineeringTelemetry)
 	};
 }
+const MISSING = "missing";
+const WRONG_TYPE = "not the expected type";
+/**
+* The envelope's Schema issues, each with a fixed reason. The Schema's own
+* message can quote the body, and the body holds the session token.
+*/
+const envelopeIssues = SchemaIssue.makeFormatterStandardSchemaV1({
+	leafHook: (issue) => issue._tag === "MissingKey" ? MISSING : WRONG_TYPE,
+	checkHook: () => WRONG_TYPE
+});
+/**
+* A body the envelope refuses, named by the path of the first field that
+* fails, or `body` when the whole body has the wrong shape.
+*/
+function refusedEnvelope(issue) {
+	const first = envelopeIssues(issue).issues[0];
+	const path = first?.path?.map((segment) => String(typeof segment === "object" ? segment.key : segment)) ?? [];
+	const missing = first?.message === MISSING;
+	return unusableAnswer(path.length === 0 ? "body" : path.join("."), missing ? "missing" : "invalid", missing ? MISSING : WRONG_TYPE);
+}
+/**
+* The bootstrap answered, and Capxul cannot use `field` of its answer. `cause`
+* is what refused the field, when it holds none of the body.
+*/
+function unusableAnswer(field, problem, reason, cause) {
+	return Errors.providerResponseInvalid({
+		provider: "convex",
+		operation: "bootstrap",
+		field,
+		problem,
+		reason,
+		...cause === void 0 ? {} : { cause }
+	});
+}
 /** The bootstrap state without the policy, which decodes separately. */
 function withoutPolicy(state) {
 	const { engineeringTelemetry: _policy, ...rest } = state;
@@ -1052,10 +1334,10 @@ function normalizeRuntimeUrl(field, raw) {
 	let parsed;
 	try {
 		parsed = new URL(raw);
-	} catch {
-		throw Errors.invalidInput(field, "must be an http or https URL");
+	} catch (cause) {
+		throw unusableAnswer(`state.${field}`, "invalid", "must be an http or https URL", cause);
 	}
-	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw Errors.invalidInput(field, "must be an http or https URL");
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw unusableAnswer(`state.${field}`, "invalid", "must be an http or https URL");
 	return parsed.toString().replace(/\/$/, "");
 }
 //#endregion
@@ -1166,8 +1448,14 @@ var HttpBootstrapAdapter = class {
 				return resolution;
 			},
 			catch: (cause) => {
-				if (cause instanceof CapxulError && cause.code === "INVALID_INPUT") return bootstrapErrorFromCapxul("invalidInput", cause);
-				return bootstrapErrorFromCapxul("malformedBody", Errors.providerError("convex", "bootstrap", cause instanceof Error ? cause : new Error(String(cause))));
+				if (cause instanceof CapxulError && cause.code === "PROVIDER_RESPONSE_INVALID") return bootstrapErrorFromCapxul("malformedBody", cause);
+				return bootstrapErrorFromCapxul("malformedBody", Errors.providerResponseInvalid({
+					provider: "convex",
+					operation: "bootstrap",
+					field: "body",
+					problem: "invalid",
+					cause
+				}));
 			}
 		});
 		return Effect.promise(() => safeText(res)).pipe(Effect.flatMap((body) => {
@@ -1182,7 +1470,9 @@ var HttpBootstrapAdapter = class {
 				...edgeRequestId === void 0 ? {} : { edgeRequestId }
 			};
 			if (res.status === 401) return Effect.fail(bootstrapErrorFromCapxul("notAuthenticated", keyRefused(input, evidence)));
-			return Effect.fail(bootstrapErrorFromCapxul("provider", Errors.providerError("convex", "bootstrap", /* @__PURE__ */ new Error(`HTTP ${res.status}${edgeError === void 0 ? "" : ` ${edgeError}`}`), {
+			return Effect.fail(bootstrapErrorFromCapxul("provider", providerStatusFailure({
+				provider: "convex",
+				operation: "bootstrap",
 				httpStatus: res.status,
 				details: evidence
 			})));
@@ -1372,43 +1662,23 @@ function makeIdentityMethods(deps) {
 			return toCapxulResult(loadIdentityProgram, identityDepsContext(deps), deps.runPromise);
 		},
 		async completeProfile(profile, options) {
-			if (options?.signal?.aborted) return {
-				ok: false,
-				error: Errors.cancelled({ operation: onboardings.complete.name })
-			};
-			if (typeof profile !== "object" || profile === null || typeof profile.displayName !== "string" || typeof profile.country !== "string" || typeof profile.handle !== "string") return {
-				ok: false,
-				error: Errors.invalidInput("profile", "invalid profile")
-			};
+			const refuse = (error) => runCapxulEffect(Effect.fail(error), options, onboardings.complete.name, deps.runPromise);
+			if (options?.signal?.aborted) return refuse(Errors.cancelled({ operation: onboardings.complete.name }));
+			if (typeof profile !== "object" || profile === null || typeof profile.displayName !== "string" || typeof profile.country !== "string" || typeof profile.handle !== "string") return refuse(Errors.invalidInput("profile", "invalid profile"));
 			const displayName = profile.displayName.trim();
 			const handle = profile.handle.trim();
-			if (displayName.length === 0) return {
-				ok: false,
-				error: Errors.invalidInput("displayName", "must not be empty")
-			};
-			if (handle.length === 0) return {
-				ok: false,
-				error: Errors.invalidInput("handle", "must not be empty")
-			};
+			if (displayName.length === 0) return refuse(Errors.invalidInput("displayName", "must not be empty"));
+			if (handle.length === 0) return refuse(Errors.invalidInput("handle", "must not be empty"));
 			let country;
 			try {
 				country = toCountryCode(profile.country);
-			} catch {
-				return {
-					ok: false,
-					error: Errors.invalidInput("country", "unsupported country")
-				};
+			} catch (cause) {
+				return refuse(Errors.invalidInput("country", "unsupported country", cause));
 			}
 			const carried = checkProfileCarriage(profile);
-			if (!carried.ok) return {
-				ok: false,
-				error: Errors.invalidInput(carried.field, carried.message)
-			};
+			if (!carried.ok) return refuse(Errors.invalidInput(carried.field, carried.message));
 			const session = deps.actor?.authSession();
-			if (session === void 0 || session === null) return {
-				ok: false,
-				error: Errors.notAuthenticated()
-			};
+			if (session === void 0 || session === null) return refuse(noSessionError(deps.actor));
 			return runPortEffect(deps.identityPort.completeOnboarding({
 				authUserId: session.authUserId,
 				email: session.email,
@@ -1597,10 +1867,10 @@ function normalizeOrganization(input) {
 	let country;
 	try {
 		country = toCountryCode(input.country);
-	} catch {
+	} catch (cause) {
 		return {
 			ok: false,
-			error: Errors.invalidInput("country", "must be an ISO country code")
+			error: Errors.invalidInput("country", "must be an ISO country code", cause)
 		};
 	}
 	const bio = input.bio?.trim() ?? "";
@@ -2242,7 +2512,43 @@ const OBSERVED_CONVEX_MUTATIONS = new Set(OPERATIONS.filter((row) => row.kind ==
 * id. The WebSocket client wraps it as `[CONVEX Q(path)] … Called by client`.
 */
 const REDACTED_ERROR = /^(?:\[CONVEX [QMA?]\([^)]*\)\] )?\[Request ID: ([^\]\s]+)\] Server Error(?:\s+Called by client)?$/u;
-function mapToCapxulError(operation, err, transport) {
+/** Whole milliseconds since `startedAt`, a `performance.now()` reading at the call's start. */
+function elapsedSince(startedAt) {
+	return Math.round(performance.now() - startedAt);
+}
+/**
+* Start one call's clock and return the mapper for its failure, so a redacted
+* refusal carries how long the call ran (CAP-387). `transportAtFailure` reads
+* the action's reconnect evidence when the call fails.
+*/
+function timedFailure(operation, transportAtFailure) {
+	const startedAt = performance.now();
+	return (err) => mapToConvexCallError(operation, err, elapsedSince(startedAt), transportAtFailure?.());
+}
+/**
+* A refusal for want of a session (`NOT_AUTHENTICATED`) from a call that ran
+* signed out because the auth provider failed to give the session's token:
+* the call fails with that token failure, its code, mode and class, and not as
+* a person who signed out (CAP-404). The refusal stays the cause.
+* `tokenFailure` is read only for such a refusal.
+*/
+function withTokenFailure(mapFailure, tokenFailure) {
+	return (err) => {
+		const refusal = mapFailure(err);
+		const reason = refusal.publicCode === "NOT_AUTHENTICATED" ? tokenFailure() : void 0;
+		if (reason === void 0) return refusal;
+		return new ConvexCallError({
+			operation: refusal.operation,
+			publicCode: reason.code,
+			publicError: reason,
+			cause: refusal,
+			tokenFailure: true,
+			...reason.details === void 0 ? {} : { details: reason.details }
+		});
+	};
+}
+/** `elapsedMs` is how long the call ran, from {@link elapsedSince}. */
+function mapToCapxulError(operation, err, elapsedMs, transport) {
 	const decoded = decodeConvexError(err);
 	if (decoded !== null) return decoded;
 	if (err instanceof CapxulError) return err;
@@ -2256,7 +2562,7 @@ function mapToCapxulError(operation, err, transport) {
 		});
 	}
 	if (err instanceof Error && isTransportError(err)) return Errors.networkError(operation, err, { provider: "convex" });
-	return backendFailure(operation, err);
+	return backendFailure(operation, err, elapsedMs);
 }
 /**
 * A failure the backend raised outside its own error boundary: Convex
@@ -2273,7 +2579,7 @@ function mapToCapxulError(operation, err, transport) {
 * the reply says where to look instead. The text matches stay for a backend
 * that does not redact (development, local).
 */
-function backendFailure(operation, err) {
+function backendFailure(operation, err, elapsedMs) {
 	const text = err instanceof Error ? err.message : String(err);
 	const redacted = REDACTED_ERROR.exec(text.trim())?.[1];
 	if (redacted !== void 0) return new CapxulError("UNKNOWN", `The backend refused ${operation} and gave no detail. Find Convex request ${redacted} in the backend logs. If the backend can be newer than this client, update the CLI or SDK.`, {
@@ -2283,7 +2589,8 @@ function backendFailure(operation, err) {
 			operation,
 			provider: "convex",
 			requestId: redacted,
-			reason: "backend-error-redacted"
+			reason: "backend-error-redacted",
+			...elapsedMs === void 0 ? {} : { elapsed_ms: elapsedMs }
 		}
 	});
 	const requestId = /\[Request ID: ([^\]\s]+)\]/u.exec(text)?.[1];
@@ -2318,8 +2625,8 @@ function backendFailure(operation, err) {
 		details: where
 	});
 }
-function mapToConvexCallError(operation, err, transport) {
-	return convexCallErrorFromCapxul(operation, mapToCapxulError(operation, err, transport), transport);
+function mapToConvexCallError(operation, err, elapsedMs, transport) {
+	return convexCallErrorFromCapxul(operation, mapToCapxulError(operation, err, elapsedMs, transport), transport);
 }
 function logActionTransportFailure(operation, error) {
 	if (error.transport === void 0) return Effect.void;
@@ -2399,9 +2706,13 @@ function observedConvexArgs(input) {
 /**
 * Subscribe one query, and the connection state when the caller asks for it.
 * The returned stop always finishes, and a callback never runs after it.
+* `tokenFailure` says why the socket runs signed out, when the auth provider
+* failed to give a token; a refusal for want of a session reports it instead
+* (CAP-404).
 */
 function subscribeConvexQuery(client, fn, args, callback, options) {
 	const path = getFunctionName(fn);
+	let startedAt = performance.now();
 	let active = true;
 	let unsubscribeQuery;
 	let unsubscribeConnection;
@@ -2422,6 +2733,7 @@ function subscribeConvexQuery(client, fn, args, callback, options) {
 			const observe = (state) => {
 				if (!active || previous === state.isWebSocketConnected) return;
 				previous = state.isWebSocketConnected;
+				if (previous) startedAt = performance.now();
 				try {
 					options.onConnectionChange?.(previous);
 				} catch {}
@@ -2430,15 +2742,21 @@ function subscribeConvexQuery(client, fn, args, callback, options) {
 			observe(client.connectionState());
 		}
 		unsubscribeQuery = client.onUpdate(fn, args, (value) => {
+			startedAt = void 0;
 			if (active) callback({
 				status: "ok",
 				value
 			});
 		}, (err) => {
-			if (active) callback({
-				status: "error",
-				error: mapToCapxulError(path, err)
-			});
+			const elapsedMs = startedAt === void 0 ? void 0 : elapsedSince(startedAt);
+			startedAt = void 0;
+			if (active) {
+				const error = mapToCapxulError(path, err, elapsedMs);
+				callback({
+					status: "error",
+					error: (error.code === "NOT_AUTHENTICATED" ? options?.tokenFailure?.() : void 0) ?? error
+				});
+			}
 		});
 		if (!active) unsubscribeQuery();
 		return stop;
@@ -2448,13 +2766,7 @@ function subscribeConvexQuery(client, fn, args, callback, options) {
 	}
 }
 //#endregion
-//#region src/platform/transport/convex-adapter.ts
-/**
-* A socket that has not emitted `close` within this window is not going to.
-* ponytail: one fixed bound; `closeTimeoutMs` is the knob if a slow runtime
-* ever needs a different one.
-*/
-const DEFAULT_CLOSE_TIMEOUT_MS = 5e3;
+//#region src/platform/transport/convex-socket-auth.ts
 /**
 * The fetcher the Convex client's auth handshake gets. Convex first asks for
 * "a possibly cached token" (`forceRefreshToken: false`) and, as soon as the
@@ -2472,6 +2784,94 @@ const DEFAULT_CLOSE_TIMEOUT_MS = 5e3;
 function freshTokenHandshake(fetchToken) {
 	return async (args) => args.forceRefreshToken ? fetchToken(args) : null;
 }
+/**
+* The socket's session: each auth handshake the adapter starts, and the
+* failure in the latest token answer. Convex runs a call signed out when the
+* auth provider gives no token, so that failure, not the backend's refusal for
+* want of a session, says why the call failed (CAP-404).
+*/
+var ConvexSocketAuth = class {
+	#client;
+	#tokenProvider;
+	/** Counts the handshakes. An answer to an older one changes nothing. */
+	#handshake = 0;
+	/** The failure in the latest token answer, and the handshake that asked for it. */
+	#failure;
+	constructor(client, tokenProvider) {
+		this.#client = client;
+		this.#tokenProvider = tokenProvider;
+	}
+	/**
+	* The session changed: the last session's failure explains no refusal now,
+	* and Convex asks for the new session's token.
+	*/
+	handshake() {
+		this.#failure = void 0;
+		this.#ask();
+	}
+	/** Start a handshake: Convex asks for the session's token again. */
+	#ask() {
+		const handshake = ++this.#handshake;
+		this.#client.setAuth(freshTokenHandshake(async (args) => {
+			const answer = await this.#tokenProvider(args);
+			if (handshake === this.#handshake) this.#failure = answer instanceof CapxulError ? {
+				failure: answer,
+				handshake
+			} : void 0;
+			return answer instanceof CapxulError ? null : answer;
+		}));
+	}
+	/**
+	* Why a call on the socket ran signed out: the failure in the latest token
+	* answer, or none when the provider gave a token or refused the session.
+	* Convex asks for a token again only when the session changes, so the first
+	* refusal after each failed answer starts a new handshake, and a later call
+	* runs as the session once the provider answers.
+	*/
+	signedOutBecause() {
+		const latest = this.#failure;
+		if (latest === void 0) return void 0;
+		if (latest.handshake === this.#handshake) this.#ask();
+		return latest.failure;
+	}
+};
+//#endregion
+//#region src/platform/transport/convex-fresh-query.ts
+/**
+* One query read past the client's cache, over HTTP with its own token. When
+* the auth provider gave no token, the read runs signed out, and a refusal for
+* want of a session reports that token failure instead (CAP-404).
+*/
+function freshQuery(deps, fn, args, path) {
+	let tokenFailure;
+	return Effect.tryPromise({
+		try: async (signal) => {
+			const observed = args();
+			const token = await deps.tokenProvider?.({ forceRefreshToken: false });
+			if (signal.aborted) throw Errors.cancelled({ operation: path });
+			const client = new ConvexHttpClient(deps.convexUrl, {
+				logger: deps.logger,
+				fetch: (input, init) => globalThis.fetch(input, {
+					...init,
+					signal
+				})
+			});
+			if (token instanceof CapxulError) tokenFailure = token;
+			else if (typeof token === "string") client.setAuth(token);
+			const query = fn;
+			return client.query(query, observed);
+		},
+		catch: withTokenFailure(timedFailure(path), () => tokenFailure)
+	});
+}
+//#endregion
+//#region src/platform/transport/convex-adapter.ts
+/**
+* A socket that has not emitted `close` within this window is not going to.
+* ponytail: one fixed bound; `closeTimeoutMs` is the knob if a slow runtime
+* ever needs a different one.
+*/
+const DEFAULT_CLOSE_TIMEOUT_MS = 5e3;
 /** Run a Convex call under the current trace parent, when there is one. */
 const withTraceparent = (run) => Effect.flatMap(Effect.serviceOption(Tracer.ParentSpan), (parent) => run(parent._tag === "Some" ? formatTraceparent(parent.value) : void 0));
 var ConvexCallAdapter = class {
@@ -2479,6 +2879,7 @@ var ConvexCallAdapter = class {
 	#convexUrl;
 	#logger;
 	#tokenProvider;
+	#socketAuth;
 	#applicationId;
 	#observation;
 	#connectionMonitor;
@@ -2494,12 +2895,13 @@ var ConvexCallAdapter = class {
 			logger: this.#logger
 		});
 		this.#tokenProvider = deps.tokenProvider;
+		this.#socketAuth = deps.tokenProvider === void 0 ? void 0 : new ConvexSocketAuth(this.#client, deps.tokenProvider);
 		this.#applicationId = deps.applicationId;
 		this.#observation = deps.observation;
 		this.refreshAuth();
 	}
 	refreshAuth() {
-		if (this.#tokenProvider) this.#client.setAuth(freshTokenHandshake(this.#tokenProvider));
+		this.#socketAuth?.handshake();
 	}
 	observeConnection(observer) {
 		return this.#connectionMonitor.observe(this.#client, observer);
@@ -2507,35 +2909,24 @@ var ConvexCallAdapter = class {
 	query(fn, args, options) {
 		const path = getFunctionName(fn);
 		return withTraceparent((traceparent) => {
+			const observed = () => this.#observedArgs(OBSERVED_CONVEX_QUERIES, path, args, traceparent);
+			if (options?.fresh === true) return freshQuery({
+				convexUrl: this.#convexUrl,
+				logger: this.#logger,
+				tokenProvider: this.#tokenProvider
+			}, fn, observed, path);
 			return Effect.tryPromise({
-				try: (signal) => {
-					const observed = this.#observedArgs(OBSERVED_CONVEX_QUERIES, path, args, traceparent);
-					return options?.fresh === true ? this.#freshQuery(fn, observed, signal, path) : this.#client.query(fn, observed);
-				},
-				catch: (cause) => mapToConvexCallError(path, cause)
+				try: () => this.#client.query(fn, observed()),
+				catch: withTokenFailure(timedFailure(path), () => this.#socketAuth?.signedOutBecause())
 			});
 		});
 	}
-	async #freshQuery(fn, args, signal, path) {
-		const token = await this.#tokenProvider?.({ forceRefreshToken: false });
-		if (signal.aborted) throw Errors.cancelled({ operation: path });
-		const client = new ConvexHttpClient(this.#convexUrl, {
-			logger: this.#logger,
-			fetch: (input, init) => globalThis.fetch(input, {
-				...init,
-				signal
-			})
-		});
-		if (token !== void 0 && token !== null) client.setAuth(token);
-		const query = fn;
-		return client.query(query, args);
-	}
 	mutation(fn, args) {
 		const path = getFunctionName(fn);
 		return withTraceparent((traceparent) => {
 			return Effect.tryPromise({
 				try: () => this.#client.mutation(fn, this.#observedArgs(OBSERVED_CONVEX_MUTATIONS, path, args, traceparent)),
-				catch: (cause) => mapToConvexCallError(path, cause)
+				catch: withTokenFailure(timedFailure(path), () => this.#socketAuth?.signedOutBecause())
 			});
 		});
 	}
@@ -2545,10 +2936,7 @@ var ConvexCallAdapter = class {
 			const connectionAtStart = connectionState(this.#client);
 			return Effect.tryPromise({
 				try: () => this.#client.action(fn, this.#observedArgs(OBSERVED_CONVEX_ACTIONS, path, args, traceparent)),
-				catch: (cause) => {
-					const transport = this.#connectionMonitor.reconnectEvidence(connectionAtStart, connectionState(this.#client));
-					return mapToConvexCallError(path, cause, transport);
-				}
+				catch: withTokenFailure(timedFailure(path, () => this.#connectionMonitor.reconnectEvidence(connectionAtStart, connectionState(this.#client))), () => this.#socketAuth?.signedOutBecause())
 			}).pipe(Effect.tapError((error) => logActionTransportFailure(path, error)));
 		});
 	}
@@ -2571,7 +2959,10 @@ var ConvexCallAdapter = class {
 	}
 	subscribe(fn, args, callback, options) {
 		return Effect.try({
-			try: () => subscribeConvexQuery(this.#client, fn, args, callback, options),
+			try: () => subscribeConvexQuery(this.#client, fn, args, callback, {
+				...options,
+				tokenFailure: () => this.#socketAuth?.signedOutBecause()
+			}),
 			catch: (cause) => mapToConvexCallError(getFunctionName(fn), cause)
 		}).pipe(Effect.tap(() => Effect.sync(() => {
 			callback({ status: "loading" });
@@ -2717,13 +3108,14 @@ function cloneGroupInput(input) {
 //#endregion
 //#region src/observability/telemetry/from-posthog.ts
 /**
-* Drop props that must never cross to a host-owned external sink. Today that is
-* the `$exception` `details` blob: `captureException` serializes
-* `CapxulError.details` (e.g. `{ asset, available, required }`, `{ name }`,
-* `{ accountId }` — errors.ts) into it, and the shared redactor has no
-* `$exception` rule, so it is stripped here at the boundary (infra#1037). The
-* safe fields (error code, operation, failure_mode, the fixed leak-safe message,
-* stack frames) are preserved.
+* Drop a `details` prop before it crosses to the host-owned sink.
+* `CapxulError.details` can hold amounts, names and account IDs (e.g.
+* `{ asset, available, required }`), and the shared redactor has no
+* `$exception` rule (infra#1037). `captureException` does not send that prop:
+* it sends the allow-listed detail as top-level keys and as `error_details`.
+* The strip drops only a top-level `details` key. It does not read
+* `error_details`, where `bootstrap_failed` puts the masked `details` object
+* (`failureEvidenceProps`).
 */
 function stripHostUnsafeProps(props) {
 	if (props === void 0) return void 0;
@@ -2731,10 +3123,6 @@ function stripHostUnsafeProps(props) {
 	return safe;
 }
 /**
-* The subset of a posthog-js client the seam calls. `identify` / `group` /
-* `reset` are optional — a host that only wants event capture can omit them.
-*/
-/**
 * Adapt the host's already-initialized posthog-like client into a
 * `TelemetryPort` for the `telemetry` prop / input. This port SUPPLANTS the
 * SDK's no-op default telemetry sink (`production.ts` binds it via
@@ -2806,6 +3194,7 @@ function postHogObservability(client, options = {}) {
 	const policy = {
 		client,
 		capxulEnv: options.capxulEnv ?? "unknown",
+		...options.failureCapture === void 0 ? {} : { failureCapture: options.failureCapture },
 		snapshot,
 		deliver: (capture) => {
 			try {
@@ -2858,6 +3247,20 @@ function hostEngineeringPolicy(observability) {
 	};
 }
 //#endregion
+//#region ../observability/src/delivery/budget.ts
+/** Fixed admission limits for one CLI invocation and its SDK client. */
+const CLI_ENGINEERING_LIMITS = Object.freeze({
+	records: 80,
+	ordinaryRecords: 64,
+	recordBytes: 16384,
+	recordFields: 48,
+	requests: 5,
+	ordinaryRequests: 2,
+	requestBytes: 1572864,
+	metricSeries: 16,
+	requestTimeoutMs: 1e3
+});
+//#endregion
 //#region ../observability/src/delivery/admission.ts
 function newDeliveryState(budget, ownsMetrics) {
 	return {
@@ -2901,7 +3304,7 @@ function closeDelivery(state) {
 	if (state.ownsMetrics) state.budget.metricRegistry.clear();
 }
 const text = (value) => typeof value === "string" ? value.slice(0, 128) : "capxul.engineering";
-const attributes = (input, limit = 32) => {
+const attributes = (input, limit = CLI_ENGINEERING_LIMITS.recordFields) => {
 	const out = {};
 	let count = 0;
 	let bytes = 0;
@@ -2938,8 +3341,20 @@ const failureText = (failure, key, limit, source) => {
 		return;
 	}
 };
+/**
+* A `CapxulError` reads as its failure row reads (`maskedMessage`), so a
+* factory message keeps the word after its field name (CAP-427). The row
+* reads the same error, so the exporter reads nothing more than the row does.
+*/
+const capxulMessage = (failure, source) => {
+	try {
+		return isCapxulError(failure) ? maskedMessage(failure, source).slice(0, 2048) : void 0;
+	} catch {
+		return;
+	}
+};
 const exportFailure = (failure, source) => {
-	const message = failureText(failure, "message", 2048, source) ?? (typeof failure === "string" ? redactSecrets(failure, source).slice(0, 2048) : "Engineering operation failed");
+	const message = capxulMessage(failure, source) ?? failureText(failure, "message", 2048, source) ?? (typeof failure === "string" ? redactSecrets(failure, source).slice(0, 2048) : "Engineering operation failed");
 	const code = failureText(failure, "code", 128);
 	const error = new Error((code === void 0 ? message : `${message} [code=${code}]`).slice(0, 2048));
 	error.name = failureText(failure, "_tag", 128) ?? failureText(failure, "name", 128) ?? "Error";
@@ -3090,7 +3505,10 @@ function admittedTracer(state, delegate) {
 		...delegate.context === void 0 ? {} : { context: delegate.context.bind(delegate) }
 	});
 }
-/** The span as a producer sees it: at most 32 fields and 2000 attribute bytes, 2 events, 2 links. */
+/**
+* The span as a producer sees it: at most `recordFields` fields and 2000
+* attribute bytes, 2 events, 2 links.
+*/
 function boundedSpan(state, span) {
 	const { budget } = state;
 	const wrapped = inheritSpan(span);
@@ -3098,7 +3516,7 @@ function boundedSpan(state, span) {
 	let ended = false;
 	Object.defineProperties(wrapped, {
 		attribute: { value: (key, value) => {
-			if (fields >= 32 && !span.attributes.has(key)) {
+			if (fields >= CLI_ENGINEERING_LIMITS.recordFields && !span.attributes.has(key)) {
 				budget.drop();
 				return;
 			}
@@ -3147,19 +3565,6 @@ function boundedSpan(state, span) {
 	return wrapped;
 }
 //#endregion
-//#region ../observability/src/delivery/budget.ts
-/** Fixed admission limits for one CLI invocation and its SDK client. */
-const CLI_ENGINEERING_LIMITS = Object.freeze({
-	records: 80,
-	ordinaryRecords: 64,
-	recordBytes: 16384,
-	requests: 5,
-	ordinaryRequests: 2,
-	requestBytes: 1572864,
-	metricSeries: 16,
-	requestTimeoutMs: 1e3
-});
-//#endregion
 //#region ../observability/src/delivery/requests.ts
 function admittedSerialization(state, delegate) {
 	return {
@@ -3307,8 +3712,8 @@ const validateEngineeringTelemetryConfig = (config) => {
 	let url;
 	try {
 		url = new URL(config.host);
-	} catch {
-		throw new TypeError("engineering telemetry host must be an absolute HTTPS URL");
+	} catch (cause) {
+		throw new TypeError("engineering telemetry host must be an absolute HTTPS URL", { cause });
 	}
 	if (url.protocol !== "https:" || url.username.length > 0 || url.password.length > 0 || url.pathname !== "/" || url.search.length > 0 || url.hash.length > 0 || !(url.hostname === "posthog.com" || url.hostname.endsWith(".posthog.com"))) throw new TypeError("engineering telemetry host must be a credential-free HTTPS origin");
 	if (!ENGINEERING_CAPXUL_ENV_SET.has(config.capxulEnv)) throw new TypeError("engineering telemetry capxulEnv is not canonical");
@@ -3368,7 +3773,8 @@ const MINIMAL_CORRELATIONS = /* @__PURE__ */ new Set([
 	"correlation_id",
 	"journey_id",
 	"invocation_id",
-	"posthogDistinctId"
+	"posthogDistinctId",
+	"failure_correlation_id"
 ]);
 const MINIMAL_METRIC_LABELS = /* @__PURE__ */ new Set([
 	"command",
@@ -3381,6 +3787,12 @@ const MINIMAL_METRIC_LABELS = /* @__PURE__ */ new Set([
 const MINIMAL_METRIC_NAMES = /* @__PURE__ */ new Set(["capxul.cli.command.count", "capxul.cli.command.duration"]);
 const traceId = (value) => typeof value === "string" && /^(?!0+$)[0-9a-f]{32}$/u.test(value);
 const spanId = (value) => typeof value === "string" && /^(?!0+$)[0-9a-f]{16}$/u.test(value);
+/**
+* A correlation id the minimal export carries: an identifier with no `/`, not
+* `0x` hex, and unchanged by the secret mask. The CLI quotes a backend
+* correlation id as its `ref` only when it passes, so the ref finds a row.
+*/
+const minimalCorrelationId = (value) => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(value) && !/^0x[0-9a-f]+$/iu.test(value) && redactSecrets(value) === value;
 const minimalName = (value) => typeof value === "string" && (MINIMAL_LOG_NAMES.has(value) || isCapxulOperation(value) || CLI_COMMAND_NAMES.some((command) => value === `cli.command.${command}`)) ? value : "capxul.engineering";
 const MINIMAL_ENUM_VALUES = /* @__PURE__ */ new Map([
 	["outcome", [
@@ -3392,6 +3804,8 @@ const MINIMAL_ENUM_VALUES = /* @__PURE__ */ new Map([
 	]],
 	["mode", FAILURE_MODES],
 	["failure_mode", FAILURE_MODES],
+	["failure_class", FAILURE_CLASSES],
+	["problem", PROVIDER_PROBLEMS],
 	["capxul_env", ENGINEERING_CAPXUL_ENVS],
 	["producer", ["browser", "server"]],
 	["command", CLI_COMMAND_NAMES],
@@ -3420,7 +3834,7 @@ const MINIMAL_ENUM_VALUES = /* @__PURE__ */ new Map([
 		"healStaleCache",
 		"walletReady"
 	]],
-	["provider", ["better-auth", "oidc"]],
+	["provider", [...PROVIDERS, "oidc"]],
 	["cli_identity_kind", ["anonymous", "identified"]],
 	["output_mode", ["human", "json"]],
 	["setup_status", ORGANIZATION_SETUP_STATUSES],
@@ -3439,25 +3853,36 @@ const MINIMAL_ENUM_VALUES = /* @__PURE__ */ new Map([
 const MINIMAL_CODE_KEYS = /* @__PURE__ */ new Set([
 	"error.code",
 	"error_code",
+	"error_kind",
 	"failure_code",
-	"refusal_code",
-	"capxul_error_code"
+	"refusal_code"
 ]);
 const MINIMAL_VERSION_KEYS = /* @__PURE__ */ new Set([
 	"sdk_version",
 	"cli_version",
 	"release"
 ]);
+/** The failure row's identifiers that the `none` text policy lets through (ADR-0039 D6). */
+const MINIMAL_FAILURE_IDENTIFIERS = /* @__PURE__ */ new Set([
+	"provider_operation",
+	"provider_code",
+	"field"
+]);
+/** What raised a failure: its layer (`convex`, `sdk`), and a CLI defect's error name. */
+const MINIMAL_FAILURE_ORIGINS = /* @__PURE__ */ new Set(["failure_layer", "failure_error_name"]);
 function minimalStringValue(key, text) {
 	if (key === "operation") return isCapxulOperation(text);
 	if (key === "organization_id") return /^org_[0-9A-Za-z]+$/u.test(text);
 	if (MINIMAL_CODE_KEYS.has(key)) return MINIMAL_ERROR_CODES.has(text);
 	if (MINIMAL_VERSION_KEYS.has(key)) return /^[A-Za-z0-9][A-Za-z0-9._+@-]{0,127}$/u.test(text);
+	if (MINIMAL_FAILURE_IDENTIFIERS.has(key)) return /^[A-Za-z0-9_][A-Za-z0-9_.:/[\]-]{0,127}$/u.test(text) && redactSecrets(text) === text;
+	if (MINIMAL_FAILURE_ORIGINS.has(key)) return /^[A-Za-z_][A-Za-z0-9_.-]{0,63}$/u.test(text) && redactSecrets(text) === text;
+	if (key === "request_id") return /^[0-9a-f]{16}$/u.test(text);
 	if (key === "trace_id") return traceId(text);
 	if (key === "span_id" || key === "parent_span_id") return spanId(text);
 	const values = MINIMAL_ENUM_VALUES.get(key);
 	if (values !== void 0) return values.includes(text);
-	return MINIMAL_CORRELATIONS.has(key) && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(text) && !/^0x[0-9a-f]+$/iu.test(text) && redactSecrets(text) === text;
+	return MINIMAL_CORRELATIONS.has(key) && minimalCorrelationId(text);
 }
 /** A named privacy projection, separate from the default credential-only redaction policy. */
 function minimalAttributes(attributes, metric = false) {
@@ -3816,8 +4241,8 @@ function normalizeHttpUrl(field, raw) {
 	let parsed;
 	try {
 		parsed = new URL(raw);
-	} catch {
-		throw Errors.invalidInput(field, "must be an http or https URL");
+	} catch (cause) {
+		throw Errors.invalidInput(field, "must be an http or https URL", cause);
 	}
 	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw Errors.invalidInput(field, "must be an http or https URL");
 	return parsed.toString().replace(/\/$/, "");
@@ -3865,8 +4290,9 @@ function productionConvexCallLayer(input, refreshConvexAuthRef) {
 				forceRefresh: forceRefreshToken,
 				...input.signal === void 0 ? {} : { signal: input.signal }
 			})));
-			if (Result.isFailure(tokenResult)) return null;
-			return String(tokenResult.success.token);
+			if (Result.isSuccess(tokenResult)) return String(tokenResult.success.token);
+			const failure = toPublicError(tokenResult.failure);
+			return failure.code === "NOT_AUTHENTICATED" ? null : failure;
 		}
 	}).pipe(Layer.flatMap((context) => {
 		const convexCall = Context.get(context, ConvexCallPortTag);
@@ -3987,10 +4413,10 @@ function validateCreateCapxulClientInput(input) {
 	const runtime = input.runtime ?? detectRuntime();
 	if (input.devToolsUrl !== void 0) try {
 		validateDevToolsUrl(input.devToolsUrl);
-	} catch {
+	} catch (cause) {
 		return {
 			ok: false,
-			error: Errors.invalidInput("devToolsUrl", "must be a local ws or wss URL without credentials")
+			error: Errors.invalidInput("devToolsUrl", "must be a local ws or wss URL without credentials", cause)
 		};
 	}
 	if (input.signer !== void 0 && input.openfortSignerFactory !== void 0) return {
@@ -4094,7 +4520,7 @@ async function createProductionAdapters(input) {
 				props: {
 					...bootstrapTelemetryEnvelope(input, resolvedInput.value),
 					reason: bootstrapResult.error.code,
-					...failureDetail(bootstrapResult.error),
+					...failureDetail$1(bootstrapResult.error),
 					...failureEvidenceProps(bootstrapResult.error)
 				}
 			});
@@ -4216,11 +4642,15 @@ function makeFinancialOpsMethods(deps) {
 }
 //#endregion
 //#region src/media/images.ts
-/** The upload POST failed: the storage provider, not the row, refused. */
-function uploadFailed(cause) {
+const UPLOAD = {
+	provider: "convex-storage",
+	operation: "uploadImage"
+};
+/** The upload POST failed: the storage provider, not the row, gave no usable answer. */
+function uploadFailed(error) {
 	return {
 		ok: false,
-		error: Errors.providerError("convex-storage", "uploadImage", cause)
+		error
 	};
 }
 /** The storage id the upload response names, if it names one. */
@@ -4239,23 +4669,51 @@ function makeMediaMethods(deps) {
 		async uploadImage(blob, options) {
 			const url = await call(images.generateUploadUrl, {}, options);
 			if (!url.ok) return url;
+			let response;
 			try {
-				const response = await fetchImpl(url.value.uploadUrl, {
+				response = await fetchImpl(url.value.uploadUrl, {
 					method: "POST",
 					headers: { "Content-Type": blob.type },
 					body: blob,
 					...options?.signal === void 0 ? {} : { signal: options.signal }
 				});
-				if (!response.ok) return uploadFailed(`upload failed with status ${response.status}`);
-				const storageId = storageIdOf(await response.json());
-				if (storageId === void 0) return uploadFailed("upload response carried no storageId");
-				return {
-					ok: true,
-					value: { storageId }
+			} catch (cause) {
+				if (options?.signal?.aborted === true) return {
+					ok: false,
+					error: Errors.cancelled({ operation: images.generateUploadUrl.name }, cause)
 				};
+				return uploadFailed(Errors.providerUnavailable({
+					...UPLOAD,
+					mode: "upstream-down",
+					cause
+				}));
+			}
+			if (!response.ok) return uploadFailed(providerStatusFailure({
+				...UPLOAD,
+				httpStatus: response.status
+			}));
+			let body;
+			try {
+				body = await response.json();
 			} catch (cause) {
-				return uploadFailed(cause);
+				return uploadFailed(Errors.providerResponseInvalid({
+					...UPLOAD,
+					field: "body",
+					problem: "invalid",
+					cause
+				}));
 			}
+			const storageId = storageIdOf(body);
+			if (storageId === void 0) return uploadFailed(Errors.providerResponseInvalid({
+				...UPLOAD,
+				field: "storageId",
+				problem: "missing",
+				reason: "upload response carried no storageId"
+			}));
+			return {
+				ok: true,
+				value: { storageId }
+			};
 		},
 		setProfileImage: (input, options) => call(images.setProfileImage, { storageId: input.storageId }, options),
 		setOrgLogo: (input, options) => call(images.setOrgLogo, {
@@ -4507,10 +4965,14 @@ function makeIdentityRuntime(actor, identityPort, runPromise) {
 				reason: "INVALID_INPUT"
 			};
 			const session = actor.authSession();
-			if (session === null) return {
-				ok: false,
-				reason: "NOT_AUTHENTICATED"
-			};
+			if (session === null) {
+				const error = noSessionError(actor);
+				return {
+					ok: false,
+					reason: error.code,
+					error
+				};
+			}
 			const result = await runPortEffect(identityPort.completeOnboarding({
 				authUserId: session.authUserId,
 				email: session.email,
@@ -4842,7 +5304,7 @@ function assembleCapxulClient(input) {
 		}),
 		close: () => closeClientResources(stopActor, effectRunner.runPromise)
 	};
-	return observeSdkClient(client, observation.failureObservation, observation.hostObservationSnapshot);
+	return observeSdkClient(client, observation.failureObservation, observation.hostObservationSnapshot, () => actor.authSession()?.authUserId);
 }
 //#endregion
 //#region src/observability/diagnostics/effect-log.ts
@@ -4912,6 +5374,23 @@ function resolveOpenfortProductionSigner(input) {
 }
 //#endregion
 //#region src/platform/production-client.ts
+/**
+* The signer's session reset, as the callback its two later callers run: the
+* sign-out wrapper (`resetSignerSessionOnSignOut`) and `close`. A failed reset
+* throws the typed signer failure, and each caller turns the throw into its
+* own failure. It lives outside the factory because the factory returns a
+* `CapxulResult` and must not throw. A signer with no session gives none.
+*/
+function signerSessionReset(signer) {
+	if (signer === void 0 || !("resetSession" in signer)) return void 0;
+	return () => {
+		try {
+			signer.resetSession();
+		} catch (cause) {
+			throw signerFailure(signer.source, "resetSession", cause);
+		}
+	};
+}
 /** Shared production composition. The normal factory passes no controls. */
 async function createCapxulClientWithSignerControls(input, controls) {
 	const invocationObservability = bindHostObservabilityInvocation(input.observability);
@@ -4948,16 +5427,8 @@ async function createCapxulClientWithSignerControls(input, controls) {
 			await adapters.value.close().catch(() => void 0);
 			return observeFailedResult(factoryChainFence, observation, "createCapxulClient");
 		}
-		if (signer !== void 0 && "resetSession" in signer) {
-			const { resetSession, source } = signer;
-			resetSignerSession.current = () => {
-				try {
-					resetSession();
-				} catch (cause) {
-					throw signerFailure(source, "resetSession", cause);
-				}
-			};
-		}
+		const resetSession = signerSessionReset(signer);
+		if (resetSession !== void 0) resetSignerSession.current = resetSession;
 		const effectRunner = {
 			runSync: Effect.runSyncWith(adapters.value.context),
 			runPromise: Effect.runPromiseWith(adapters.value.context)
@@ -4985,11 +5456,7 @@ async function createCapxulClientWithSignerControls(input, controls) {
 		}), adapters.value.close, effectRunner.runPromise);
 		const close = idempotentClose(async () => {
 			try {
-				if (signer !== void 0 && "resetSession" in signer) try {
-					signer.resetSession();
-				} catch (cause) {
-					throw signerFailure(signer.source, "resetSession", cause);
-				}
+				resetSession?.();
 			} finally {
 				await ownedClient._internal.close?.();
 			}