@fun-xyz/fiat-contract 0.5.0 → 0.7.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"]);
 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.5.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",
@@ -1766,18 +1937,18 @@ var FIXTURES = [
     docRef: "\xA7Worked example, steps 4\u20135 (order + bank instructions)",
     stateKey: "PAYMENT/INSTRUCT",
     notes: [
-      "The envelope-sibling `orderId` case. TODO(open-decision): orderId placement (envelope sibling here vs inside state in the FE doc v0)."
+      "The response-level `orderId` case. TODO(open-decision): orderId placement (beside `state` here vs inside it in the FE doc v0)."
     ]
   }
 ];
 var FIXTURE_COVERAGE_GAPS = [
   {
     stateKey: "FUN_AUTH",
-    reason: "No envelope 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."
+    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 envelope was ever published. Kind retained as handshake-gated vocabulary."
+    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) => {
@@ -1815,7 +1986,7 @@ var formatIssues = (error) => {
 };
 function assertFiatStepResponse(json) {
   const result = FiatStepResponseSchema.safeParse(json);
-  if (!result.success) throw new ContractViolation("invalid envelope", formatIssues(result.error));
+  if (!result.success) throw new ContractViolation("invalid fiat step response", formatIssues(result.error));
   return result.data;
 }
 function endpointMatches(template, actual) {
@@ -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)) {
@@ -1912,14 +2093,14 @@ function walkTable(fn) {
 function assertFixture(id) {
   const meta = fixtureMeta(id);
   const json = loadFixture(id);
-  const envelope = assertFiatStepResponse(json);
-  if (stateKey(envelope.state) !== meta.stateKey) {
+  const stepResponse = assertFiatStepResponse(json);
+  if (stateKey(stepResponse.state) !== meta.stateKey) {
     throw new ContractViolation(
-      `fixture ${id}: manifest says ${meta.stateKey}, envelope carries ${stateKey(envelope.state)}`
+      `fixture ${id}: manifest says ${meta.stateKey}, step response carries ${stateKey(stepResponse.state)}`
     );
   }
-  assertLegalEmission(envelope.state, envelope.transitions);
-  return { meta, envelope };
+  assertLegalEmission(stepResponse.state, stepResponse.transitions);
+  return { meta, stepResponse };
 }
 function assertAllFixtures() {
   return FIXTURES.map((meta) => assertFixture(meta.id));

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-3R5GGUAK.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",
@@ -1273,18 +1366,18 @@ var FIXTURES = [
     docRef: "\xA7Worked example, steps 4\u20135 (order + bank instructions)",
     stateKey: "PAYMENT/INSTRUCT",
     notes: [
-      "The envelope-sibling `orderId` case. TODO(open-decision): orderId placement (envelope sibling here vs inside state in the FE doc v0)."
+      "The response-level `orderId` case. TODO(open-decision): orderId placement (beside `state` here vs inside it in the FE doc v0)."
     ]
   }
 ];
 var FIXTURE_COVERAGE_GAPS = [
   {
     stateKey: "FUN_AUTH",
-    reason: "No envelope 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."
+    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 envelope was ever published. Kind retained as handshake-gated vocabulary."
+    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) => {
@@ -1322,7 +1415,7 @@ var formatIssues = (error) => {
 };
 function assertFiatStepResponse(json) {
   const result = FiatStepResponseSchema.safeParse(json);
-  if (!result.success) throw new ContractViolation("invalid envelope", formatIssues(result.error));
+  if (!result.success) throw new ContractViolation("invalid fiat step response", formatIssues(result.error));
   return result.data;
 }
 function endpointMatches(template, actual) {
@@ -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)) {
@@ -1419,14 +1522,14 @@ function walkTable(fn) {
 function assertFixture(id) {
   const meta = fixtureMeta(id);
   const json = loadFixture(id);
-  const envelope = assertFiatStepResponse(json);
-  if (stateKey(envelope.state) !== meta.stateKey) {
+  const stepResponse = assertFiatStepResponse(json);
+  if (stateKey(stepResponse.state) !== meta.stateKey) {
     throw new ContractViolation(
-      `fixture ${id}: manifest says ${meta.stateKey}, envelope carries ${stateKey(envelope.state)}`
+      `fixture ${id}: manifest says ${meta.stateKey}, step response carries ${stateKey(stepResponse.state)}`
     );
   }
-  assertLegalEmission(envelope.state, envelope.transitions);
-  return { meta, envelope };
+  assertLegalEmission(stepResponse.state, stepResponse.transitions);
+  return { meta, stepResponse };
 }
 function assertAllFixtures() {
   return FIXTURES.map((meta) => assertFixture(meta.id));
@@ -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

@@ -2,7 +2,7 @@
  * fiat-contract — zod schemas
  *
  * zod is the single runtime validator: TypeScript cannot validate at the boundary, and the
- * table (`src/table.ts`) cannot reject a *malformed* envelope — only an illegal *sequence*.
+ * table (`src/table.ts`) cannot reject a *malformed* step response — only an illegal *sequence*.
  *
  * Every object schema is `.strict()`: an undeclared key is a contract violation, not extra data.
  *
@@ -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>;