@fun-xyz/fiat-contract 0.2.1

package/dist/index.js

@@ -0,0 +1,1665 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthChallengeSchema: () => AuthChallengeSchema,
+  BlockedStateSchema: () => BlockedStateSchema,
+  ContractViolation: () => ContractViolation,
+  CryptoAmountSchema: () => CryptoAmountSchema,
+  DOCUMENTED_ENDPOINTS: () => DOCUMENTED_ENDPOINTS,
+  ENDPOINT_PATTERN: () => ENDPOINT_PATTERN,
+  EnvelopeSchema: () => EnvelopeSchema,
+  FIELD_SPEC_TYPES: () => FIELD_SPEC_TYPES,
+  FIXTURES: () => FIXTURES,
+  FIXTURE_COVERAGE_GAPS: () => FIXTURE_COVERAGE_GAPS,
+  FailureReasonSchema: () => FailureReasonSchema,
+  FeeLineSchema: () => FeeLineSchema,
+  FiatAmountSchema: () => FiatAmountSchema,
+  FiatEndpointSchema: () => FiatEndpointSchema,
+  FiatProviderSchema: () => FiatProviderSchema,
+  FieldSpecSchema: () => FieldSpecSchema,
+  FlowStateSchema: () => FlowStateSchema,
+  FormDescriptorSchema: () => FormDescriptorSchema,
+  FormFieldSchema: () => FormFieldSchema,
+  FormFieldTypeSchema: () => FormFieldTypeSchema,
+  FunAuthStateSchema: () => FunAuthStateSchema,
+  HTTP_VERBS: () => HTTP_VERBS,
+  InstructionFieldSchema: () => InstructionFieldSchema,
+  InstructionsSchema: () => InstructionsSchema,
+  InstrumentSchema: () => InstrumentSchema,
+  JsonSchema: () => JsonSchema,
+  KycCaptureStateSchema: () => KycCaptureStateSchema,
+  KycInputRequiredStateSchema: () => KycInputRequiredStateSchema,
+  KycNoActionRequiredStateSchema: () => KycNoActionRequiredStateSchema,
+  OrderAwaitingConfirmationStateSchema: () => OrderAwaitingConfirmationStateSchema,
+  OrderCreatedStateSchema: () => OrderCreatedStateSchema,
+  OrderRefSchema: () => OrderRefSchema,
+  OrderStatusSchema: () => OrderStatusSchema,
+  OrderSummarySchema: () => OrderSummarySchema,
+  PaymentCaptureStateSchema: () => PaymentCaptureStateSchema,
+  PaymentInstructStateSchema: () => PaymentInstructStateSchema,
+  PendingOrderStateSchema: () => PendingOrderStateSchema,
+  PollSpecSchema: () => PollSpecSchema,
+  QuoteSchema: () => QuoteSchema,
+  QuoteStateSchema: () => QuoteStateSchema,
+  RecoverySchema: () => RecoverySchema,
+  RefundSchema: () => RefundSchema,
+  ReportSpecSchema: () => ReportSpecSchema,
+  STATE_KEYS: () => STATE_KEYS,
+  SelectOptionSchema: () => SelectOptionSchema,
+  SessionAuthStateSchema: () => SessionAuthStateSchema,
+  StatusHistoryEntrySchema: () => StatusHistoryEntrySchema,
+  StepResponseFragmentSchema: () => StepResponseFragmentSchema,
+  StepResponseSchema: () => StepResponseSchema,
+  SurfaceSchema: () => SurfaceSchema,
+  TABLE_VERSION: () => TABLE_VERSION,
+  TERMINAL_ORDER_STATUSES: () => TERMINAL_ORDER_STATUSES,
+  TRANSITION_TABLE: () => TRANSITION_TABLE,
+  TransitionInputsSchema: () => TransitionInputsSchema,
+  TransitionParamsSchema: () => TransitionParamsSchema,
+  TransitionSchema: () => TransitionSchema,
+  TxSchema: () => TxSchema,
+  assertAllFixtures: () => assertAllFixtures,
+  assertEnvelope: () => assertEnvelope,
+  assertEnvelopeFragment: () => assertEnvelopeFragment,
+  assertFixture: () => assertFixture,
+  assertLegalEmission: () => assertLegalEmission,
+  assertLegalReturn: () => assertLegalReturn,
+  checkLegalEmission: () => checkLegalEmission,
+  endpointMatches: () => endpointMatches,
+  fixtureMeta: () => fixtureMeta,
+  isTerminal: () => isTerminal,
+  loadFixture: () => loadFixture,
+  loadFixtures: () => loadFixtures,
+  looksLikeFieldSpec: () => looksLikeFieldSpec,
+  stateKey: () => stateKey,
+  tableEntry: () => tableEntry,
+  walkTable: () => walkTable
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/schemas.ts
+var import_zod = require("zod");
+var obj = (shape) => import_zod.z.object(shape).strict();
+var JsonSchema = import_zod.z.lazy(
+  () => import_zod.z.union([
+    import_zod.z.string(),
+    import_zod.z.number(),
+    import_zod.z.boolean(),
+    import_zod.z.null(),
+    import_zod.z.array(JsonSchema),
+    import_zod.z.record(import_zod.z.string(), JsonSchema)
+  ])
+);
+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 FiatProviderSchema = $provider;
+var $orderStatus = import_zod.z.enum([
+  "CREATING",
+  "AWAITING_PAYMENT",
+  "PAYMENT_VERIFYING",
+  "PROCESSING",
+  "PENDING_DELIVERY",
+  "ON_HOLD",
+  "CRYPTO_SENT",
+  "SETTLED",
+  "EXPIRED",
+  "CANCELLED",
+  "FAILED",
+  "REFUNDED",
+  "CAPTURE_ORPHANED"
+]);
+var OrderStatusSchema = $orderStatus;
+var $recovery = import_zod.z.enum(["REQUOTE", "RETRY_PAYMENT", "CONTACT_SUPPORT", "NONE"]);
+var RecoverySchema = $recovery;
+var $failureReason = import_zod.z.union([
+  obj({
+    category: import_zod.z.enum([
+      "PAYMENT_DECLINED",
+      "KYC_REJECTED",
+      "PROVIDER_OUTAGE",
+      "USER_ERROR",
+      "CANCELLED"
+    ]),
+    retryable: import_zod.z.boolean(),
+    recovery: $recovery,
+    code: import_zod.z.string().optional()
+  }),
+  obj({
+    category: import_zod.z.literal("EXPIRED"),
+    which: import_zod.z.enum(["QUOTE", "PAYMENT_WINDOW", "INSTRUCTIONS"]),
+    retryable: import_zod.z.boolean(),
+    recovery: $recovery,
+    code: import_zod.z.string().optional()
+  })
+]);
+var FailureReasonSchema = $failureReason;
+var $money = obj({ currency: import_zod.z.string(), amount: import_zod.z.string() });
+var FiatAmountSchema = $money;
+var $cryptoAmount = obj({
+  currency: import_zod.z.string(),
+  network: import_zod.z.string(),
+  amount: import_zod.z.string()
+});
+var CryptoAmountSchema = $cryptoAmount;
+var $feeLine = obj({ id: import_zod.z.string(), labelFallback: import_zod.z.string(), amount: import_zod.z.string() });
+var FeeLineSchema = $feeLine;
+var $quote = obj({
+  quoteRef: import_zod.z.string(),
+  fiat: $money,
+  crypto: $cryptoAmount,
+  rate: import_zod.z.string(),
+  totalFee: import_zod.z.string(),
+  feeBreakdown: import_zod.z.array($feeLine),
+  paymentMethod: import_zod.z.string(),
+  expiresAt: import_zod.z.string()
+});
+var QuoteSchema = $quote;
+var $instrument = obj({ brandLabel: import_zod.z.string(), last4: import_zod.z.string() });
+var InstrumentSchema = $instrument;
+var $orderRef = obj({
+  orderId: import_zod.z.string(),
+  fiat: $money,
+  crypto: $cryptoAmount,
+  method: import_zod.z.string(),
+  createdAt: import_zod.z.string(),
+  status: $orderStatus
+});
+var OrderRefSchema = $orderRef;
+var $orderSummary = obj({
+  orderId: import_zod.z.string(),
+  fiat: $money,
+  crypto: $cryptoAmount.optional(),
+  method: import_zod.z.string(),
+  createdAt: import_zod.z.string(),
+  instrument: $instrument.optional()
+});
+var OrderSummarySchema = $orderSummary;
+var $statusHistoryEntry = obj({ status: $orderStatus });
+var StatusHistoryEntrySchema = $statusHistoryEntry;
+var $tx = obj({ chainId: import_zod.z.number(), hash: import_zod.z.string() });
+var TxSchema = $tx;
+var $refund = obj({
+  currency: import_zod.z.string(),
+  amount: import_zod.z.string(),
+  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 SurfaceSchema = $surface;
+var $instructionField = obj({
+  id: import_zod.z.string(),
+  labelFallback: import_zod.z.string(),
+  value: import_zod.z.string()
+});
+var InstructionFieldSchema = $instructionField;
+var $instructions = import_zod.z.union([
+  obj({ kind: import_zod.z.literal("DEEPLINK"), url: import_zod.z.string(), appVariants: import_zod.z.array(import_zod.z.string()) }),
+  obj({ kind: import_zod.z.literal("QR_IMAGE"), url: import_zod.z.string() }),
+  obj({
+    kind: import_zod.z.literal("BANK_FIELDS"),
+    fields: import_zod.z.array($instructionField),
+    expiresAt: import_zod.z.string().optional()
+  }),
+  obj({ kind: import_zod.z.literal("REFERENCE"), code: import_zod.z.string(), expiresAt: import_zod.z.string() })
+]);
+var InstructionsSchema = $instructions;
+var $selectOption = obj({ id: import_zod.z.string(), labelFallback: import_zod.z.string() });
+var SelectOptionSchema = $selectOption;
+var $formFieldType = import_zod.z.enum(["TEXT", "DATE", "SELECT", "COUNTRY", "FILE", "HOSTED_LINK"]);
+var FormFieldTypeSchema = $formFieldType;
+var $formField = obj({
+  id: import_zod.z.string(),
+  type: $formFieldType,
+  labelFallback: import_zod.z.string(),
+  required: import_zod.z.boolean(),
+  regex: import_zod.z.string().optional(),
+  options: import_zod.z.array($selectOption).optional(),
+  url: import_zod.z.string().optional()
+});
+var FormFieldSchema = $formField;
+var $formDescriptor = obj({ formId: import_zod.z.string(), fields: import_zod.z.array($formField) });
+var FormDescriptorSchema = $formDescriptor;
+var FIELD_SPEC_TYPES = [
+  "TEXT",
+  "DATE",
+  "COUNTRY",
+  "FILE",
+  "SELECT",
+  "HOSTED_LINK",
+  "FORM_VALUES"
+];
+var $fieldSpec = import_zod.z.union([
+  obj({
+    type: import_zod.z.literal("TEXT"),
+    length: import_zod.z.number().optional(),
+    regex: import_zod.z.string().optional(),
+    labelFallback: import_zod.z.string().optional()
+  }),
+  obj({ type: import_zod.z.literal("DATE"), labelFallback: import_zod.z.string().optional() }),
+  obj({ type: import_zod.z.literal("COUNTRY"), labelFallback: import_zod.z.string().optional() }),
+  obj({ type: import_zod.z.literal("FILE"), labelFallback: import_zod.z.string().optional() }),
+  obj({
+    type: import_zod.z.literal("SELECT"),
+    options: import_zod.z.array($selectOption).optional(),
+    labelFallback: import_zod.z.string().optional()
+  }),
+  obj({ type: import_zod.z.literal("HOSTED_LINK"), url: import_zod.z.string(), labelFallback: import_zod.z.string().optional() }),
+  obj({ type: import_zod.z.literal("FORM_VALUES") })
+]);
+var FieldSpecSchema = $fieldSpec;
+var looksLikeFieldSpec = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.type === "string" && FIELD_SPEC_TYPES.includes(value.type);
+var $params = import_zod.z.record(import_zod.z.string(), JsonSchema).superRefine((params, ctx) => {
+  for (const [key, value] of Object.entries(params)) {
+    if (looksLikeFieldSpec(value)) {
+      ctx.addIssue({
+        code: "custom",
+        path: [key],
+        message: `params.${key} is FieldSpec-shaped ({type: "\u2026"}). params carry server literals the client spreads verbatim; a spec the client must collect belongs in inputs.`
+      });
+    }
+  }
+});
+var TransitionParamsSchema = $params;
+var $inputs = import_zod.z.record(import_zod.z.string(), $fieldSpec);
+var TransitionInputsSchema = $inputs;
+var $pollSpec = obj({
+  endpoint: $endpoint,
+  params: $params.optional(),
+  intervalMs: import_zod.z.number(),
+  backoffFactor: import_zod.z.number().optional(),
+  maxIntervalMs: import_zod.z.number().optional(),
+  giveUpAfterMs: import_zod.z.number().optional()
+});
+var PollSpecSchema = $pollSpec;
+var $reportSpec = obj({
+  endpoint: $endpoint,
+  params: $params.optional(),
+  expects: import_zod.z.array(import_zod.z.string()).optional()
+});
+var ReportSpecSchema = $reportSpec;
+var $transition = import_zod.z.union([
+  obj({
+    id: import_zod.z.string(),
+    mode: import_zod.z.literal("SUBMIT"),
+    endpoint: $endpoint,
+    params: $params.optional(),
+    inputs: $inputs.optional(),
+    labelFallback: import_zod.z.string().optional()
+  }),
+  obj({ id: import_zod.z.string(), mode: import_zod.z.literal("AWAIT"), poll: $pollSpec }),
+  obj({ id: import_zod.z.string(), mode: import_zod.z.literal("CLIENT_SURFACE"), report: $reportSpec })
+]);
+var TransitionSchema = $transition;
+var $authChallenge = import_zod.z.record(import_zod.z.string(), JsonSchema);
+var AuthChallengeSchema = $authChallenge;
+var $quoteState = obj({
+  kind: import_zod.z.literal("QUOTE"),
+  quote: $quote,
+  error: $failureReason.optional()
+});
+var QuoteStateSchema = $quoteState;
+var $funAuthState = obj({
+  kind: import_zod.z.literal("FUN_AUTH"),
+  challenge: $authChallenge,
+  error: $failureReason.optional()
+});
+var FunAuthStateSchema = $funAuthState;
+var $sessionAuthState = obj({
+  kind: import_zod.z.literal("SESSION_AUTH"),
+  channel: import_zod.z.literal("EMAIL_OTP"),
+  error: $failureReason.optional()
+});
+var SessionAuthStateSchema = $sessionAuthState;
+var $kycCaptureState = obj({
+  kind: import_zod.z.literal("KYC"),
+  phase: import_zod.z.literal("CAPTURE"),
+  surface: $surface,
+  error: $failureReason.optional()
+});
+var KycCaptureStateSchema = $kycCaptureState;
+var $kycInputRequiredState = obj({
+  kind: import_zod.z.literal("KYC"),
+  phase: import_zod.z.literal("INPUT_REQUIRED"),
+  form: $formDescriptor,
+  error: $failureReason.optional()
+});
+var KycInputRequiredStateSchema = $kycInputRequiredState;
+var $kycNoActionRequiredState = obj({
+  kind: import_zod.z.literal("KYC"),
+  phase: import_zod.z.literal("NO_ACTION_REQUIRED"),
+  reason: import_zod.z.enum(["IN_REVIEW", "ON_HOLD", "REJECTED"]),
+  retryAfter: import_zod.z.string().optional(),
+  failureReason: $failureReason.optional(),
+  error: $failureReason.optional()
+});
+var KycNoActionRequiredStateSchema = $kycNoActionRequiredState;
+var $pendingOrderState = obj({
+  kind: import_zod.z.literal("PENDING_ORDER"),
+  order: $orderRef,
+  error: $failureReason.optional()
+});
+var PendingOrderStateSchema = $pendingOrderState;
+var $blockedState = obj({
+  kind: import_zod.z.literal("BLOCKED"),
+  reason: import_zod.z.string(),
+  retryAfter: import_zod.z.string().nullable().optional(),
+  error: $failureReason.optional()
+});
+var BlockedStateSchema = $blockedState;
+var $paymentCaptureState = obj({
+  kind: import_zod.z.literal("PAYMENT"),
+  phase: import_zod.z.literal("CAPTURE"),
+  surface: $surface,
+  error: $failureReason.optional()
+});
+var PaymentCaptureStateSchema = $paymentCaptureState;
+var $paymentInstructState = obj({
+  kind: import_zod.z.literal("PAYMENT"),
+  phase: import_zod.z.literal("INSTRUCT"),
+  orderId: import_zod.z.string().optional(),
+  instructions: $instructions,
+  error: $failureReason.optional()
+});
+var PaymentInstructStateSchema = $paymentInstructState;
+var $orderAwaitingConfirmationState = obj({
+  kind: import_zod.z.literal("ORDER"),
+  phase: import_zod.z.literal("AWAITING_CONFIRMATION"),
+  quote: $quote,
+  error: $failureReason.optional()
+});
+var OrderAwaitingConfirmationStateSchema = $orderAwaitingConfirmationState;
+var $orderCreatedState = obj({
+  kind: import_zod.z.literal("ORDER"),
+  phase: import_zod.z.literal("CREATED"),
+  order: $orderSummary.optional(),
+  status: $orderStatus,
+  statusHistory: import_zod.z.array($statusHistoryEntry).optional(),
+  tx: $tx.optional(),
+  refund: $refund.optional(),
+  failureReason: $failureReason.optional(),
+  error: $failureReason.optional()
+});
+var OrderCreatedStateSchema = $orderCreatedState;
+var $flowState = import_zod.z.union([
+  $quoteState,
+  $funAuthState,
+  $sessionAuthState,
+  $kycCaptureState,
+  $kycInputRequiredState,
+  $kycNoActionRequiredState,
+  $pendingOrderState,
+  $blockedState,
+  $paymentCaptureState,
+  $paymentInstructState,
+  $orderAwaitingConfirmationState,
+  $orderCreatedState
+]);
+var FlowStateSchema = $flowState;
+var $stepResponse = obj({
+  state: $flowState,
+  provider: $provider,
+  transitions: import_zod.z.array($transition),
+  orderId: import_zod.z.string().optional()
+});
+var StepResponseSchema = $stepResponse;
+var $stepResponseFragment = obj({
+  state: $flowState,
+  provider: $provider.optional(),
+  transitions: import_zod.z.array($transition),
+  orderId: import_zod.z.string().optional()
+});
+var StepResponseFragmentSchema = $stepResponseFragment;
+var EnvelopeSchema = StepResponseSchema;
+
+// src/table.ts
+var TABLE_VERSION = "0.2.1";
+var TERMINAL_ORDER_STATUSES = [
+  "SETTLED",
+  "EXPIRED",
+  "CANCELLED",
+  "FAILED",
+  "REFUNDED"
+];
+var KYC_ANY = [
+  "KYC/CAPTURE",
+  "KYC/INPUT_REQUIRED",
+  "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
+  "KYC/NO_ACTION_REQUIRED:ON_HOLD",
+  "KYC/NO_ACTION_REQUIRED:REJECTED"
+];
+var TRANSITION_TABLE = {
+  QUOTE: {
+    key: "QUOTE",
+    kind: "QUOTE",
+    screens: [1],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [
+      {
+        id: "continue",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/session",
+        when: "no valid provider session token (own-tables check)"
+      },
+      {
+        id: "continue",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/orders",
+        when: "returning user, session + KYC valid \u2014 the quote screen doubles as review"
+      },
+      {
+        id: "continue",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/auth",
+        when: "no ambient Fun identity (non-fomo surfaces only)"
+      }
+    ],
+    mayReturn: [
+      "SESSION_AUTH",
+      ...KYC_ANY,
+      "PENDING_ORDER",
+      "ORDER/AWAITING_CONFIRMATION",
+      "ORDER/CREATED",
+      "BLOCKED"
+    ],
+    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".'
+    ]
+  },
+  FUN_AUTH: {
+    key: "FUN_AUTH",
+    kind: "FUN_AUTH",
+    screens: [],
+    docStatus: "UNSPECIFIED",
+    allowedTransitions: [],
+    terminal: false,
+    notes: [
+      "TODO(open-decision): shape and transitions owned by the auth spike (contract \xA7Auth & ref binding, item 5).",
+      "Never renders in fomo \u2014 identity is ambient, so the FE doc gives it no screen and no bindings row."
+    ]
+  },
+  SESSION_AUTH: {
+    key: "SESSION_AUTH",
+    kind: "SESSION_AUTH",
+    screens: [2],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [
+      { id: "verify", mode: "SUBMIT", endpoint: "POST /fiat/session/verify" }
+    ],
+    mayReturn: [
+      "SESSION_AUTH",
+      ...KYC_ANY,
+      "ORDER/AWAITING_CONFIRMATION",
+      "PENDING_ORDER"
+    ],
+    terminal: false,
+    notes: [
+      "A bad code re-enters this same state with error {category: USER_ERROR, code: BAD_CODE} \u2014 banner, not a screen change.",
+      "No resend affordance is specified in either doc (known gap, FE doc Screen 2)."
+    ]
+  },
+  "KYC/CAPTURE": {
+    key: "KYC/CAPTURE",
+    kind: "KYC",
+    phase: "CAPTURE",
+    screens: [8],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [
+      {
+        id: "capture",
+        mode: "CLIENT_SURFACE",
+        endpoint: "GET /fiat/kyc",
+        note: 'report target per FE bindings ("POST surface report \u2192 GET /fiat/kyc") and contract Flow C.'
+      }
+    ],
+    mayReturn: [
+      "KYC/INPUT_REQUIRED",
+      "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
+      "KYC/NO_ACTION_REQUIRED:ON_HOLD",
+      "KYC/NO_ACTION_REQUIRED:REJECTED",
+      "ORDER/AWAITING_CONFIRMATION"
+    ],
+    terminal: false,
+    notes: [
+      "Dropped from v1 (no UK headless-module coverage) \u2014 FE Screen 8 is a tombstone. Kind retained as vocabulary; the handshake (supportedStepKinds) keeps the backend from routing v1 SDKs here."
+    ]
+  },
+  "KYC/INPUT_REQUIRED": {
+    key: "KYC/INPUT_REQUIRED",
+    kind: "KYC",
+    phase: "INPUT_REQUIRED",
+    screens: [3],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [
+      { id: "submit_round", mode: "SUBMIT", endpoint: "POST /fiat/kyc/form" }
+    ],
+    mayReturn: [
+      "KYC/INPUT_REQUIRED",
+      "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
+      "KYC/NO_ACTION_REQUIRED:ON_HOLD",
+      "KYC/NO_ACTION_REQUIRED:REJECTED",
+      "ORDER/AWAITING_CONFIRMATION"
+    ],
+    terminal: false,
+    notes: [
+      "One POST per round; conditional requirements may open another round.",
+      "FILE fields stream to POST /fiat/kyc/document \u2014 an upload path the harness owns, not a transition.",
+      "Hosted KYC links arrive as HOSTED_LINK form fields, not as a Surface."
+    ]
+  },
+  "KYC/NO_ACTION_REQUIRED:IN_REVIEW": {
+    key: "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
+    kind: "KYC",
+    phase: "NO_ACTION_REQUIRED",
+    reason: "IN_REVIEW",
+    screens: [9],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [{ id: "poll", mode: "AWAIT", endpoint: "GET /fiat/kyc" }],
+    mayReturn: [
+      "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
+      "KYC/INPUT_REQUIRED",
+      "KYC/NO_ACTION_REQUIRED:ON_HOLD",
+      "KYC/NO_ACTION_REQUIRED:REJECTED",
+      "ORDER/AWAITING_CONFIRMATION"
+    ],
+    terminal: false,
+    notes: [
+      "Documented poll shape: intervalMs 3000, backoffFactor 1.5, maxIntervalMs 10000, giveUpAfterMs 90000.",
+      "Pre-order giveUp destination is a design gap (FE doc Screen 9) \u2014 client-local, no contract impact."
+    ]
+  },
+  "KYC/NO_ACTION_REQUIRED:ON_HOLD": {
+    key: "KYC/NO_ACTION_REQUIRED:ON_HOLD",
+    kind: "KYC",
+    phase: "NO_ACTION_REQUIRED",
+    reason: "ON_HOLD",
+    screens: [10],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [],
+    mayReturn: KYC_ANY,
+    terminal: false,
+    notes: [
+      "THE proof that terminality is not array emptiness: transitions [] and NOT terminal. Re-entry after retryAfter re-derives."
+    ]
+  },
+  "KYC/NO_ACTION_REQUIRED:REJECTED": {
+    key: "KYC/NO_ACTION_REQUIRED:REJECTED",
+    kind: "KYC",
+    phase: "NO_ACTION_REQUIRED",
+    reason: "REJECTED",
+    screens: [11],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [
+      {
+        id: "escalate",
+        mode: "SUBMIT",
+        endpoint: "GET /fiat/kyc",
+        when: "an escalation round is offered",
+        note: "TODO(open-decision): placeholder shape \u2014 the FE doc flags that a GET carrying params is not a real request shape, and OQ7 owns which rejections escalate. FE doc open question 7."
+      }
+    ],
+    mayReturn: KYC_ANY,
+    terminal: false,
+    notes: [
+      "Terminal *variant*: failureReason {KYC_REJECTED, retryable: false, recovery: CONTACT_SUPPORT} + transitions [] \u2014 renders in place, never routes through ORDER{CREATED, FAILED}. Because escalation is also legal here, the entry is not flatly terminal.",
+      "TODO(open-decision): contract OQ7 \u2014 terminal vs escalating rejections are not enumerated."
+    ]
+  },
+  PENDING_ORDER: {
+    key: "PENDING_ORDER",
+    kind: "PENDING_ORDER",
+    screens: [12],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [
+      { id: "resume", mode: "SUBMIT", endpoint: "GET /fiat/orders/:id" },
+      { id: "cancel", mode: "SUBMIT", endpoint: "POST /fiat/orders/:id/cancel" }
+    ],
+    mayReturn: ["ORDER/CREATED", "QUOTE"],
+    terminal: false,
+    notes: [
+      'TODO(open-decision): removal proposed (contract \xA7"Proposal: remove PENDING_ORDER"); FE Screen 12 is frozen until it lands. The two-call resume-or-cancel shape is why transitions is an array.',
+      "SUBMIT is a user-fired request, not a POST: GET /fiat/orders/:id under SUBMIT is legal."
+    ]
+  },
+  BLOCKED: {
+    key: "BLOCKED",
+    kind: "BLOCKED",
+    screens: [16],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [],
+    mayReturn: [],
+    terminal: true,
+    notes: [
+      "Region/compliance block \u2014 fires from anywhere (contract \xA7Global transitions). retryAfter renders a dated comeback; null = none.",
+      "TODO(open-decision): v1 scope assumed yes for FCA/UK \u2014 product confirm (FE doc open question 4)."
+    ]
+  },
+  "PAYMENT/CAPTURE": {
+    key: "PAYMENT/CAPTURE",
+    kind: "PAYMENT",
+    phase: "CAPTURE",
+    screens: [5],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [
+      {
+        id: "capture",
+        mode: "CLIENT_SURFACE",
+        endpoint: "POST /fiat/orders",
+        when: "capture-then-order topology (Transak headless cards: the component yields requestId, an input to createOrder)",
+        note: 'TODO(open-decision): report target per card topology \u2014 Transak ask (contract Flow A: "confirm before freeze").'
+      },
+      {
+        id: "capture",
+        mode: "CLIENT_SURFACE",
+        endpoint: "POST /fiat/orders/:id/surface-result",
+        when: "the order already exists (order-then-capture topology)",
+        note: 'Endpoint per contract \xA7Endpoints ("client reports CLIENT_SURFACE outcome; backend reconciles vs webhooks").'
+      }
+    ],
+    mayReturn: ["ORDER/CREATED", "PAYMENT/CAPTURE", "QUOTE"],
+    terminal: false,
+    notes: [
+      "Decline re-entry: same state, fresh surface.session, error {category: PAYMENT_DECLINED, retryable: true, recovery: RETRY_PAYMENT}.",
+      "The Surface is carried in state, never in the transition (\u03942, single-carry)."
+    ]
+  },
+  "PAYMENT/INSTRUCT": {
+    key: "PAYMENT/INSTRUCT",
+    kind: "PAYMENT",
+    phase: "INSTRUCT",
+    screens: [6],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [
+      {
+        id: "confirm_paid",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/orders/:id/confirm-payment"
+      },
+      {
+        id: "cancel",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/orders/:id/cancel",
+        when: "in-wizard cancel placement wins",
+        note: "TODO(open-decision): cancel placement \u2014 in-wizard vs an out-of-wizard pending-orders surface (FE doc open questions 1+2). Per-rail cancel eligibility is contract OQ7."
+      }
+    ],
+    mayReturn: ["ORDER/CREATED"],
+    terminal: false,
+    notes: [
+      "No instructions re-issue endpoint exists; expired-instructions recovery is unenumerated. TODO(open-decision): contract OQ7.",
+      "Async instructions (PREPARING) are deliberately not in v1 \u2014 Transak returns bank details synchronously."
+    ]
+  },
+  "ORDER/AWAITING_CONFIRMATION": {
+    key: "ORDER/AWAITING_CONFIRMATION",
+    kind: "ORDER",
+    phase: "AWAITING_CONFIRMATION",
+    screens: [4],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [{ id: "confirm", mode: "SUBMIT", endpoint: "POST /fiat/orders" }],
+    mayReturn: [
+      "PAYMENT/CAPTURE",
+      "PAYMENT/INSTRUCT",
+      "ORDER/CREATED",
+      "QUOTE",
+      "PENDING_ORDER"
+    ],
+    terminal: false,
+    notes: [
+      "Bank rails only \u2014 card rails skip it, the pay sheet was the confirmation.",
+      "Carries a refreshed quote: the price may have drifted during KYC."
+    ]
+  },
+  "ORDER/CREATED": {
+    key: "ORDER/CREATED",
+    kind: "ORDER",
+    phase: "CREATED",
+    screens: [7, 13, 14, 15],
+    docStatus: "SPECIFIED",
+    allowedTransitions: [
+      {
+        id: "poll",
+        mode: "AWAIT",
+        endpoint: "GET /fiat/orders/:id",
+        when: "status is non-terminal",
+        note: "Documented giveUpAfterMs 300000 \u2014 on give-up the wizard exits and the durable order takes over."
+      },
+      {
+        id: "retry_payment",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/orders",
+        when: "failureReason.recovery === RETRY_PAYMENT"
+      },
+      {
+        id: "requote",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/quote",
+        when: "failureReason.recovery === REQUOTE"
+      },
+      {
+        id: "cancel",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/orders/:id/cancel",
+        when: "in-wizard cancel placement wins and the rail allows it",
+        note: "TODO(open-decision): cancel placement (FE doc open questions 1+2); per-rail eligibility is contract OQ7."
+      }
+    ],
+    mayReturn: ["ORDER/CREATED"],
+    terminal: false,
+    terminalStatuses: TERMINAL_ORDER_STATUSES,
+    notes: [
+      "Flow-terminality here rides status \u2208 terminalStatuses, not the state kind and not array emptiness.",
+      "A terminal status may still carry a recovery transition: FAILED + retryable failureReason emits it (FE doc Screen 14); non-retryable emits [].",
+      "ON_HOLD is a non-terminal status (resolves to PROCESSING or REFUNDED) \u2014 and is NOT the same thing as the KYC ON_HOLD reason; see the note on that field.",
+      "CAPTURE_ORPHANED is non-terminal pending the backend rank map (added from review 2026-08-14).",
+      "TODO(open-decision): contract OQ7 \u2014 under/over-payment is the biggest unenumerated branch."
+    ]
+  }
+};
+var STATE_KEYS = Object.keys(TRANSITION_TABLE);
+var DOCUMENTED_ENDPOINTS = [
+  "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"
+];
+function stateKey(state) {
+  switch (state.kind) {
+    case "QUOTE":
+      return "QUOTE";
+    case "FUN_AUTH":
+      return "FUN_AUTH";
+    case "SESSION_AUTH":
+      return "SESSION_AUTH";
+    case "PENDING_ORDER":
+      return "PENDING_ORDER";
+    case "BLOCKED":
+      return "BLOCKED";
+    case "KYC": {
+      if (state.phase === "CAPTURE") return "KYC/CAPTURE";
+      if (state.phase === "INPUT_REQUIRED") return "KYC/INPUT_REQUIRED";
+      return `KYC/NO_ACTION_REQUIRED:${state.reason}`;
+    }
+    case "PAYMENT":
+      return state.phase === "CAPTURE" ? "PAYMENT/CAPTURE" : "PAYMENT/INSTRUCT";
+    case "ORDER":
+      return state.phase === "AWAITING_CONFIRMATION" ? "ORDER/AWAITING_CONFIRMATION" : "ORDER/CREATED";
+    default: {
+      const exhaustive = state;
+      throw new Error(`unknown FlowState: ${JSON.stringify(exhaustive)}`);
+    }
+  }
+}
+var tableEntry = (state) => TRANSITION_TABLE[stateKey(state)];
+function isTerminal(state) {
+  const entry = tableEntry(state);
+  if (entry.terminalStatuses && state.kind === "ORDER" && state.phase === "CREATED") {
+    return entry.terminalStatuses.includes(state.status);
+  }
+  return entry.terminal;
+}
+
+// src/fixtures/data.ts
+var FIXTURE_DATA = {
+  "screen-01-quote": {
+    "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"
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "continue",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/session",
+        "params": {
+          "quoteRef": "q_8f2"
+        }
+      }
+    ]
+  },
+  "screen-02-session-auth": {
+    "state": {
+      "kind": "SESSION_AUTH",
+      "channel": "EMAIL_OTP"
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "verify",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/session/verify",
+        "params": {
+          "quoteRef": "q_8f2"
+        },
+        "inputs": {
+          "code": {
+            "type": "TEXT",
+            "length": 6
+          }
+        }
+      }
+    ]
+  },
+  "screen-03-kyc-input-required": {
+    "state": {
+      "kind": "KYC",
+      "phase": "INPUT_REQUIRED",
+      "form": {
+        "formId": "personal_details",
+        "fields": [
+          {
+            "id": "firstName",
+            "type": "TEXT",
+            "labelFallback": "First name",
+            "required": true
+          },
+          {
+            "id": "dob",
+            "type": "DATE",
+            "labelFallback": "Date of birth",
+            "required": true
+          },
+          {
+            "id": "country",
+            "type": "COUNTRY",
+            "labelFallback": "Country",
+            "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"
+          }
+        ]
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "submit_round",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/kyc/form",
+        "params": {
+          "formId": "personal_details"
+        },
+        "inputs": {
+          "values": {
+            "type": "FORM_VALUES"
+          }
+        }
+      }
+    ]
+  },
+  "screen-04-order-review": {
+    "state": {
+      "kind": "ORDER",
+      "phase": "AWAITING_CONFIRMATION",
+      "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"
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "confirm",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/orders",
+        "params": {
+          "quoteRef": "q_8f2"
+        }
+      }
+    ]
+  },
+  "screen-05-payment-capture": {
+    "state": {
+      "kind": "PAYMENT",
+      "phase": "CAPTURE",
+      "surface": {
+        "kind": "PCI_COMPONENT",
+        "session": "eyJ\u2026"
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "capture",
+        "mode": "CLIENT_SURFACE",
+        "report": {
+          "endpoint": "POST /fiat/orders",
+          "params": {
+            "quoteRef": "q_8f2"
+          },
+          "expects": [
+            "requestId"
+          ]
+        }
+      }
+    ]
+  },
+  "screen-09-kyc-in-review": {
+    "state": {
+      "kind": "KYC",
+      "phase": "NO_ACTION_REQUIRED",
+      "reason": "IN_REVIEW"
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "poll",
+        "mode": "AWAIT",
+        "poll": {
+          "endpoint": "GET /fiat/kyc",
+          "params": {
+            "quoteRef": "q_8f2"
+          },
+          "intervalMs": 3e3,
+          "backoffFactor": 1.5,
+          "maxIntervalMs": 1e4,
+          "giveUpAfterMs": 9e4
+        }
+      }
+    ]
+  },
+  "screen-10-kyc-on-hold": {
+    "state": {
+      "kind": "KYC",
+      "phase": "NO_ACTION_REQUIRED",
+      "reason": "ON_HOLD",
+      "retryAfter": "2026-08-20T09:00:00Z"
+    },
+    "provider": "TRANSAK",
+    "transitions": []
+  },
+  "screen-11-kyc-rejected-escalation": {
+    "state": {
+      "kind": "KYC",
+      "phase": "NO_ACTION_REQUIRED",
+      "reason": "REJECTED"
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "escalate",
+        "mode": "SUBMIT",
+        "endpoint": "GET /fiat/kyc",
+        "params": {
+          "tier": "escalated"
+        }
+      }
+    ]
+  },
+  "screen-12-pending-order": {
+    "state": {
+      "kind": "PENDING_ORDER",
+      "order": {
+        "orderId": "o_31c",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "method": "bank_transfer",
+        "createdAt": "\u2026",
+        "status": "AWAITING_PAYMENT"
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "resume",
+        "mode": "SUBMIT",
+        "endpoint": "GET /fiat/orders/o_31c"
+      },
+      {
+        "id": "cancel",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/orders/o_31c/cancel"
+      }
+    ]
+  },
+  "screen-13-order-settled": {
+    "state": {
+      "kind": "ORDER",
+      "phase": "CREATED",
+      "order": {
+        "orderId": "o_31c",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "crypto": {
+          "currency": "USDC",
+          "network": "polygon",
+          "amount": "98.41"
+        },
+        "method": "card",
+        "instrument": {
+          "brandLabel": "Chase Debit",
+          "last4": "4021"
+        },
+        "createdAt": "\u2026"
+      },
+      "status": "SETTLED",
+      "tx": {
+        "chainId": 137,
+        "hash": "0x\u2026"
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": []
+  },
+  "screen-14-order-failed": {
+    "state": {
+      "kind": "ORDER",
+      "phase": "CREATED",
+      "order": {
+        "orderId": "o_31c",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "method": "card",
+        "createdAt": "\u2026"
+      },
+      "status": "FAILED",
+      "failureReason": {
+        "category": "PAYMENT_DECLINED",
+        "retryable": true,
+        "recovery": "RETRY_PAYMENT"
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": [
+      {
+        "id": "retry_payment",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/orders",
+        "params": {
+          "quoteRef": "q_8f2"
+        }
+      }
+    ]
+  },
+  "screen-15-order-refunded": {
+    "state": {
+      "kind": "ORDER",
+      "phase": "CREATED",
+      "order": {
+        "orderId": "o_31c",
+        "fiat": {
+          "currency": "GBP",
+          "amount": "100.00"
+        },
+        "method": "bank_transfer",
+        "createdAt": "\u2026"
+      },
+      "status": "REFUNDED",
+      "refund": {
+        "currency": "GBP",
+        "amount": "100.00",
+        "expectedBy": "\u2026"
+      }
+    },
+    "provider": "TRANSAK",
+    "transitions": []
+  },
+  "screen-16-blocked": {
+    "state": {
+      "kind": "BLOCKED",
+      "reason": "REGION_UNSUPPORTED",
+      "retryAfter": null
+    },
+    "provider": "TRANSAK",
+    "transitions": []
+  },
+  "worked-example-01-quote": {
+    "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": "2026-08-11T21:33:00Z"
+      }
+    },
+    "transitions": [
+      {
+        "id": "continue",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/session",
+        "params": {
+          "quoteRef": "q_8f2"
+        },
+        "inputs": {
+          "email": {
+            "type": "TEXT"
+          }
+        }
+      }
+    ]
+  },
+  "worked-example-02-session-auth": {
+    "state": {
+      "kind": "SESSION_AUTH",
+      "channel": "EMAIL_OTP"
+    },
+    "transitions": [
+      {
+        "id": "verify",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/session/verify",
+        "params": {
+          "quoteRef": "q_8f2"
+        },
+        "inputs": {
+          "code": {
+            "type": "TEXT",
+            "length": 6
+          }
+        }
+      }
+    ]
+  },
+  "worked-example-04-payment-instruct": {
+    "orderId": "o_3d1",
+    "state": {
+      "kind": "PAYMENT",
+      "phase": "INSTRUCT",
+      "instructions": {
+        "kind": "BANK_FIELDS",
+        "fields": [
+          {
+            "id": "beneficiary",
+            "labelFallback": "Beneficiary",
+            "value": "Transak"
+          },
+          {
+            "id": "sort_code",
+            "labelFallback": "Sort code",
+            "value": "04-00-04"
+          },
+          {
+            "id": "account_number",
+            "labelFallback": "Account number",
+            "value": "12345678"
+          },
+          {
+            "id": "reference",
+            "labelFallback": "Reference",
+            "value": "o_3d1"
+          }
+        ],
+        "expiresAt": "\u2026"
+      }
+    },
+    "transitions": [
+      {
+        "id": "confirm_paid",
+        "mode": "SUBMIT",
+        "endpoint": "POST /fiat/orders/o_3d1/confirm-payment"
+      }
+    ]
+  }
+};
+
+// src/fixtures/index.ts
+var FIXTURES = [
+  {
+    id: "screen-01-quote",
+    file: "screen-01-quote.json",
+    source: "FE_DOC",
+    docRef: "Screen 1 \xB7 Quote / review",
+    screen: 1,
+    stateKey: "QUOTE",
+    complete: true
+  },
+  {
+    id: "screen-02-session-auth",
+    file: "screen-02-session-auth.json",
+    source: "FE_DOC",
+    docRef: "Screen 2 \xB7 Verification code (OTP)",
+    screen: 2,
+    stateKey: "SESSION_AUTH",
+    complete: true
+  },
+  {
+    id: "screen-03-kyc-input-required",
+    file: "screen-03-kyc-input-required.json",
+    source: "FE_DOC",
+    docRef: "Screen 3 \xB7 Identity form (KYC)",
+    screen: 3,
+    stateKey: "KYC/INPUT_REQUIRED",
+    complete: true,
+    notes: ["Carries the FORM_VALUES input spec \u2014 the no-double-carry case of the accepted split."]
+  },
+  {
+    id: "screen-04-order-review",
+    file: "screen-04-order-review.json",
+    source: "FE_DOC",
+    docRef: "Screen 4 \xB7 Order review (bank rail)",
+    screen: 4,
+    stateKey: "ORDER/AWAITING_CONFIRMATION",
+    complete: true,
+    notes: [
+      `The screen card publishes this payload by reference \u2014 "quote: <same shape as Screen 1, refreshed>" \u2014 so the quote here is Screen 1's payload verbatim. The numbers are not re-published as refreshed values, so they are unchanged; only the shape is contractual.`
+    ]
+  },
+  {
+    id: "screen-05-payment-capture",
+    file: "screen-05-payment-capture.json",
+    source: "FE_DOC",
+    docRef: "Screen 5 \xB7 Card payment",
+    screen: 5,
+    stateKey: "PAYMENT/CAPTURE",
+    complete: true,
+    notes: [
+      "Capture-then-order topology (report \u2192 POST /fiat/orders, expects requestId).",
+      "TODO(open-decision): report target per card topology is a Transak ask (contract Flow A)."
+    ]
+  },
+  {
+    id: "screen-09-kyc-in-review",
+    file: "screen-09-kyc-in-review.json",
+    source: "FE_DOC",
+    docRef: "Screen 9 \xB7 Verifying identity",
+    screen: 9,
+    stateKey: "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
+    complete: true
+  },
+  {
+    id: "screen-10-kyc-on-hold",
+    file: "screen-10-kyc-on-hold.json",
+    source: "FE_DOC",
+    docRef: "Screen 10 \xB7 Verification on hold",
+    screen: 10,
+    stateKey: "KYC/NO_ACTION_REQUIRED:ON_HOLD",
+    complete: true,
+    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",
+    screen: 11,
+    stateKey: "KYC/NO_ACTION_REQUIRED:REJECTED",
+    complete: true,
+    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."
+    ]
+  },
+  {
+    id: "screen-12-pending-order",
+    file: "screen-12-pending-order.json",
+    source: "FE_DOC",
+    docRef: "Screen 12 \xB7 Order in progress",
+    screen: 12,
+    stateKey: "PENDING_ORDER",
+    complete: true,
+    notes: [
+      "TODO(open-decision): PENDING_ORDER removal proposed; Screen 12 frozen. Kept so 0.1.0 can validate the current shape."
+    ]
+  },
+  {
+    id: "screen-13-order-settled",
+    file: "screen-13-order-settled.json",
+    source: "FE_DOC",
+    docRef: "Screen 13 \xB7 Success",
+    screen: 13,
+    stateKey: "ORDER/CREATED",
+    complete: true
+  },
+  {
+    id: "screen-14-order-failed",
+    file: "screen-14-order-failed.json",
+    source: "FE_DOC",
+    docRef: "Screen 14 \xB7 Something went wrong",
+    screen: 14,
+    stateKey: "ORDER/CREATED",
+    complete: true,
+    notes: ["Terminal status (FAILED) still carrying a recovery transition \u2014 retryable failureReason."]
+  },
+  {
+    id: "screen-15-order-refunded",
+    file: "screen-15-order-refunded.json",
+    source: "FE_DOC",
+    docRef: "Screen 15 \xB7 Refund on the way",
+    screen: 15,
+    stateKey: "ORDER/CREATED",
+    complete: true
+  },
+  {
+    id: "screen-16-blocked",
+    file: "screen-16-blocked.json",
+    source: "FE_DOC",
+    docRef: "Screen 16 \xB7 Not available",
+    screen: 16,
+    stateKey: "BLOCKED",
+    complete: true,
+    notes: ["The only flatly terminal state entry in the table."]
+  },
+  {
+    id: "worked-example-01-quote",
+    file: "worked-example-01-quote.json",
+    source: "CONTRACT_DOC",
+    docRef: "\xA7Worked example, step 1 (method selection)",
+    stateKey: "QUOTE",
+    complete: false,
+    notes: ["Carries inputs {email: {type: TEXT}} \u2014 the collected-spec half of the split."]
+  },
+  {
+    id: "worked-example-02-session-auth",
+    file: "worked-example-02-session-auth.json",
+    source: "CONTRACT_DOC",
+    docRef: "\xA7Worked example, step 2 (session challenge)",
+    stateKey: "SESSION_AUTH",
+    complete: false
+  },
+  {
+    id: "worked-example-04-payment-instruct",
+    file: "worked-example-04-payment-instruct.json",
+    source: "CONTRACT_DOC",
+    docRef: "\xA7Worked example, steps 4\u20135 (order + bank instructions)",
+    stateKey: "PAYMENT/INSTRUCT",
+    complete: false,
+    notes: [
+      "The envelope-sibling `orderId` case. TODO(open-decision): orderId placement (envelope sibling here vs inside state 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."
+  },
+  {
+    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."
+  }
+];
+var fixtureMeta = (id) => {
+  const meta = FIXTURES.find((f) => f.id === id);
+  if (!meta) throw new Error(`unknown fixture: ${id}`);
+  return meta;
+};
+function loadFixture(id) {
+  const meta = fixtureMeta(id);
+  const data = FIXTURE_DATA[meta.id];
+  if (data === void 0) throw new Error(`fixture data missing for ${meta.id} \u2014 run npm run generate:fixtures`);
+  return JSON.parse(JSON.stringify(data));
+}
+function loadFixtures() {
+  return FIXTURES.map((meta) => ({ meta, json: loadFixture(meta.id) }));
+}
+
+// src/assert.ts
+var ContractViolation = class extends Error {
+  issues;
+  constructor(message, issues = []) {
+    super(issues.length ? `${message}
+  - ${issues.join("\n  - ")}` : message);
+    this.name = "ContractViolation";
+    this.issues = issues;
+  }
+};
+var formatIssues = (error) => {
+  const issues = error.issues;
+  if (!issues) return [String(error)];
+  return issues.map((issue) => {
+    const path = (issue.path ?? []).join(".");
+    return path ? `${path}: ${issue.message ?? "invalid"}` : issue.message ?? "invalid";
+  });
+};
+function assertEnvelope(json) {
+  const result = StepResponseSchema.safeParse(json);
+  if (!result.success) throw new ContractViolation("invalid envelope", formatIssues(result.error));
+  return result.data;
+}
+function assertEnvelopeFragment(json) {
+  const result = StepResponseFragmentSchema.safeParse(json);
+  if (!result.success)
+    throw new ContractViolation("invalid envelope fragment", formatIssues(result.error));
+  return result.data;
+}
+function endpointMatches(template, actual) {
+  const pattern = template.split("/").map((segment) => segment.startsWith(":") ? "[^/]+" : escapeRegExp(segment)).join("/");
+  return new RegExp(`^${pattern}$`).test(actual);
+}
+var escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+var transitionEndpoint = (transition) => {
+  switch (transition.mode) {
+    case "SUBMIT":
+      return transition.endpoint;
+    case "AWAIT":
+      return transition.poll.endpoint;
+    case "CLIENT_SURFACE":
+      return transition.report.endpoint;
+  }
+};
+var matchesAllowed = (transition, allowed) => allowed.mode === transition.mode && endpointMatches(allowed.endpoint, transitionEndpoint(transition));
+function bodyKeyIssues(transition) {
+  const issues = [];
+  const collide = (a, b, left, right) => {
+    for (const key of a) {
+      if (b.includes(key)) issues.push(`transition "${transition.id}": key "${key}" is in both ${left} and ${right}`);
+    }
+  };
+  if (transition.mode === "SUBMIT") {
+    const params = Object.keys(transition.params ?? {});
+    const inputs = Object.keys(transition.inputs ?? {});
+    collide(params, inputs, "params", "inputs");
+    for (const [key, value] of Object.entries(transition.params ?? {})) {
+      if (looksLikeFieldSpec(value)) {
+        issues.push(
+          `transition "${transition.id}": params.${key} is FieldSpec-shaped \u2014 a spec the client must collect belongs in inputs`
+        );
+      }
+    }
+  }
+  if (transition.mode === "CLIENT_SURFACE") {
+    const params = Object.keys(transition.report.params ?? {});
+    collide(params, transition.report.expects ?? [], "report.params", "report.expects");
+  }
+  return issues;
+}
+function checkLegalEmission(state, transitions) {
+  const entry = tableEntry(state);
+  const issues = [];
+  if (entry.terminal && transitions.length > 0) {
+    issues.push(
+      `${entry.key} is terminal (table) and must carry transitions: [] \u2014 got ${transitions.length}`
+    );
+  }
+  for (const transition of transitions) {
+    issues.push(...bodyKeyIssues(transition));
+    if (transition.mode === "CLIENT_SURFACE" && !("surface" in state)) {
+      issues.push(
+        `transition "${transition.id}": CLIENT_SURFACE requires the Surface in state (\u03942 single-carry) \u2014 ${entry.key} carries none`
+      );
+    }
+    if (transition.mode === "SUBMIT" && Object.values(transition.inputs ?? {}).some((spec) => spec.type === "FORM_VALUES") && !("form" in state)) {
+      issues.push(
+        `transition "${transition.id}": inputs {type: FORM_VALUES} collects state.form \u2014 ${entry.key} carries no form`
+      );
+    }
+    if (entry.docStatus === "SPECIFIED" && !entry.allowedTransitions.some((a) => matchesAllowed(transition, a))) {
+      issues.push(
+        `transition "${transition.id}": ${transition.mode} ${transitionEndpoint(transition)} is not in ${entry.key}'s legal set (${entry.allowedTransitions.map((a) => `${a.mode} ${a.endpoint}`).join(" | ") || "none"})`
+      );
+    }
+  }
+  return {
+    state: entry.key,
+    issues,
+    unjudgeable: entry.docStatus === "UNSPECIFIED"
+  };
+}
+function assertLegalEmission(state, transitions) {
+  const { issues, state: key } = checkLegalEmission(state, transitions);
+  if (issues.length) throw new ContractViolation(`illegal emission for ${key}`, issues);
+}
+function assertLegalReturn(from, to) {
+  const entry = tableEntry(from);
+  const target = stateKey(to);
+  if (!entry.mayReturn) return;
+  if (!entry.mayReturn.includes(target)) {
+    throw new ContractViolation(
+      `illegal return: ${entry.key} \u2192 ${target}`,
+      [`${entry.key} may receive back: ${entry.mayReturn.join(" \xB7 ") || "nothing (terminal)"}`]
+    );
+  }
+}
+function walkTable(fn) {
+  return STATE_KEYS.map((key) => fn(TRANSITION_TABLE[key], key));
+}
+function assertFixture(id) {
+  const meta = fixtureMeta(id);
+  const json = loadFixture(id);
+  const envelope = meta.complete ? assertEnvelope(json) : assertEnvelopeFragment(json);
+  if (stateKey(envelope.state) !== meta.stateKey) {
+    throw new ContractViolation(
+      `fixture ${id}: manifest says ${meta.stateKey}, envelope carries ${stateKey(envelope.state)}`
+    );
+  }
+  assertLegalEmission(envelope.state, envelope.transitions);
+  return { meta, envelope };
+}
+function assertAllFixtures() {
+  return FIXTURES.map((meta) => assertFixture(meta.id));
+}
+//# sourceMappingURL=index.js.map