@fun-xyz/fiat-contract 0.6.0 → 0.8.0

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-LVVQ46YG.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", "MOONPAY", "STRIPE"]);
 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", "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: 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;
@@ -538,6 +557,7 @@ var SessionAuthStateSchema = $sessionAuthState;
 var $kycCaptureState = obj({
   kind: z.literal("KYC"),
   phase: z.literal("CAPTURE"),
+  quote: $quote,
   surface: $surface,
   error: $failureReason.optional()
 });
@@ -545,6 +565,7 @@ var KycCaptureStateSchema = $kycCaptureState;
 var $kycInputRequiredState = obj({
   kind: z.literal("KYC"),
   phase: z.literal("INPUT_REQUIRED"),
+  quote: $quote,
   form: $formDescriptor,
   error: $failureReason.optional()
 });
@@ -552,6 +573,7 @@ var KycInputRequiredStateSchema = $kycInputRequiredState;
 var $kycNoActionRequiredState = obj({
   kind: z.literal("KYC"),
   phase: z.literal("NO_ACTION_REQUIRED"),
+  quote: $quote,
   reason: z.enum(["IN_REVIEW", "ON_HOLD", "REJECTED"]),
   retryAfter: z.string().optional(),
   failureReason: $failureReason.optional(),
@@ -674,6 +696,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",
@@ -701,45 +781,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",
+            "labelFallback": "Tax ID",
             "required": true
           },
           {
-            "id": "dob",
-            "type": "DATE",
-            "labelFallback": "Date of birth",
-            "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"
           }
         ]
       }
@@ -751,7 +829,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": {
@@ -812,7 +891,11 @@ var FIXTURE_DATA = {
       "phase": "CAPTURE",
       "surface": {
         "kind": "PCI_COMPONENT",
-        "session": "eyJ\u2026"
+        "provider": "TRANSAK",
+        "params": {
+          "sessionId": "eyJ\u2026",
+          "environment": "STAGING"
+        }
       }
     },
     "provider": "TRANSAK",
@@ -832,11 +915,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": [
@@ -844,10 +1000,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,
@@ -861,28 +1014,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": {
@@ -1137,6 +1332,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",
@@ -1148,8 +1355,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."]
@@ -1177,34 +1384,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",
@@ -1249,7 +1462,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",
@@ -1281,10 +1494,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) => {
@@ -1374,6 +1583,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 +1682,7 @@ export {
   InstructionsSchema,
   InstrumentSchema,
   JsonSchema,
+  KYCProviderSchema,
   KycCaptureStateSchema,
   KycInputRequiredStateSchema,
   KycNoActionRequiredStateSchema,
@@ -1485,6 +1705,8 @@ export {
   SelectOptionSchema,
   SessionAuthStateSchema,
   StatusHistoryEntrySchema,
+  SurfaceKindSchema,
+  SurfaceProviderSchema,
   SurfaceSchema,
   TABLE_VERSION,
   TERMINAL_ORDER_STATUSES,
@@ -1493,6 +1715,8 @@ export {
   TransitionParamsSchema,
   TransitionSchema,
   TxSchema,
+  UNOFFERED_ENDPOINTS,
+  UNREACHABLE_STATES,
   assertAllFixtures,
   assertFiatStepResponse,
   assertFixture,
@@ -1507,6 +1731,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

@@ -42,8 +42,7 @@ export type StateKey = 'QUOTE' | 'FUN_AUTH' | 'SESSION_AUTH' | 'KYC/CAPTURE' | '
 export declare const TERMINAL_ORDER_STATUSES: readonly ["SETTLED", "EXPIRED", "CANCELLED", "FAILED", "REFUNDED"];
 export type TerminalOrderStatus = (typeof TERMINAL_ORDER_STATUSES)[number];
 /**
- * Endpoint template as written in the docs — `:id` stands for an order id, so
- * `"POST /fiat/orders/:id/cancel"` matches the emitted `"POST /fiat/orders/o_31c/cancel"`.
+ * Endpoint template as written in the docs. Named `:` segments match one emitted path segment.
  */
 export type EndpointTemplate = FiatEndpoint;
 export interface AllowedTransition {
@@ -84,10 +83,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/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", "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;