@fun-xyz/fiat-contract 0.6.0 → 0.8.0

package/dist/index.js

@@ -51,6 +51,7 @@ __export(index_exports, {
   InstructionsSchema: () => InstructionsSchema,
   InstrumentSchema: () => InstrumentSchema,
   JsonSchema: () => JsonSchema,
+  KYCProviderSchema: () => KYCProviderSchema,
   KycCaptureStateSchema: () => KycCaptureStateSchema,
   KycInputRequiredStateSchema: () => KycInputRequiredStateSchema,
   KycNoActionRequiredStateSchema: () => KycNoActionRequiredStateSchema,
@@ -73,6 +74,8 @@ __export(index_exports, {
   SelectOptionSchema: () => SelectOptionSchema,
   SessionAuthStateSchema: () => SessionAuthStateSchema,
   StatusHistoryEntrySchema: () => StatusHistoryEntrySchema,
+  SurfaceKindSchema: () => SurfaceKindSchema,
+  SurfaceProviderSchema: () => SurfaceProviderSchema,
   SurfaceSchema: () => SurfaceSchema,
   TABLE_VERSION: () => TABLE_VERSION,
   TERMINAL_ORDER_STATUSES: () => TERMINAL_ORDER_STATUSES,
@@ -81,6 +84,8 @@ __export(index_exports, {
   TransitionParamsSchema: () => TransitionParamsSchema,
   TransitionSchema: () => TransitionSchema,
   TxSchema: () => TxSchema,
+  UNOFFERED_ENDPOINTS: () => UNOFFERED_ENDPOINTS,
+  UNREACHABLE_STATES: () => UNREACHABLE_STATES,
   assertAllFixtures: () => assertAllFixtures,
   assertFiatStepResponse: () => assertFiatStepResponse,
   assertFixture: () => assertFixture,
@@ -95,6 +100,8 @@ __export(index_exports, {
   looksLikeFieldSpec: () => looksLikeFieldSpec,
   stateKey: () => stateKey,
   tableEntry: () => tableEntry,
+  unofferedEndpoints: () => unofferedEndpoints,
+  unreachableStates: () => unreachableStates,
   walkTable: () => walkTable
 });
 module.exports = __toCommonJS(index_exports);
@@ -380,8 +387,12 @@ var HTTP_VERBS = ["GET", "POST"];
 var ENDPOINT_PATTERN = /^(GET|POST) \/fiat\/[^\s]*$/;
 var $endpoint = import_zod.z.string().regex(ENDPOINT_PATTERN, 'endpoint must read "<GET|POST> /fiat/\u2026"');
 var FiatEndpointSchema = $endpoint;
-var $provider = import_zod.z.enum(["TRANSAK", "SWAPPED"]);
+var $provider = import_zod.z.enum(["TRANSAK", "SWAPPED", "BANXA", "MOONPAY", "STRIPE"]);
 var FiatProviderSchema = $provider;
+var $kycProvider = import_zod.z.enum(["SUMSUB"]);
+var KYCProviderSchema = $kycProvider;
+var $surfaceProvider = import_zod.z.enum([...$provider.options, ...$kycProvider.options]);
+var SurfaceProviderSchema = $surfaceProvider;
 var $orderStatus = import_zod.z.enum([
   "CREATING",
   "AWAITING_PAYMENT",
@@ -473,13 +484,22 @@ var $refund = obj({
   expectedBy: import_zod.z.string()
 });
 var RefundSchema = $refund;
-var $surface = import_zod.z.union([
-  obj({ kind: import_zod.z.literal("URL_REDIRECT"), url: import_zod.z.string() }),
-  obj({ kind: import_zod.z.literal("URL_EMBED"), url: import_zod.z.string() }),
-  obj({ kind: import_zod.z.literal("PCI_COMPONENT"), session: import_zod.z.string() }),
-  obj({ kind: import_zod.z.literal("PAY_SHEET"), session: import_zod.z.string() }),
-  obj({ kind: import_zod.z.literal("ACH_COMPONENT"), session: import_zod.z.string() })
-]);
+var $surfaceKind = import_zod.z.enum(["URL_REDIRECT", "KYC_SDK", "PCI_COMPONENT", "PAY_SHEET", "ACH_COMPONENT"]);
+var SurfaceKindSchema = $surfaceKind;
+var $surface = obj({
+  kind: $surfaceKind,
+  provider: $surfaceProvider,
+  /**
+   * The one deliberate non-strict leaf in the contract. Provider inputs are the adapter's
+   * vocabulary, so typing them here would drag every provider field change through a contract
+   * release and both consumers — and a normalised `environment` could only be lossy across
+   * Transak's four values and Banxa's two. Both ends narrow instead: fun-backend emits from a
+   * typed provider session, the client adapter validates with its own schema, and a recorded
+   * fixture per `(provider, kind)` keeps the two honest.
+   */
+  params: import_zod.z.record(import_zod.z.string(), JsonSchema),
+  expiresAt: import_zod.z.string().optional()
+});
 var SurfaceSchema = $surface;
 var $instructionField = obj({
   id: import_zod.z.string(),
@@ -609,6 +629,8 @@ var AuthChallengeSchema = $authChallenge;
 var $quoteState = obj({
   kind: import_zod.z.literal("QUOTE"),
   quote: $quote,
+  /** Present when the provider's component is the primary CTA, inline on the entry screen. */
+  surface: $surface.optional(),
   error: $failureReason.optional()
 });
 var QuoteStateSchema = $quoteState;
@@ -627,6 +649,7 @@ var SessionAuthStateSchema = $sessionAuthState;
 var $kycCaptureState = obj({
   kind: import_zod.z.literal("KYC"),
   phase: import_zod.z.literal("CAPTURE"),
+  quote: $quote,
   surface: $surface,
   error: $failureReason.optional()
 });
@@ -634,6 +657,7 @@ var KycCaptureStateSchema = $kycCaptureState;
 var $kycInputRequiredState = obj({
   kind: import_zod.z.literal("KYC"),
   phase: import_zod.z.literal("INPUT_REQUIRED"),
+  quote: $quote,
   form: $formDescriptor,
   error: $failureReason.optional()
 });
@@ -641,6 +665,7 @@ var KycInputRequiredStateSchema = $kycInputRequiredState;
 var $kycNoActionRequiredState = obj({
   kind: import_zod.z.literal("KYC"),
   phase: import_zod.z.literal("NO_ACTION_REQUIRED"),
+  quote: $quote,
   reason: import_zod.z.enum(["IN_REVIEW", "ON_HOLD", "REJECTED"]),
   retryAfter: import_zod.z.string().optional(),
   failureReason: $failureReason.optional(),
@@ -718,7 +743,7 @@ var $stepResponse = obj({
 var FiatStepResponseSchema = $stepResponse;
 
 // package.json
-var version = "0.6.0";
+var version = "0.8.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -749,22 +774,46 @@ var TRANSITION_TABLE = {
         endpoint: "POST /fiat/session",
         when: "no valid provider session token (own-tables check)"
       },
+      {
+        id: "open_session",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/payment-session",
+        when: "returning user, session + KYC valid, capture-first rail \u2014 the method authorises before any order exists",
+        note: "Returns PAYMENT{CAPTURE} carrying the Surface. Without this entry the capture-first rail has no legal way in: a transition-following client takes POST /fiat/orders instead, and the backend refuses that when the provider declares the capture-first capability and no authorisation is present. Named open_session per the Fiat Contract 0.7 doc, which adds quote-time-minted surface rows beside it."
+      },
       {
         id: "continue",
         mode: "SUBMIT",
         endpoint: "POST /fiat/orders",
-        when: "returning user, session + KYC valid \u2014 the quote screen doubles as review"
+        when: "returning user, session + KYC valid, order-first rail \u2014 the quote screen doubles as review",
+        note: "Narrowed to the order-first rail: on a capture-first method the order cannot be created before the payment is authorised, so the sibling payment-session entry is the one that applies."
       },
       {
         id: "continue",
         mode: "SUBMIT",
         endpoint: "POST /fiat/auth",
         when: "no ambient Fun identity (non-fomo surfaces only)"
+      },
+      {
+        id: "capture",
+        mode: "CLIENT_SURFACE",
+        endpoint: "POST /fiat/orders",
+        when: "capture-then-order rail whose session is minted at quote time (inline pay sheet)",
+        note: "The 0.7 row that makes the single-screen Apple Pay design legal: the surface rides QUOTE, the provider component IS the primary CTA, and its result creates the order. Apple policy forbids a visible step between an Apple-branded tap and the sheet, and TransakApplePay exposes no programmatic trigger, so a two-step via payment-session cannot serve this rail. Requires state.surface (\u03942)."
+      },
+      {
+        id: "capture",
+        mode: "CLIENT_SURFACE",
+        endpoint: "POST /fiat/orders/:id/surface-result",
+        when: "order-then-capture rail whose provider order was created with the quote-time session",
+        note: "Same quote-time placement, other topology: the order already exists, so the surface reports against it rather than creating one."
       }
     ],
     mayReturn: [
       "SESSION_AUTH",
       ...KYC_ANY,
+      "PAYMENT/CAPTURE",
+      "PAYMENT/INSTRUCT",
       "PENDING_ORDER",
       "ORDER/AWAITING_CONFIRMATION",
       "ORDER/CREATED",
@@ -772,8 +821,10 @@ var TRANSITION_TABLE = {
     ],
     terminal: false,
     notes: [
-      "Re-quote on amount change is a client-local event, not a transition.",
-      'If the PENDING_ORDER removal lands, QUOTE additionally returns PAYMENT{INSTRUCT} / ORDER{CREATED} directly. TODO(open-decision): contract \xA7"Proposal: remove PENDING_ORDER".'
+      "Re-quote on amount change is a client-local event, not a transition. A new quote carries a new surface; the client remounts the adapter rather than reusing the old session.",
+      "A surface on QUOTE and a SUBMIT to the same endpoint may not coexist \u2014 two paths to one order. assertLegalEmission enforces it; the server picks one per rail.",
+      `Both PAYMENT states are reachable directly from QUOTE: the FE doc canvas draws S1 \u2192 S5 (card, capture-first) and S1 \u2192 S6 (bank). This entry was first ported from the FE doc's bindings table, whose "May receive back" column omits both \u2014 the canvas is the correct source of the two.`,
+      'TODO(open-decision): contract \xA7"Proposal: remove PENDING_ORDER" would additionally have QUOTE return ORDER{CREATED} for an active order. That decision does not gate the PAYMENT edges above.'
     ]
   },
   FUN_AUTH: {
@@ -818,21 +869,23 @@ var TRANSITION_TABLE = {
       {
         id: "capture",
         mode: "CLIENT_SURFACE",
-        endpoint: "GET /fiat/kyc",
-        note: 'report target per FE bindings ("POST surface report \u2192 GET /fiat/kyc") and contract Flow C.'
+        endpoint: "POST /fiat/kyc/capture",
+        note: "Reports SDK submission; provider eligibility is re-evaluated through quote orchestration."
       }
     ],
     mayReturn: [
+      "KYC/CAPTURE",
       "KYC/INPUT_REQUIRED",
       "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
       "KYC/NO_ACTION_REQUIRED:ON_HOLD",
       "KYC/NO_ACTION_REQUIRED:REJECTED",
+      "QUOTE",
+      "PAYMENT/CAPTURE",
+      "PAYMENT/INSTRUCT",
       "ORDER/AWAITING_CONFIRMATION"
     ],
     terminal: false,
-    notes: [
-      "Dropped from v1 (no UK headless-module coverage) \u2014 FE Screen 8 is a tombstone. Kind retained as vocabulary; the handshake (supportedStepKinds) keeps the backend from routing v1 SDKs here."
-    ]
+    notes: ["Carries the handshake-gated KYC_SDK surface; provider selects the identity-vendor adapter."]
   },
   "KYC/INPUT_REQUIRED": {
     key: "KYC/INPUT_REQUIRED",
@@ -844,16 +897,20 @@ var TRANSITION_TABLE = {
       { id: "submit_round", mode: "SUBMIT", endpoint: "POST /fiat/kyc/form" }
     ],
     mayReturn: [
+      "KYC/CAPTURE",
       "KYC/INPUT_REQUIRED",
       "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
       "KYC/NO_ACTION_REQUIRED:ON_HOLD",
       "KYC/NO_ACTION_REQUIRED:REJECTED",
+      "QUOTE",
+      "PAYMENT/CAPTURE",
+      "PAYMENT/INSTRUCT",
       "ORDER/AWAITING_CONFIRMATION"
     ],
     terminal: false,
     notes: [
       "One POST per round; conditional requirements may open another round.",
-      "FILE fields stream to POST /fiat/kyc/document \u2014 an upload path the harness owns, not a transition.",
+      "FILE fields use POST /fiat/kyc/document to obtain or report a direct provider/vendor upload; document bytes never transit Fun. The harness owns this auxiliary path, not a transition.",
       "Hosted KYC links arrive as HOSTED_LINK form fields, not as a Surface."
     ]
   },
@@ -864,12 +921,16 @@ var TRANSITION_TABLE = {
     reason: "IN_REVIEW",
     screens: [9],
     docStatus: "SPECIFIED",
-    allowedTransitions: [{ id: "poll", mode: "AWAIT", endpoint: "GET /fiat/kyc" }],
+    allowedTransitions: [{ id: "poll", mode: "AWAIT", endpoint: "GET /fiat/quotes/:quoteRef" }],
     mayReturn: [
       "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
+      "KYC/CAPTURE",
       "KYC/INPUT_REQUIRED",
       "KYC/NO_ACTION_REQUIRED:ON_HOLD",
       "KYC/NO_ACTION_REQUIRED:REJECTED",
+      "QUOTE",
+      "PAYMENT/CAPTURE",
+      "PAYMENT/INSTRUCT",
       "ORDER/AWAITING_CONFIRMATION"
     ],
     terminal: false,
@@ -899,20 +960,11 @@ var TRANSITION_TABLE = {
     reason: "REJECTED",
     screens: [11],
     docStatus: "SPECIFIED",
-    allowedTransitions: [
-      {
-        id: "escalate",
-        mode: "SUBMIT",
-        endpoint: "GET /fiat/kyc",
-        when: "an escalation round is offered",
-        note: "TODO(open-decision): placeholder shape \u2014 the FE doc flags that a GET carrying params is not a real request shape, and OQ7 owns which rejections escalate. FE doc open question 7."
-      }
-    ],
-    mayReturn: KYC_ANY,
-    terminal: false,
+    allowedTransitions: [],
+    mayReturn: [],
+    terminal: true,
     notes: [
-      "Terminal *variant*: failureReason {KYC_REJECTED, retryable: false, recovery: CONTACT_SUPPORT} + transitions [] \u2014 renders in place, never routes through ORDER{CREATED, FAILED}. Because escalation is also legal here, the entry is not flatly terminal.",
-      "TODO(open-decision): contract OQ7 \u2014 terminal vs escalating rejections are not enumerated."
+      "Only explicit non-retryable outcomes reach REJECTED. Correctable failures return CAPTURE or INPUT_REQUIRED; provider-specific declines re-route before becoming user rejection."
     ]
   },
   PENDING_ORDER: {
@@ -1071,10 +1123,13 @@ var DOCUMENTED_ENDPOINTS = [
   "GET /fiat/payment-methods",
   "POST /fiat/quote",
   "POST /fiat/auth",
+  "POST /fiat/payment-session",
   "POST /fiat/session",
   "POST /fiat/session/verify",
-  "GET /fiat/kyc",
+  "GET /fiat/quotes/:quoteRef",
   "POST /fiat/kyc/form",
+  "POST /fiat/kyc/capture",
+  "POST /fiat/kyc/sdk-token",
   "POST /fiat/kyc/document",
   "POST /fiat/instruments",
   "POST /fiat/orders",
@@ -1085,6 +1140,58 @@ var DOCUMENTED_ENDPOINTS = [
   "POST /fiat/orders/:id/cancel",
   "POST /fiat/orders/:id/surface-result"
 ];
+var UNOFFERED_ENDPOINTS = [
+  {
+    endpoint: "POST /fiat/kyc/sdk-token",
+    reason: "SDK token refresh is adapter-driven rather than a flow transition."
+  },
+  {
+    endpoint: "GET /fiat/payment-methods",
+    reason: "Discovery, called before any flow state exists \u2014 there is no state to hang it off."
+  },
+  {
+    endpoint: "POST /fiat/kyc/document",
+    reason: "FILE fields use it for a direct provider/vendor upload handshake and completion report; the harness owns that auxiliary path and it is not a transition (see KYC/INPUT_REQUIRED notes)."
+  },
+  {
+    endpoint: "POST /fiat/instruments",
+    reason: "No state offers it and no published doc explains why. TODO(open-decision): saved instruments may simply be unreached in v1 \u2014 confirm, or wire it to the state that should offer it."
+  },
+  {
+    endpoint: "GET /fiat/orders/:id/instructions",
+    reason: "PAYMENT{INSTRUCT} carries its instructions in state and offers no fetch. TODO(open-decision): that state also notes no re-issue endpoint exists, which sits oddly beside this one being published \u2014 confirm or retire it."
+  },
+  {
+    endpoint: "POST /fiat/orders/:id/reference",
+    reason: "The bank-reference submission is offered by no state. TODO(open-decision): PAYMENT{INSTRUCT} is the plausible home \u2014 confirm or wire it."
+  }
+];
+var UNREACHABLE_STATES = [
+  {
+    stateKey: "FUN_AUTH",
+    reason: "No bindings row published (docStatus UNSPECIFIED) and never rendered in fomo, where identity is ambient. Entered out-of-band, not by a mayReturn edge."
+  }
+];
+function unofferedEndpoints() {
+  const offered = /* @__PURE__ */ new Set();
+  for (const key of STATE_KEYS) {
+    for (const allowed of TRANSITION_TABLE[key].allowedTransitions) offered.add(allowed.endpoint);
+  }
+  return DOCUMENTED_ENDPOINTS.filter((endpoint) => !offered.has(endpoint));
+}
+function unreachableStates(from = "QUOTE") {
+  const seen = /* @__PURE__ */ new Set([from]);
+  const queue = [from];
+  while (queue.length > 0) {
+    for (const target of TRANSITION_TABLE[queue.pop()].mayReturn ?? []) {
+      if (!seen.has(target)) {
+        seen.add(target);
+        queue.push(target);
+      }
+    }
+  }
+  return STATE_KEYS.filter((key) => !seen.has(key));
+}
 function stateKey(state) {
   switch (state.kind) {
     case "QUOTE":
@@ -1167,6 +1274,64 @@ var FIXTURE_DATA = {
       }
     ]
   },
+  "screen-01b-quote-with-pay-sheet": {
+    "state": {
+      "kind": "QUOTE",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.09"
+          },
+          {
+            "id": "network_fee",
+            "labelFallback": "Network fee",
+            "amount": "0.50"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "\u2026"
+      },
+      "surface": {
+        "kind": "PAY_SHEET",
+        "provider": "TRANSAK",
+        "params": {
+          "sessionId": "txs_\u2026",
+          "environment": "STAGING"
+        }
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "capture",
+        "mode": "CLIENT_SURFACE",
+        "report": {
+          "endpoint": "POST /fiat/orders",
+          "params": {
+            "quoteRef": "q_8f2",
+            "depositAddress": "\u2026"
+          },
+          "expects": [
+            "paymentAuthorisationId"
+          ]
+        }
+      }
+    ]
+  },
   "screen-02-session-auth": {
     "state": {
       "kind": "SESSION_AUTH",
@@ -1194,45 +1359,43 @@ var FIXTURE_DATA = {
     "state": {
       "kind": "KYC",
       "phase": "INPUT_REQUIRED",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.59"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "\u2026"
+      },
       "form": {
-        "formId": "personal_details",
+        "formId": "kyc_q_8f2_1",
         "fields": [
           {
-            "id": "firstName",
+            "id": "tin",
             "type": "TEXT",
-            "labelFallback": "First name",
-            "required": true
-          },
-          {
-            "id": "dob",
-            "type": "DATE",
-            "labelFallback": "Date of birth",
+            "labelFallback": "Tax ID",
             "required": true
           },
           {
-            "id": "country",
-            "type": "COUNTRY",
-            "labelFallback": "Country",
+            "id": "address",
+            "type": "TEXT",
+            "labelFallback": "Home address",
             "required": true
-          },
-          {
-            "id": "sourceOfFunds",
-            "type": "SELECT",
-            "labelFallback": "Source of funds",
-            "required": true,
-            "options": [
-              {
-                "id": "salary",
-                "labelFallback": "Salary"
-              }
-            ]
-          },
-          {
-            "id": "idProof",
-            "type": "HOSTED_LINK",
-            "labelFallback": "Verify your ID",
-            "required": true,
-            "url": "\u2026"
           }
         ]
       }
@@ -1244,7 +1407,8 @@ var FIXTURE_DATA = {
         "mode": "SUBMIT",
         "endpoint": "POST /fiat/kyc/form",
         "params": {
-          "formId": "personal_details"
+          "quoteRef": "q_8f2",
+          "formId": "kyc_q_8f2_1"
         },
         "inputs": {
           "values": {
@@ -1305,7 +1469,11 @@ var FIXTURE_DATA = {
       "phase": "CAPTURE",
       "surface": {
         "kind": "PCI_COMPONENT",
-        "session": "eyJ\u2026"
+        "provider": "TRANSAK",
+        "params": {
+          "sessionId": "eyJ\u2026",
+          "environment": "STAGING"
+        }
       }
     },
     "provider": "TRANSAK",
@@ -1325,11 +1493,84 @@ var FIXTURE_DATA = {
       }
     ]
   },
+  "screen-08-kyc-capture": {
+    "state": {
+      "kind": "KYC",
+      "phase": "CAPTURE",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.59"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "\u2026"
+      },
+      "surface": {
+        "kind": "KYC_SDK",
+        "provider": "SUMSUB",
+        "params": {
+          "accessToken": "eyJ\u2026"
+        },
+        "expiresAt": "\u2026"
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "capture",
+        "mode": "CLIENT_SURFACE",
+        "report": {
+          "endpoint": "POST /fiat/kyc/capture",
+          "params": {
+            "quoteRef": "q_8f2"
+          }
+        }
+      }
+    ]
+  },
   "screen-09-kyc-in-review": {
     "state": {
       "kind": "KYC",
       "phase": "NO_ACTION_REQUIRED",
-      "reason": "IN_REVIEW"
+      "reason": "IN_REVIEW",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.59"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "\u2026"
+      }
     },
     "provider": "TRANSAK",
     "transitions": [
@@ -1337,10 +1578,7 @@ var FIXTURE_DATA = {
         "id": "poll",
         "mode": "AWAIT",
         "poll": {
-          "endpoint": "GET /fiat/kyc",
-          "params": {
-            "quoteRef": "q_8f2"
-          },
+          "endpoint": "GET /fiat/quotes/q_8f2",
           "intervalMs": 3e3,
           "backoffFactor": 1.5,
           "maxIntervalMs": 1e4,
@@ -1354,28 +1592,70 @@ var FIXTURE_DATA = {
       "kind": "KYC",
       "phase": "NO_ACTION_REQUIRED",
       "reason": "ON_HOLD",
-      "retryAfter": "2026-08-20T09:00:00Z"
+      "retryAfter": "2026-08-20T09:00:00Z",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.59"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "\u2026"
+      }
     },
     "provider": "TRANSAK",
     "transitions": []
   },
-  "screen-11-kyc-rejected-escalation": {
+  "screen-11-kyc-rejected": {
     "state": {
       "kind": "KYC",
       "phase": "NO_ACTION_REQUIRED",
-      "reason": "REJECTED"
+      "reason": "REJECTED",
+      "quote": {
+        "quoteRef": "q_8f2",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "rate": "0.9841",
+        "totalFee": "1.59",
+        "feeBreakdown": [
+          {
+            "id": "provider_fee",
+            "labelFallback": "Processing fee",
+            "amount": "1.59"
+          }
+        ],
+        "paymentMethod": "bank_transfer",
+        "expiresAt": "\u2026"
+      },
+      "failureReason": {
+        "category": "KYC_REJECTED",
+        "retryable": false,
+        "recovery": "CONTACT_SUPPORT"
+      }
     },
     "provider": "TRANSAK",
-    "transitions": [
-      {
-        "id": "escalate",
-        "mode": "SUBMIT",
-        "endpoint": "GET /fiat/kyc",
-        "params": {
-          "tier": "escalated"
-        }
-      }
-    ]
+    "transitions": []
   },
   "screen-12-pending-order": {
     "state": {
@@ -1630,6 +1910,18 @@ var FIXTURES = [
     screen: 1,
     stateKey: "QUOTE"
   },
+  {
+    id: "screen-01b-quote-with-pay-sheet",
+    file: "screen-01b-quote-with-pay-sheet.json",
+    source: "CONTRACT_DOC",
+    docRef: "Fiat Contract 0.7 \xA7The contract diff \xB7 example envelopes",
+    screen: 1,
+    stateKey: "QUOTE",
+    notes: [
+      "The 0.7 single-screen shape: the quote carries its own PAY_SHEET, so the provider component is the primary CTA rather than something a later state reveals.",
+      "Quote payload is screen-01-quote verbatim; only the surface and the transition differ."
+    ]
+  },
   {
     id: "screen-02-session-auth",
     file: "screen-02-session-auth.json",
@@ -1641,8 +1933,8 @@ var FIXTURES = [
   {
     id: "screen-03-kyc-input-required",
     file: "screen-03-kyc-input-required.json",
-    source: "FE_DOC",
-    docRef: "Screen 3 \xB7 Identity form (KYC)",
+    source: "KYC_DOC",
+    docRef: "Fiat KYC \xB7 L1 input round",
     screen: 3,
     stateKey: "KYC/INPUT_REQUIRED",
     notes: ["Carries the FORM_VALUES input spec \u2014 the no-double-carry case of the accepted split."]
@@ -1670,34 +1962,40 @@ var FIXTURES = [
       "TODO(open-decision): report target per card topology is a Transak ask (contract Flow A)."
     ]
   },
+  {
+    id: "screen-08-kyc-capture",
+    file: "screen-08-kyc-capture.json",
+    source: "KYC_DOC",
+    docRef: "Fiat KYC \xB7 embedded Sumsub WebSDK",
+    screen: 8,
+    stateKey: "KYC/CAPTURE",
+    notes: ["The client mounts the Sumsub adapter; no URL or iframe is emitted."]
+  },
   {
     id: "screen-09-kyc-in-review",
     file: "screen-09-kyc-in-review.json",
-    source: "FE_DOC",
-    docRef: "Screen 9 \xB7 Verifying identity",
+    source: "KYC_DOC",
+    docRef: "Fiat KYC \xB7 pending quote",
     screen: 9,
     stateKey: "KYC/NO_ACTION_REQUIRED:IN_REVIEW"
   },
   {
     id: "screen-10-kyc-on-hold",
     file: "screen-10-kyc-on-hold.json",
-    source: "FE_DOC",
-    docRef: "Screen 10 \xB7 Verification on hold",
+    source: "KYC_DOC",
+    docRef: "Fiat KYC \xB7 verification on hold",
     screen: 10,
     stateKey: "KYC/NO_ACTION_REQUIRED:ON_HOLD",
     notes: ["transitions: [] and NOT terminal \u2014 the fixture that proves terminality is table data."]
   },
   {
-    id: "screen-11-kyc-rejected-escalation",
-    file: "screen-11-kyc-rejected-escalation.json",
-    source: "FE_DOC",
-    docRef: "Screen 11 \xB7 Verification unsuccessful",
+    id: "screen-11-kyc-rejected",
+    file: "screen-11-kyc-rejected.json",
+    source: "KYC_DOC",
+    docRef: "Fiat KYC \xB7 non-retryable rejection",
     screen: 11,
     stateKey: "KYC/NO_ACTION_REQUIRED:REJECTED",
-    notes: [
-      "TODO(open-decision): the escalation transition is a flagged placeholder \u2014 a GET carrying params is not a real request shape (FE doc Screen 11 + open question 7).",
-      "The terminal REJECTED variant (failureReason + transitions []) is described in prose, not published as JSON \u2014 no fixture."
-    ]
+    notes: ["Only an explicit non-retryable provider or identity-vendor outcome reaches this state."]
   },
   {
     id: "screen-12-pending-order",
@@ -1742,7 +2040,7 @@ var FIXTURES = [
     docRef: "Screen 16 \xB7 Not available",
     screen: 16,
     stateKey: "BLOCKED",
-    notes: ["The only flatly terminal state entry in the table."]
+    notes: ["A flatly terminal availability state; explicit non-retryable KYC rejection is terminal too."]
   },
   {
     id: "worked-example-01-quote",
@@ -1774,10 +2072,6 @@ var FIXTURE_COVERAGE_GAPS = [
   {
     stateKey: "FUN_AUTH",
     reason: "No step response exists in either doc \u2014 shape owned by the auth spike, and FUN_AUTH never renders in fomo. TODO(open-decision): contract \xA7Auth & ref binding, item 5."
-  },
-  {
-    stateKey: "KYC/CAPTURE",
-    reason: "Dropped from v1 (FE Screen 8 tombstone, no UK module coverage); no step response was ever published. Kind retained as handshake-gated vocabulary."
   }
 ];
 var fixtureMeta = (id) => {
@@ -1867,6 +2161,16 @@ function checkLegalEmission(state, transitions) {
       `${entry.key} is terminal (table) and must carry transitions: [] \u2014 got ${transitions.length}`
     );
   }
+  const surfaceTargets = new Set(
+    transitions.filter((t) => t.mode === "CLIENT_SURFACE").map((t) => t.report.endpoint)
+  );
+  for (const transition of transitions) {
+    if (transition.mode === "SUBMIT" && surfaceTargets.has(transition.endpoint)) {
+      issues.push(
+        `transition "${transition.id}": SUBMIT ${transition.endpoint} coexists with a CLIENT_SURFACE reporting to it`
+      );
+    }
+  }
   for (const transition of transitions) {
     issues.push(...bodyKeyIssues(transition));
     if (transition.mode === "CLIENT_SURFACE" && !("surface" in state)) {