@fun-xyz/fiat-contract 0.6.0 → 0.7.0

package/README.md

@@ -17,7 +17,7 @@ Four things, zero runtime logic beyond validation:
 | Import | Weight | Contains | Used by |
 | --- | --- | --- | --- |
 | `@fun-xyz/fiat-contract/types` | **0.1 KB** (types erase) | every type; no runtime values | production, both repos |
-| `@fun-xyz/fiat-contract/table` | **13.8 KB**, zero deps | `TRANSITION_TABLE`, `stateKey`, `tableEntry`, `isTerminal`, `walkTable`, `TABLE_VERSION`, `TERMINAL_ORDER_STATUSES`, `DOCUMENTED_ENDPOINTS` | **production frontend** + backend |
+| `@fun-xyz/fiat-contract/table` | **13.8 KB**, zero deps | `TRANSITION_TABLE`, `stateKey`, `tableEntry`, `isTerminal`, `walkTable`, `TABLE_VERSION`, `TERMINAL_ORDER_STATUSES`, `DOCUMENTED_ENDPOINTS`, `UNOFFERED_ENDPOINTS`, `UNREACHABLE_STATES`, `unofferedEndpoints`, `unreachableStates` | **production frontend** + backend |
 | `@fun-xyz/fiat-contract` | 47.6 KB, needs zod | the above + 46 zod schemas + assertions + 16 fixtures | tests, and backend dev/test guards |
 
 `./table` is not a micro-optimisation. Terminality is table data a **shipped** client must read

package/dist/{chunk-EHYDQU4T.mjs → chunk-OGNYHIOE.mjs}

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.6.0";
+var version = "0.7.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -30,22 +30,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",
@@ -53,8 +77,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: {
@@ -352,6 +378,7 @@ 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",
@@ -366,6 +393,54 @@ var DOCUMENTED_ENDPOINTS = [
   "POST /fiat/orders/:id/cancel",
   "POST /fiat/orders/:id/surface-result"
 ];
+var UNOFFERED_ENDPOINTS = [
+  {
+    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 stream to it directly; the harness owns that upload 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":
@@ -408,8 +483,12 @@ export {
   TRANSITION_TABLE,
   STATE_KEYS,
   DOCUMENTED_ENDPOINTS,
+  UNOFFERED_ENDPOINTS,
+  UNREACHABLE_STATES,
+  unofferedEndpoints,
+  unreachableStates,
   stateKey,
   tableEntry,
   isTerminal
 };
-//# sourceMappingURL=chunk-EHYDQU4T.mjs.map
+//# sourceMappingURL=chunk-OGNYHIOE.mjs.map

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"]);
 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", "URL_EMBED", "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;
@@ -718,7 +740,7 @@ var $stepResponse = obj({
 var FiatStepResponseSchema = $stepResponse;
 
 // package.json
-var version = "0.6.0";
+var version = "0.7.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -749,22 +771,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 +818,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: {
@@ -1071,6 +1119,7 @@ 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",
@@ -1085,6 +1134,54 @@ var DOCUMENTED_ENDPOINTS = [
   "POST /fiat/orders/:id/cancel",
   "POST /fiat/orders/:id/surface-result"
 ];
+var UNOFFERED_ENDPOINTS = [
+  {
+    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 stream to it directly; the harness owns that upload 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 +1264,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",
@@ -1305,7 +1460,11 @@ var FIXTURE_DATA = {
       "phase": "CAPTURE",
       "surface": {
         "kind": "PCI_COMPONENT",
-        "session": "eyJ\u2026"
+        "provider": "TRANSAK",
+        "params": {
+          "sessionId": "eyJ\u2026",
+          "environment": "STAGING"
+        }
       }
     },
     "provider": "TRANSAK",
@@ -1630,6 +1789,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",
@@ -1867,6 +2038,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)) {

package/dist/index.mjs

@@ -5,10 +5,14 @@ import {
   TABLE_VERSION,
   TERMINAL_ORDER_STATUSES,
   TRANSITION_TABLE,
+  UNOFFERED_ENDPOINTS,
+  UNREACHABLE_STATES,
   isTerminal,
   stateKey,
-  tableEntry
-} from "./chunk-EHYDQU4T.mjs";
+  tableEntry,
+  unofferedEndpoints,
+  unreachableStates
+} from "./chunk-OGNYHIOE.mjs";
 
 // src/codes.ts
 var COUNTRY_CURRENCY_LIST = [
@@ -291,8 +295,12 @@ var HTTP_VERBS = ["GET", "POST"];
 var ENDPOINT_PATTERN = /^(GET|POST) \/fiat\/[^\s]*$/;
 var $endpoint = z.string().regex(ENDPOINT_PATTERN, 'endpoint must read "<GET|POST> /fiat/\u2026"');
 var FiatEndpointSchema = $endpoint;
-var $provider = z.enum(["TRANSAK", "SWAPPED"]);
+var $provider = z.enum(["TRANSAK", "SWAPPED", "BANXA"]);
 var FiatProviderSchema = $provider;
+var $kycProvider = z.enum(["SUMSUB"]);
+var KYCProviderSchema = $kycProvider;
+var $surfaceProvider = z.enum([...$provider.options, ...$kycProvider.options]);
+var SurfaceProviderSchema = $surfaceProvider;
 var $orderStatus = z.enum([
   "CREATING",
   "AWAITING_PAYMENT",
@@ -384,13 +392,22 @@ var $refund = obj({
   expectedBy: z.string()
 });
 var RefundSchema = $refund;
-var $surface = z.union([
-  obj({ kind: z.literal("URL_REDIRECT"), url: z.string() }),
-  obj({ kind: z.literal("URL_EMBED"), url: z.string() }),
-  obj({ kind: z.literal("PCI_COMPONENT"), session: z.string() }),
-  obj({ kind: z.literal("PAY_SHEET"), session: z.string() }),
-  obj({ kind: z.literal("ACH_COMPONENT"), session: z.string() })
-]);
+var $surfaceKind = z.enum(["URL_REDIRECT", "URL_EMBED", "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: z.record(z.string(), JsonSchema),
+  expiresAt: z.string().optional()
+});
 var SurfaceSchema = $surface;
 var $instructionField = obj({
   id: z.string(),
@@ -520,6 +537,8 @@ var AuthChallengeSchema = $authChallenge;
 var $quoteState = obj({
   kind: 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;
@@ -674,6 +693,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",
@@ -812,7 +889,11 @@ var FIXTURE_DATA = {
       "phase": "CAPTURE",
       "surface": {
         "kind": "PCI_COMPONENT",
-        "session": "eyJ\u2026"
+        "provider": "TRANSAK",
+        "params": {
+          "sessionId": "eyJ\u2026",
+          "environment": "STAGING"
+        }
       }
     },
     "provider": "TRANSAK",
@@ -1137,6 +1218,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",
@@ -1374,6 +1467,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)) {
@@ -1463,6 +1566,7 @@ export {
   InstructionsSchema,
   InstrumentSchema,
   JsonSchema,
+  KYCProviderSchema,
   KycCaptureStateSchema,
   KycInputRequiredStateSchema,
   KycNoActionRequiredStateSchema,
@@ -1485,6 +1589,8 @@ export {
   SelectOptionSchema,
   SessionAuthStateSchema,
   StatusHistoryEntrySchema,
+  SurfaceKindSchema,
+  SurfaceProviderSchema,
   SurfaceSchema,
   TABLE_VERSION,
   TERMINAL_ORDER_STATUSES,
@@ -1493,6 +1599,8 @@ export {
   TransitionParamsSchema,
   TransitionSchema,
   TxSchema,
+  UNOFFERED_ENDPOINTS,
+  UNREACHABLE_STATES,
   assertAllFixtures,
   assertFiatStepResponse,
   assertFixture,
@@ -1507,6 +1615,8 @@ export {
   looksLikeFieldSpec,
   stateKey,
   tableEntry,
+  unofferedEndpoints,
+  unreachableStates,
   walkTable
 };
 //# sourceMappingURL=index.mjs.map

package/dist/schemas.d.ts

@@ -27,13 +27,15 @@
  * They are module-private, so none of it reaches the published declarations.
  */
 import { z } from 'zod';
-import type { CryptoAmount, FailureReason, FeeLine, FiatEndpoint, FieldSpec, FlowState, FormDescriptor, FormField, FormFieldType, Instructions, InstructionField, Instrument, JsonValue, FiatAmount, OrderRef, OrderStatus, OrderSummary, PollSpec, FiatProvider, Quote, Recovery, Refund, ReportSpec, SelectOption, StatusHistoryEntry, FiatStepResponse, Surface, Transition, TransitionInputs, TransitionParams, Tx } from './types';
+import type { CryptoAmount, FailureReason, FeeLine, FiatEndpoint, FieldSpec, FlowState, FormDescriptor, FormField, FormFieldType, Instructions, InstructionField, Instrument, JsonValue, FiatAmount, OrderRef, OrderStatus, OrderSummary, PollSpec, FiatProvider, Quote, Recovery, Refund, ReportSpec, SelectOption, StatusHistoryEntry, FiatStepResponse, Surface, SurfaceKind, SurfaceProvider, KYCProvider, Transition, TransitionInputs, TransitionParams, Tx } from './types';
 export declare const JsonSchema: z.ZodType<JsonValue>;
 export declare const HTTP_VERBS: readonly ["GET", "POST"];
 /** `"POST /fiat/session/verify"`, `"GET /fiat/orders/o_31c"` — the verb rides the string. */
 export declare const ENDPOINT_PATTERN: RegExp;
 export declare const FiatEndpointSchema: z.ZodType<FiatEndpoint>;
 export declare const FiatProviderSchema: z.ZodType<FiatProvider>;
+export declare const KYCProviderSchema: z.ZodType<KYCProvider>;
+export declare const SurfaceProviderSchema: z.ZodType<SurfaceProvider>;
 export declare const OrderStatusSchema: z.ZodType<OrderStatus>;
 export declare const RecoverySchema: z.ZodType<Recovery>;
 export declare const FailureReasonSchema: z.ZodType<FailureReason>;
@@ -47,6 +49,7 @@ export declare const OrderSummarySchema: z.ZodType<OrderSummary>;
 export declare const StatusHistoryEntrySchema: z.ZodType<StatusHistoryEntry>;
 export declare const TxSchema: z.ZodType<Tx>;
 export declare const RefundSchema: z.ZodType<Refund>;
+export declare const SurfaceKindSchema: z.ZodType<SurfaceKind>;
 export declare const SurfaceSchema: z.ZodType<Surface>;
 export declare const InstructionFieldSchema: z.ZodType<InstructionField>;
 export declare const InstructionsSchema: z.ZodType<Instructions>;

package/dist/table.d.ts

@@ -84,10 +84,45 @@ export interface TableEntry {
 export declare const TRANSITION_TABLE: Readonly<Record<StateKey, TableEntry>>;
 export declare const STATE_KEYS: StateKey[];
 /**
- * The `/fiat/*` surface as enumerated in contract §Endpoints. Informational data — emissions are
- * checked against each state's `allowedTransitions`, not against this list.
+ * The `/fiat/*` surface. Informational data — emissions are checked against each state's
+ * `allowedTransitions`, not against this list.
+ *
+ * Sourced from contract §Endpoints, with one deliberate divergence: `POST /fiat/payment-session` is
+ * named by the table (QUOTE's capture-first entry) while the doc's endpoint table still lists no
+ * session-minting call for that rail.
+ */
+export declare const DOCUMENTED_ENDPOINTS: readonly ["GET /fiat/payment-methods", "POST /fiat/quote", "POST /fiat/auth", "POST /fiat/payment-session", "POST /fiat/session", "POST /fiat/session/verify", "GET /fiat/kyc", "POST /fiat/kyc/form", "POST /fiat/kyc/document", "POST /fiat/instruments", "POST /fiat/orders", "GET /fiat/orders/:id", "GET /fiat/orders/:id/instructions", "POST /fiat/orders/:id/confirm-payment", "POST /fiat/orders/:id/reference", "POST /fiat/orders/:id/cancel", "POST /fiat/orders/:id/surface-result"];
+/**
+ * Documented endpoints no flow state offers, and why. Declared so an endpoint nothing can reach is
+ * visible instead of silent — the table test asserts the unoffered set equals exactly these.
+ */
+export declare const UNOFFERED_ENDPOINTS: readonly {
+    endpoint: EndpointTemplate;
+    reason: string;
+}[];
+/**
+ * States entered out-of-band rather than by returning from a call. Declared so an unreachable state
+ * is visible instead of silent — the table test asserts reachability from QUOTE equals (all state
+ * keys − these).
+ */
+export declare const UNREACHABLE_STATES: readonly {
+    stateKey: StateKey;
+    reason: string;
+}[];
+/**
+ * The live answer to what `UNOFFERED_ENDPOINTS` declares: documented endpoints that no state's
+ * `allowedTransitions` names. The table test asserts the two agree, so a new orphan and a stale
+ * declaration both fail.
+ */
+export declare function unofferedEndpoints(): readonly EndpointTemplate[];
+/**
+ * The live answer to what `UNREACHABLE_STATES` declares: states no `mayReturn` path reaches from
+ * `QUOTE`, the flow's entry. The table test asserts the two agree.
+ *
+ * `mayReturn` is the only edge set the contract publishes, so it is the only graph there is to walk
+ * — a state absent from every one of them cannot be arrived at by following the contract.
  */
-export declare const DOCUMENTED_ENDPOINTS: readonly ["GET /fiat/payment-methods", "POST /fiat/quote", "POST /fiat/auth", "POST /fiat/session", "POST /fiat/session/verify", "GET /fiat/kyc", "POST /fiat/kyc/form", "POST /fiat/kyc/document", "POST /fiat/instruments", "POST /fiat/orders", "GET /fiat/orders/:id", "GET /fiat/orders/:id/instructions", "POST /fiat/orders/:id/confirm-payment", "POST /fiat/orders/:id/reference", "POST /fiat/orders/:id/cancel", "POST /fiat/orders/:id/surface-result"];
+export declare function unreachableStates(from?: StateKey): readonly StateKey[];
 /** State → its table key. The one place kind/phase/reason is flattened. */
 export declare function stateKey(state: FlowState): StateKey;
 export declare const tableEntry: (state: FlowState) => TableEntry;

package/dist/table.js

@@ -25,14 +25,18 @@ __export(table_exports, {
   TABLE_VERSION: () => TABLE_VERSION,
   TERMINAL_ORDER_STATUSES: () => TERMINAL_ORDER_STATUSES,
   TRANSITION_TABLE: () => TRANSITION_TABLE,
+  UNOFFERED_ENDPOINTS: () => UNOFFERED_ENDPOINTS,
+  UNREACHABLE_STATES: () => UNREACHABLE_STATES,
   isTerminal: () => isTerminal,
   stateKey: () => stateKey,
-  tableEntry: () => tableEntry
+  tableEntry: () => tableEntry,
+  unofferedEndpoints: () => unofferedEndpoints,
+  unreachableStates: () => unreachableStates
 });
 module.exports = __toCommonJS(table_exports);
 
 // package.json
-var version = "0.6.0";
+var version = "0.7.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -63,22 +67,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",
@@ -86,8 +114,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: {
@@ -385,6 +415,7 @@ 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",
@@ -399,6 +430,54 @@ var DOCUMENTED_ENDPOINTS = [
   "POST /fiat/orders/:id/cancel",
   "POST /fiat/orders/:id/surface-result"
 ];
+var UNOFFERED_ENDPOINTS = [
+  {
+    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 stream to it directly; the harness owns that upload 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":

package/dist/table.mjs

@@ -4,18 +4,26 @@ import {
   TABLE_VERSION,
   TERMINAL_ORDER_STATUSES,
   TRANSITION_TABLE,
+  UNOFFERED_ENDPOINTS,
+  UNREACHABLE_STATES,
   isTerminal,
   stateKey,
-  tableEntry
-} from "./chunk-EHYDQU4T.mjs";
+  tableEntry,
+  unofferedEndpoints,
+  unreachableStates
+} from "./chunk-OGNYHIOE.mjs";
 export {
   DOCUMENTED_ENDPOINTS,
   STATE_KEYS,
   TABLE_VERSION,
   TERMINAL_ORDER_STATUSES,
   TRANSITION_TABLE,
+  UNOFFERED_ENDPOINTS,
+  UNREACHABLE_STATES,
   isTerminal,
   stateKey,
-  tableEntry
+  tableEntry,
+  unofferedEndpoints,
+  unreachableStates
 };
 //# sourceMappingURL=table.mjs.map

package/dist/types.d.ts

@@ -65,8 +65,10 @@ export type FiatEndpoint = 'GET /fiat/payment-methods' | 'POST /fiat/quote' | 'P
  * `SWAPPED` added at fun-backend's request (2026-08-17) so its legacy fops payment-provider id
  * has one shared vocabulary instead of a second fun-backend-local enum — it never appears as a
  * `FiatStepResponse.provider` value since Swapped's fops flow doesn't emit this response.
+ * `BANXA` added at 0.7 (Provider Landscape: Tier 1). A vendor name here is a routing key only —
+ * it never decides which fields exist, which is what keeps provider churn out of this package.
  */
-export type FiatProvider = 'TRANSAK' | 'SWAPPED';
+export type FiatProvider = 'TRANSAK' | 'SWAPPED' | 'BANXA';
 /**
  * The order status vocabulary. Monotonic ranks, no backwards moves. Terminal outcomes are
  * OrderStatus, never FlowState kinds.
@@ -199,27 +201,45 @@ export interface Refund {
     amount: string;
     expectedBy: string;
 }
+/** What the user sees, and therefore where it can be placed. */
+export type SurfaceKind = 'URL_REDIRECT' | 'URL_EMBED' | 'PCI_COMPONENT' | 'PAY_SHEET' | 'ACH_COMPONENT';
 /**
- * Carried as *data* in CAPTURE phases only (`PAYMENT{CAPTURE}` · `KYC{CAPTURE}`).
- * Δ2: the CLIENT_SURFACE transition carries just `report` — single-carry, no duplication.
- * `session` values are secrets: never log them (FE doc §Decisions, redaction).
+ * Identity vendors Fun verifies into. Its own axis rather than a `FiatProvider` value, because
+ * Fun is the KYC-of-record in its own tenant — an identity surface is never the onramp's to mint.
+ * `SUMSUB` alone at 0.7; adding a value later is additive, and a vendor with no installed adapter
+ * lands on the client's existing unsupported screen.
  */
-export type Surface = {
-    kind: 'URL_REDIRECT';
-    url: string;
-} | {
-    kind: 'URL_EMBED';
-    url: string;
-} | {
-    kind: 'PCI_COMPONENT';
-    session: string;
-} | {
-    kind: 'PAY_SHEET';
-    session: string;
-} | {
-    kind: 'ACH_COMPONENT';
-    session: string;
-};
+export type KYCProvider = 'SUMSUB';
+/**
+ * Which adapter renders the surface. Can differ from `FiatStepResponse.provider`: an identity
+ * surface is Fun's to mint, not the onramp's.
+ *
+ * A routing key only — it never narrows the shape of `params`.
+ */
+export type SurfaceProvider = FiatProvider | KYCProvider;
+/**
+ * Carried as data in `QUOTE` (inline in the entry screen's primary slot) and in the CAPTURE
+ * phases (a screen of its own). Δ2 unchanged: the CLIENT_SURFACE transition carries only
+ * `report`, so a surface is never described twice.
+ *
+ * `params` is the adapter's vocabulary — opaque here, narrowed at the adapter boundary, and
+ * honoured verbatim. A provider's own `environment` value lives here and is never normalised:
+ * Transak's is `LOCAL | DEVELOPMENT | STAGING | PRODUCTION`, Banxa's is `sandbox | production`,
+ * and URL surfaces carry none, so a Fun-owned enum could only be lossy.
+ *
+ * `params` values are secrets by default. Client redaction defaults every key closed and opens
+ * only names that are safe under *any* provider's vocabulary.
+ */
+export interface Surface {
+    kind: SurfaceKind;
+    provider: SurfaceProvider;
+    params: Record<string, JsonValue>;
+    /**
+     * When the provider stops honouring the session, if it says so. Lets a client re-quote before
+     * the button goes dead; absent, the surface lives as long as the quote that carried it.
+     */
+    expiresAt?: string;
+}
 export interface InstructionField {
     id: string;
     labelFallback: string;
@@ -402,9 +422,16 @@ export type AuthChallenge = Record<string, JsonValue>;
  *   2. terminal outcomes are OrderStatus, never kinds
  *   3. every fallible state carries `error?: FailureReason`
  */
-export type FlowState = {
+export type FlowState = 
+/**
+ * `surface` present means the provider's own component IS the primary CTA, inline on the entry
+ * screen — the placement Apple policy forces for a pay sheet, since no visible step may sit
+ * between the Apple-branded tap and the sheet. Absent, the quote's SUBMITs drive our button.
+ */
+{
     kind: 'QUOTE';
     quote: Quote;
+    surface?: Surface;
     error?: FailureReason;
 } | {
     kind: 'FUN_AUTH';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fun-xyz/fiat-contract",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Published conformance contract for Fun's headless fiat onramp: FlowState/Transition types, zod schemas, the transition table as data, recorded fixtures, assertion helpers.",
   "license": "MIT",
   "repository": {
@@ -78,4 +78,4 @@
       ]
     }
   }
-}
+}