fix(spec): a user's refusal and a structural refusal are distinct outcomes

SPEC.md's wire table gave SPEND_DENIED -33053 to a declined ceremony and
SPEND_NOT_AUTHORIZED -33052 to PolicyDenied, while the decline path already
returned PolicyDenied -- so the normative mapping named two codes for one
value and no conforming host could exist. The table now keys every row on a
distinct AccountError variant, and states that it MUST be a function of the
outcome alone.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: MichaelTaylor3d

SPEC.md

@@ -292,7 +292,8 @@ test double drives the real gate with a test policy and the public `FixedClock`.
 |---|---|---|
 | `Ok(SpendRuling::Approved(approval))` | Auto-approved by policy; the rolling cap is ALREADY charged its real value | — (already permitted) |
 | `Ok(SpendRuling::RequiresConfirmation(pending))` | Not auto-approved, but the user MAY permit it. Nothing charged | YES — this IS the escalation |
-| `Err(AccountError::PolicyDenied)` | Forbidden by a structural custody rule, or the user declined | NO |
+| `Err(AccountError::PolicyDenied)` | Forbidden by a structural custody rule | NO |
+| `Err(AccountError::UserDeclined)` | The user was asked and refused | NO — the human has already answered |
 | `Err(AccountError::PolicyIndeterminate)` | The policy could not be EVALUATED | NO — the condition must be fixed |
 
 **The escalatable outcome MUST be an `Ok` value, not an error.** A return type that can only say "yes"
@@ -303,8 +304,11 @@ them can lose detail but can no longer lose a permission.
 
 `PendingApproval::confirmed(SpendDecision) -> Result<SpendApproval>` is the ONLY route from "needs a
 human" to a signable approval. It MUST consume `self`, so one prompt yields at most one approval, and it
-MUST return `PolicyDenied` on `Decline` — the human has already been asked, so re-prompting would turn a
-refusal into a prompt-until-mis-click. A declined or escalated spend MUST NOT consume the rolling
+MUST return `UserDeclined` on `Decline`, NOT `PolicyDenied` — the human has already been asked, so
+re-prompting would turn a refusal into a prompt-until-mis-click, and the two facts have different
+deciders. An implementation MUST NOT return one variant for both: a host holding a single variant cannot
+tell "you said no" from "the rules say no", cannot render an honest UI, and cannot satisfy §6.3.1's
+mapping, which requires each outcome to name exactly one wire code. A declined or escalated spend MUST NOT consume the rolling
 allowance; nor does a human-confirmed one, since that cap bounds what moves UNATTENDED.
 
 An implementation MUST NOT collapse "denied by policy" with "could not determine policy": doing so both
@@ -317,12 +321,18 @@ taxonomy itself lives in the host's loopback layer rather than in this crate; th
 
 | Outcome | Wire code | Escalatable? |
 |---|---|---|
-| `RequiresConfirmation`, then the user declines | `SPEND_DENIED` `-33053` | — |
-| `Err(PolicyDenied)` | `SPEND_NOT_AUTHORIZED` `-33052` | NO |
+| `Err(UserDeclined)` (the ceremony ran and the user refused) | `SPEND_DENIED` `-33053` | NO |
+| `Err(PolicyDenied)` (a structural custody rule forbids it) | `SPEND_NOT_AUTHORIZED` `-33052` | NO |
 | `Err(PolicyIndeterminate)` | `SPEND_POLICY_INDETERMINATE` `-33056` | NO |
 | verify failure (`Err(AccountError::Spend)`) | `SPEND_REFUSED` `-33051` | NO |
 | decode failure, or a forbidden field present | `SPEND_BAD_PAYLOAD` `-33050` | NO |
 
+**This mapping MUST be a function of the crate outcome alone.** Each row's left-hand side is a distinct
+`AccountError` variant, so a host maps by matching the variant and never by reconstructing which decider
+refused. An earlier revision keyed one row on a SEQUENCE of events ("`RequiresConfirmation`, then the user
+declines") while another keyed on `PolicyDenied`, and both resolved to `PolicyDenied` — so the table named
+two codes for one value and a conforming host could not exist. `UserDeclined` is what makes it total.
+
 `SPEND_POLICY_INDETERMINATE` `-33056` MUST exist as its own code. Without it, "the policy could not be
 evaluated" collapses into `SPEND_NOT_AUTHORIZED` — the very defect §6.3 forbids, one layer up.
 

src/error.rs

@@ -50,8 +50,11 @@ pub enum AccountError {
     #[error("the user declined the spend: {0}")]
     UserDeclined(String),
 
-    /// The spend is FORBIDDEN by a structural custody rule, or the user declined it — no (further)
-    /// confirmation ceremony can permit it.
+    /// The spend is FORBIDDEN by a structural custody rule — no confirmation ceremony can permit it.
+    ///
+    /// A user's refusal is NOT this variant; it is [`UserDeclined`](Self::UserDeclined). Both are
+    /// terminal, but they name different deciders and `SPEC.md` §6.3.1 maps them to different wire
+    /// codes, so a host must be able to tell them apart.
     ///
     /// # The escalatable outcome is deliberately NOT an error
     ///

src/wallet/enforcer.rs

@@ -1778,7 +1778,11 @@ mod tests {
         StandardLayer::new(spender().public_key())
             .spend(
                 &mut ctx,
-                Coin::new(Bytes32::new([9u8; 32]), spender().puzzle_hash(), coin_amount),
+                Coin::new(
+                    Bytes32::new([9u8; 32]),
+                    spender().puzzle_hash(),
+                    coin_amount,
+                ),
                 conditions,
             )
             .unwrap();
@@ -1851,4 +1855,49 @@ mod tests {
         );
         let _ = pending(ruling);
     }
+
+    /// **SPEC §6.3.1 CONFORMANCE: the two refusals a host must distinguish are different variants.**
+    ///
+    /// The wire mapping gives `SPEND_DENIED -33053` to a user's refusal and `SPEND_NOT_AUTHORIZED
+    /// -33052` to a structural one. That mapping is only a function if the crate hands back a
+    /// different value for each, and for one revision it did not: both arrived as `PolicyDenied`, so
+    /// the table named two codes for one value and no conforming host could exist.
+    ///
+    /// Both halves are produced HERE, in one test, from ONE gate. Two separate tests each asserting
+    /// its own variant would pass just as happily if a refactor merged the variants and only one of
+    /// them was updated — it is the DIFFERENCE that the host depends on, so the difference is what is
+    /// asserted.
+    #[tokio::test]
+    async fn a_user_refusal_and_a_structural_refusal_are_distinguishable_outcomes() {
+        // Structural: a vault outflow may only ever pay this profile's own hot wallet.
+        let vault = gate_with(vault_custody(), permissive_auto_send());
+        let structural = refusal(vault.authorize_op(&pays_third_party(1_000), SpendOpClass::Tip));
+
+        // Human: the same gate escalates a payment to its OWN hot wallet, and the user says no.
+        let escalated = pending(vault.authorize_op(
+            &spend_paying(&[(hot_wallet().puzzle_hash(), 1_000)], 0),
+            SpendOpClass::Tip,
+        ));
+        let human = denial(
+            confirmed(
+                escalated,
+                crate::auth::provider::SpendDecision::Decline(None),
+            )
+            .await,
+        );
+
+        assert!(
+            matches!(structural, AccountError::PolicyDenied(_)),
+            "a structural refusal must map to SPEND_NOT_AUTHORIZED -33052: {structural}"
+        );
+        assert!(
+            matches!(human, AccountError::UserDeclined(_)),
+            "a user's refusal must map to SPEND_DENIED -33053: {human}"
+        );
+        assert_ne!(
+            std::mem::discriminant(&structural),
+            std::mem::discriminant(&human),
+            "the wire mapping is a function only if these are different values; collapsing them              leaves a host unable to tell 'you said no' from 'the rules say no'"
+        );
+    }
 }