feat(platform): give AuthState::LoginFailed a typed kind

ios/truapi-host/Sources/TrUAPIHost/truapi_platform.swift

@@ -1370,6 +1370,10 @@ public enum AuthState: Equatable, Hashable {
      * The last login attempt failed; show the reason and offer a retry.
      */
     case loginFailed(
+        /**
+         * What kind of failure this was. Hosts branch on this and treat
+         * `reason` as display copy only.
+         */kind: LoginFailureKind,
         /**
          * Human-readable failure reason.
          */reason: String
@@ -1409,7 +1413,7 @@ public struct FfiConverterTypeAuthState: FfiConverterRustBuffer {
         case 3: return .connected(try FfiConverterTypeSessionUiInfo.read(from: &buf)
         )
 
-        case 4: return .loginFailed(reason: try FfiConverterString.read(from: &buf)
+        case 4: return .loginFailed(kind: try FfiConverterTypeLoginFailureKind.read(from: &buf), reason: try FfiConverterString.read(from: &buf)
         )
 
         case 5: return .authenticating
@@ -1436,8 +1440,9 @@ public struct FfiConverterTypeAuthState: FfiConverterRustBuffer {
             FfiConverterTypeSessionUiInfo.write(v1, into: &buf)
 
 
-        case let .loginFailed(reason):
+        case let .loginFailed(kind,reason):
             writeInt(&buf, Int32(4))
+            FfiConverterTypeLoginFailureKind.write(kind, into: &buf)
             FfiConverterString.write(reason, into: &buf)
 
 
@@ -1546,6 +1551,84 @@ public func FfiConverterTypeCreateTransactionReview_lower(_ value: CreateTransac
 
 
 
+/**
+ * Why a login attempt failed, for hosts that need to act on the cause rather
+ * than only display it.
+ */
+
+public enum LoginFailureKind: Equatable, Hashable {
+
+    /**
+     * The wallet has no free statement-store allowance slot for this period,
+     * so it cannot register the device. Deterministic until the period rolls
+     * over: retrying wastes the user's remaining budget.
+     */
+    case noFreeAllowanceSlots
+    /**
+     * Anything else. `reason` carries the detail.
+     */
+    case other
+
+
+
+
+
+}
+
+#if compiler(>=6)
+extension LoginFailureKind: Sendable {}
+#endif
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public struct FfiConverterTypeLoginFailureKind: FfiConverterRustBuffer {
+    typealias SwiftType = LoginFailureKind
+
+    public static func read(from buf: inout (data: Data, offset: Data.Index)) throws -> LoginFailureKind {
+        let variant: Int32 = try readInt(&buf)
+        switch variant {
+
+        case 1: return .noFreeAllowanceSlots
+
+        case 2: return .other
+
+        default: throw UniffiInternalError.unexpectedEnumCase
+        }
+    }
+
+    public static func write(_ value: LoginFailureKind, into buf: inout [UInt8]) {
+        switch value {
+
+
+        case .noFreeAllowanceSlots:
+            writeInt(&buf, Int32(1))
+
+
+        case .other:
+            writeInt(&buf, Int32(2))
+
+        }
+    }
+}
+
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public func FfiConverterTypeLoginFailureKind_lift(_ buf: RustBuffer) throws -> LoginFailureKind {
+    return try FfiConverterTypeLoginFailureKind.lift(buf)
+}
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public func FfiConverterTypeLoginFailureKind_lower(_ value: LoginFailureKind) -> RustBuffer {
+    return FfiConverterTypeLoginFailureKind.lower(value)
+}
+
+
+
 /**
  * Permission request whose authorization status can be inspected or updated
  * by host administration UI.

playground/tests/e2e/dotli-diagnosis.ts

@@ -319,9 +319,9 @@ async function waitForSignedIn(
   signingHost: SigningHostCliProcess,
 ): Promise<string> {
   try {
-    const existingFailure = await latestLoginFailureReason(page);
+    const existingFailure = await latestLoginFailure(page);
     if (existingFailure !== null) {
-      throw new Error(`Login failed: ${existingFailure}`);
+      throw new Error(formatLoginFailure(existingFailure));
     }
     const outcome = await Promise.race([
       page
@@ -334,14 +334,18 @@ async function waitForSignedIn(
             const listener = (event: Event): void => {
               const state = (
                 event as CustomEvent<
-                  { tag?: string; reason?: string } | undefined
+                  { tag?: string; kind?: string; reason?: string } | undefined
                 >
               ).detail;
               if (state?.tag !== "LoginFailed") {
                 return;
               }
               window.removeEventListener("dotli:truapi-auth-state", listener);
-              reject(new Error(`Login failed: ${state.reason ?? "unknown"}`));
+              reject(
+                new Error(
+                  `Login failed (${state.kind ?? "Other"}): ${state.reason ?? "unknown"}`,
+                ),
+              );
             };
             window.addEventListener("dotli:truapi-auth-state", listener);
           }),
@@ -370,15 +374,29 @@ async function waitForSignedIn(
   }
 }
 
-async function latestLoginFailureReason(page: Page): Promise<string | null> {
+/** A login failure the host reported, with the core's typed cause. */
+interface LoginFailure {
+  kind: string;
+  reason: string;
+}
+
+/** Name the cause first: `NoFreeAllowanceSlots` cannot succeed on a retry. */
+function formatLoginFailure(failure: LoginFailure): string {
+  return `Login failed (${failure.kind}): ${failure.reason}`;
+}
+
+async function latestLoginFailure(page: Page): Promise<LoginFailure | null> {
   return await page.evaluate(() => {
     const states = window.__dotliE2eAuthStates ?? [];
     for (let i = states.length - 1; i >= 0; i--) {
       const candidate = states[i] as {
-        detail?: { tag?: string; reason?: string };
+        detail?: { tag?: string; kind?: string; reason?: string };
       };
       if (candidate.detail?.tag === "LoginFailed") {
-        return candidate.detail.reason ?? "unknown";
+        return {
+          kind: candidate.detail.kind ?? "Other",
+          reason: candidate.detail.reason ?? "unknown",
+        };
       }
     }
     return null;

rust/crates/truapi-host-cli/src/platform.rs

@@ -648,7 +648,7 @@ impl truapi_platform::AuthPresenter for CliPlatform {
             AuthState::Disconnected => {
                 ("disconnected".to_string(), SystemEvent::PairingDisconnected)
             }
-            AuthState::LoginFailed { reason } => (
+            AuthState::LoginFailed { reason, .. } => (
                 "failed".to_string(),
                 SystemEvent::PairingFailed {
                     reason: reason.clone(),

rust/crates/truapi-platform/src/lib.rs

@@ -1052,6 +1052,9 @@ pub enum AuthState {
     Connected(SessionUiInfo),
     /// The last login attempt failed; show the reason and offer a retry.
     LoginFailed {
+        /// What kind of failure this was. Hosts branch on this and treat
+        /// `reason` as display copy only.
+        kind: LoginFailureKind,
         /// Human-readable failure reason.
         reason: String,
     },
@@ -1061,6 +1064,20 @@ pub enum AuthState {
     Authenticating,
 }
 
+/// Why a login attempt failed, for hosts that need to act on the cause rather
+/// than only display it.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Encode, Decode)]
+#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
+pub enum LoginFailureKind {
+    /// The wallet has no free statement-store allowance slot for this period,
+    /// so it cannot register the device. Deterministic until the period rolls
+    /// over: retrying wastes the user's remaining budget.
+    NoFreeAllowanceSlots,
+    /// Anything else. `reason` carries the detail.
+    #[default]
+    Other,
+}
+
 /// Host auth UI driven by core-owned [`AuthState`] transitions.
 pub trait AuthPresenter: Send + Sync {
     /// Observe an auth state change. Emitted only when the state actually

rust/crates/truapi-server/src/runtime.rs

@@ -15,6 +15,7 @@ mod authority;
 pub(crate) mod bulletin_rpc;
 mod chat;
 mod identity;
+pub(crate) mod login_failure;
 mod pairing_host;
 mod ring_vrf_registry;
 /// Role-neutral runtime services shared by product-facing runtimes.

rust/crates/truapi-server/src/runtime/auth_state.rs

@@ -5,7 +5,9 @@
 use std::sync::{Arc, Mutex};
 
 use futures::channel::oneshot;
-use truapi_platform::{AuthPresenter, AuthState, Platform, SessionUiInfo};
+use truapi_platform::{AuthPresenter, AuthState, LoginFailureKind, Platform, SessionUiInfo};
+
+use crate::runtime::login_failure::classify_login_failure;
 
 /// Serialized auth-state machine bound to the platform's `auth_state_changed`
 /// sink. Each transition mutates under the lock, releases it, then emits the
@@ -71,6 +73,8 @@ impl AuthStateMachine {
     }
 
     /// Active login -> `LoginFailed`: the in-flight login reported a failure.
+    /// The kind is recovered from `reason`, which is the only form the wallet
+    /// reports a refusal in.
     pub(super) fn login_failed(&self, reason: String) {
         self.transition(|inner| {
             if !matches!(
@@ -80,7 +84,10 @@ impl AuthStateMachine {
                 return None;
             }
             inner.cancel_tx = None;
-            inner.state = AuthState::LoginFailed { reason };
+            inner.state = AuthState::LoginFailed {
+                kind: classify_login_failure(&reason),
+                reason,
+            };
             Some(())
         });
     }
@@ -97,7 +104,12 @@ impl AuthStateMachine {
             ) {
                 return None;
             }
-            inner.state = AuthState::LoginFailed { reason };
+            // Pre-pairing failures are the pairing host's own (device identity,
+            // bootstrap); allowance exhaustion is only ever wallet-reported.
+            inner.state = AuthState::LoginFailed {
+                kind: LoginFailureKind::Other,
+                reason,
+            };
             Some(())
         });
     }