@fun-xyz/fiat-contract 0.3.0 → 0.5.0

package/README.md

@@ -7,10 +7,10 @@ Four things, zero runtime logic beyond validation:
 
 | File | What it is |
 | --- | --- |
-| `src/types.ts` | `FlowState` · `Transition` · `FailureReason` · `Surface` · `Instructions` · `FormDescriptor` · `OrderStatus` · `StepResponse` |
+| `src/types.ts` | `FlowState` · `Transition` · `FailureReason` · `Surface` · `Instructions` · `FormDescriptor` · `OrderStatus` · `FiatStepResponse` |
 | `src/schemas.ts` | zod mirrors of every type — the single runtime validator |
 | `src/table.ts` | the transition table **as data**: per state, its legal transition set, the states any call from it may return, and `terminal: boolean` |
-| `src/assert.ts` + `src/fixtures/` | `assertEnvelope` · `assertLegalEmission` · `assertLegalReturn` · `walkTable` · fixture loader + 16 recorded envelopes (inlined as data — no filesystem, so React Native can bundle it) |
+| `src/assert.ts` + `src/fixtures/` | `assertFiatStepResponse` · `assertLegalEmission` · `assertLegalReturn` · `walkTable` · fixture loader + 16 recorded envelopes (inlined as data — no filesystem, so React Native can bundle it) |
 
 ## Three entry points — production vs test-time
 
@@ -55,23 +55,26 @@ this package is [ENG-5268](https://linear.app/funxyz/issue/ENG-5268).
 
 ## Versioning — the package version IS the table version
 
-`TABLE_VERSION` (exported from `src/table.ts`) must equal `package.json#version`; a test asserts it.
+`TABLE_VERSION` (exported from `src/table.ts`) is derived from `package.json#version` at build
+time — a version bump is one edit, in package.json, and the two can never drift. A test asserts
+the wiring still resolves to the package version.
 That version rides the capability handshake (`supportedProviders` / `supportedSurfaces` /
 `supportedStepKinds` + table version), which is how BE↔FE skew stays explicit and designed-for:
 the server never routes a flow into a state kind the installed SDK didn't declare.
 
 Starting at **0.1.0**. Bump the minor for additive vocabulary (a new field, a new fixture); bump the
-major when an existing shape changes meaning.
+major when an existing shape changes meaning. Until 1.0 the contract is MVP-beta: renames and
+removals also ride a minor, with no deprecated aliases kept — consumers pin and migrate in one step.
 
 ## How each repo consumes it
 
 **`fun-backend`** — adapters compile their provider's real flow into this state machine.
 
 ```ts
-import { assertEnvelope, assertLegalEmission, walkTable } from '@fun-xyz/fiat-contract';
+import { assertFiatStepResponse, assertLegalEmission, walkTable } from '@fun-xyz/fiat-contract';
 
-assertLegalEmission(state, transitions);              // per emission: adapter conformance
-assertEnvelope(outgoing);                             // outgoing-envelope validation in dev/test
+assertLegalEmission(state, transitions);                     // per emission: adapter conformance
+assertFiatStepResponse(outgoing);                            // outgoing-envelope validation in dev/test
 const owed = walkTable((entry) => entry.allowedTransitions); // what the adapter must emit
 ```
 
@@ -102,9 +105,9 @@ The backend *builds* envelopes, so its production use is entirely compile-time
 verification. Runtime assertions stay behind a dev/test guard.
 
 ```ts
-import type { FlowState, StepResponse, Transition } from '@fun-xyz/fiat-contract/types';
+import type { FlowState, FiatStepResponse, Transition } from '@fun-xyz/fiat-contract/types';
 
-export async function createOrder(quoteRef: string): Promise<StepResponse> {
+export async function createOrder(quoteRef: string): Promise<FiatStepResponse> {
   const state: FlowState = {
     kind: 'PAYMENT',
     phase: 'INSTRUCT',
@@ -137,9 +140,9 @@ production-safe: types erase, `./table` is 13.8 KB with no zod.
 
 ```ts
 import { isTerminal, stateKey } from '@fun-xyz/fiat-contract/table';
-import type { StepResponse } from '@fun-xyz/fiat-contract/types';
+import type { FiatStepResponse } from '@fun-xyz/fiat-contract/types';
 
-export function FiatScreen({ env }: { env: StepResponse }) {
+export function FiatScreen({ env }: { env: FiatStepResponse }) {
   const page = computePage(stateKey(env.state), clientLocal); // client owns state → screen
   const done = isTerminal(env.state);                          // table data, never inferred
 
@@ -160,9 +163,9 @@ re-derive that rule locally.
 ### Production: the transitions loop
 
 ```ts
-import type { StepResponse, Transition } from '@fun-xyz/fiat-contract/types';
+import type { FiatStepResponse, Transition } from '@fun-xyz/fiat-contract/types';
 
-function useTransitions(env: StepResponse) {
+function useTransitions(env: FiatStepResponse) {
   return {
     ctas: env.transitions.filter((t) => t.mode === 'SUBMIT'),          // render buttons
     poll: env.transitions.find((t) => t.mode === 'AWAIT'),             // harness schedules
@@ -190,15 +193,16 @@ These import from the root, which carries zod. Test-time only.
 
 ### Validate an envelope at the boundary
 
-`assertEnvelope` parses and returns a typed envelope, or throws `ContractViolation` listing every
-problem. Use it on the way out of `fun-backend` (dev/test) and on the way in to `connect-core` tests.
+`assertFiatStepResponse` parses and returns a typed step response, or throws `ContractViolation`
+listing every problem. Use it on the way out of `fun-backend` (dev/test) and on the way in to
+`connect-core` tests.
 
 ```ts
-import { assertEnvelope, ContractViolation } from '@fun-xyz/fiat-contract';
+import { assertFiatStepResponse, ContractViolation } from '@fun-xyz/fiat-contract';
 
 try {
-  const envelope = assertEnvelope(await res.json());
-  //    ^? StepResponse — state is a narrowable discriminated union from here on
+  const envelope = assertFiatStepResponse(await res.json());
+  //    ^? FiatStepResponse — state is a narrowable discriminated union from here on
   if (envelope.state.kind === 'PAYMENT' && envelope.state.phase === 'INSTRUCT') {
     render(envelope.state.instructions); // narrowed: instructions exists, quote does not
   }
@@ -313,9 +317,9 @@ pnpm add -D @fun-xyz/fiat-contract
 ```
 
 ```ts
-import type { StepResponse } from '@fun-xyz/fiat-contract/types'; // production, 0 KB
-import { isTerminal } from '@fun-xyz/fiat-contract/table';         // production, 13.8 KB, no zod
-import { assertEnvelope } from '@fun-xyz/fiat-contract';           // tests only, pulls zod
+import type { FiatStepResponse } from '@fun-xyz/fiat-contract/types'; // production, 0 KB
+import { isTerminal } from '@fun-xyz/fiat-contract/table';            // production, 13.8 KB, no zod
+import { assertFiatStepResponse } from '@fun-xyz/fiat-contract';      // tests only, pulls zod
 ```
 
 Public npm — no `.npmrc`, no token, no registry config. Releases fire from a `v*` tag

package/dist/assert.d.ts

@@ -10,19 +10,14 @@
  */
 import { type EndpointTemplate, type StateKey, type TableEntry } from './table';
 import { type FixtureMeta } from './fixtures/index';
-import type { FlowState, StepResponse, Transition } from './types';
+import type { FiatStepResponse, FlowState, Transition } from './types';
 /** Thrown for anything the contract calls a violation — 4xx-class, never a user-facing state. */
 export declare class ContractViolation extends Error {
     readonly issues: readonly string[];
     constructor(message: string, issues?: readonly string[]);
 }
-/** Validate a `/fiat/*` response envelope. Returns the parsed envelope; throws on violation. */
-export declare function assertEnvelope(json: unknown): StepResponse;
-/**
- * Validate an envelope whose `provider` is absent — only doc excerpts look like this
- * (see `src/fixtures`: fixtures marked `complete: false`). Never valid on the wire.
- */
-export declare function assertEnvelopeFragment(json: unknown): Omit<StepResponse, 'provider'>;
+/** Validate a `/fiat/*` step response. Returns the parsed response; throws on violation. */
+export declare function assertFiatStepResponse(json: unknown): FiatStepResponse;
 /** `"POST /fiat/orders/:id/cancel"` matches `"POST /fiat/orders/o_31c/cancel"`. */
 export declare function endpointMatches(template: EndpointTemplate, actual: string): boolean;
 export interface EmissionCheck {
@@ -54,10 +49,7 @@ export declare function assertLegalReturn(from: FlowState, to: FlowState): void;
 export declare function walkTable<T>(fn: (entry: TableEntry, key: StateKey) => T): T[];
 export interface ValidatedFixture {
     meta: FixtureMeta;
-    /** `provider` is absent on fragment fixtures (`meta.complete === false`). */
-    envelope: Omit<StepResponse, 'provider'> & {
-        provider?: StepResponse['provider'];
-    };
+    envelope: FiatStepResponse;
 }
 /** Load one fixture, validate its shape, and assert its emission is legal for its state. */
 export declare function assertFixture(id: string): ValidatedFixture;

package/dist/{chunk-UWR2DRHB.mjs → chunk-3R5GGUAK.mjs}

@@ -1,5 +1,8 @@
+// package.json
+var version = "0.5.0";
+
 // src/table.ts
-var TABLE_VERSION = "0.3.0";
+var TABLE_VERSION = version;
 var TERMINAL_ORDER_STATUSES = [
   "SETTLED",
   "EXPIRED",
@@ -409,4 +412,4 @@ export {
   tableEntry,
   isTerminal
 };
-//# sourceMappingURL=chunk-UWR2DRHB.mjs.map
+//# sourceMappingURL=chunk-3R5GGUAK.mjs.map

package/dist/fixtures/index.d.ts

@@ -9,10 +9,10 @@
  * already synthetic (`q_8f2`, `o_31c`, `eyJ…`, `"…"` placeholders); the redaction rule applies to
  * fixtures too, so never replace a fake session token, bank field, or PII value with a real one.
  *
- * Two fixture shapes exist:
- *  - `complete: true`  — a full envelope (`state` + `provider` + `transitions`) ⇒ `assertEnvelope`
- *  - `complete: false` — a doc excerpt that omits `provider` ⇒ `assertEnvelopeFragment`
- *    (`provider` is always present on the wire; the contract doc's worked example just elides it)
+ * Every fixture is a full envelope (`state` + `provider` + `transitions`). The contract doc's worked
+ * example elides `provider` in its prose; the three `worked-example-*` fixtures add
+ * `"provider": "TRANSAK"` so they validate as real responses — `provider` is always present on the
+ * wire, and the contract has no half-envelope shape.
  */
 import type { StateKey } from '../table';
 export type FixtureSource = 'FE_DOC' | 'CONTRACT_DOC';
@@ -25,8 +25,6 @@ export interface FixtureMeta {
     /** FE doc screen number, when the fixture comes from a screen card. */
     screen?: number;
     stateKey: StateKey;
-    /** `false` ⇒ the doc excerpt omits `provider`; validate as a fragment. */
-    complete: boolean;
     notes?: readonly string[];
 }
 export declare const FIXTURES: readonly FixtureMeta[];

package/dist/index.js

@@ -29,7 +29,6 @@ __export(index_exports, {
   CryptoAmountSchema: () => CryptoAmountSchema,
   DOCUMENTED_ENDPOINTS: () => DOCUMENTED_ENDPOINTS,
   ENDPOINT_PATTERN: () => ENDPOINT_PATTERN,
-  EnvelopeSchema: () => EnvelopeSchema,
   FIAT_CURRENCY_NAMES: () => FIAT_CURRENCY_NAMES,
   FIELD_SPEC_TYPES: () => FIELD_SPEC_TYPES,
   FIXTURES: () => FIXTURES,
@@ -40,6 +39,7 @@ __export(index_exports, {
   FiatCurrencyCode: () => FiatCurrencyCode,
   FiatEndpointSchema: () => FiatEndpointSchema,
   FiatProviderSchema: () => FiatProviderSchema,
+  FiatStepResponseSchema: () => FiatStepResponseSchema,
   FieldSpecSchema: () => FieldSpecSchema,
   FlowStateSchema: () => FlowStateSchema,
   FormDescriptorSchema: () => FormDescriptorSchema,
@@ -73,8 +73,6 @@ __export(index_exports, {
   SelectOptionSchema: () => SelectOptionSchema,
   SessionAuthStateSchema: () => SessionAuthStateSchema,
   StatusHistoryEntrySchema: () => StatusHistoryEntrySchema,
-  StepResponseFragmentSchema: () => StepResponseFragmentSchema,
-  StepResponseSchema: () => StepResponseSchema,
   SurfaceSchema: () => SurfaceSchema,
   TABLE_VERSION: () => TABLE_VERSION,
   TERMINAL_ORDER_STATUSES: () => TERMINAL_ORDER_STATUSES,
@@ -84,8 +82,7 @@ __export(index_exports, {
   TransitionSchema: () => TransitionSchema,
   TxSchema: () => TxSchema,
   assertAllFixtures: () => assertAllFixtures,
-  assertEnvelope: () => assertEnvelope,
-  assertEnvelopeFragment: () => assertEnvelopeFragment,
+  assertFiatStepResponse: () => assertFiatStepResponse,
   assertFixture: () => assertFixture,
   assertLegalEmission: () => assertLegalEmission,
   assertLegalReturn: () => assertLegalReturn,
@@ -560,13 +557,32 @@ var $params = import_zod.z.record(import_zod.z.string(), JsonSchema).superRefine
 var TransitionParamsSchema = $params;
 var $inputs = import_zod.z.record(import_zod.z.string(), $fieldSpec);
 var TransitionInputsSchema = $inputs;
+var MAX_DELAY_MS = 2 ** 31 - 1;
+var MIN_INTERVAL_MS = 500;
 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()
+  intervalMs: import_zod.z.number().int().min(MIN_INTERVAL_MS).max(MAX_DELAY_MS),
+  // Not `.int()` — 1.5 is the recorded factor and a legitimate one. `.finite()` is load-bearing:
+  // zod 3's `z.number()` admits Infinity, and `Infinity >= 1` satisfies `.min(1)` on its own.
+  backoffFactor: import_zod.z.number().finite().min(1).optional(),
+  maxIntervalMs: import_zod.z.number().int().min(MIN_INTERVAL_MS).max(MAX_DELAY_MS).optional(),
+  giveUpAfterMs: import_zod.z.number().int().nonnegative().max(MAX_DELAY_MS).optional()
+}).superRefine((spec, ctx) => {
+  if (spec.backoffFactor !== void 0 && spec.maxIntervalMs === void 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["maxIntervalMs"],
+      message: "maxIntervalMs is required when backoffFactor is present \u2014 an unbounded backoff grows the interval past 2^31-1, where setTimeout truncates the delay to 0 and the poll hot-loops."
+    });
+  }
+  if (spec.maxIntervalMs !== void 0 && spec.maxIntervalMs < spec.intervalMs) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["maxIntervalMs"],
+      message: `maxIntervalMs (${spec.maxIntervalMs}) is below intervalMs (${spec.intervalMs}) \u2014 a ceiling under the starting interval caps the poll at less than its own first delay.`
+    });
+  }
 });
 var PollSpecSchema = $pollSpec;
 var $reportSpec = obj({
@@ -699,18 +715,13 @@ var $stepResponse = obj({
   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;
+var FiatStepResponseSchema = $stepResponse;
+
+// package.json
+var version = "0.5.0";
 
 // src/table.ts
-var TABLE_VERSION = "0.3.0";
+var TABLE_VERSION = version;
 var TERMINAL_ORDER_STATUSES = [
   "SETTLED",
   "EXPIRED",
@@ -1526,6 +1537,7 @@ var FIXTURE_DATA = {
         "expiresAt": "2026-08-11T21:33:00Z"
       }
     },
+    "provider": "TRANSAK",
     "transitions": [
       {
         "id": "continue",
@@ -1547,6 +1559,7 @@ var FIXTURE_DATA = {
       "kind": "SESSION_AUTH",
       "channel": "EMAIL_OTP"
     },
+    "provider": "TRANSAK",
     "transitions": [
       {
         "id": "verify",
@@ -1596,6 +1609,7 @@ var FIXTURE_DATA = {
         "expiresAt": "\u2026"
       }
     },
+    "provider": "TRANSAK",
     "transitions": [
       {
         "id": "confirm_paid",
@@ -1614,8 +1628,7 @@ var FIXTURES = [
     source: "FE_DOC",
     docRef: "Screen 1 \xB7 Quote / review",
     screen: 1,
-    stateKey: "QUOTE",
-    complete: true
+    stateKey: "QUOTE"
   },
   {
     id: "screen-02-session-auth",
@@ -1623,8 +1636,7 @@ var FIXTURES = [
     source: "FE_DOC",
     docRef: "Screen 2 \xB7 Verification code (OTP)",
     screen: 2,
-    stateKey: "SESSION_AUTH",
-    complete: true
+    stateKey: "SESSION_AUTH"
   },
   {
     id: "screen-03-kyc-input-required",
@@ -1633,7 +1645,6 @@ var FIXTURES = [
     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."]
   },
   {
@@ -1643,7 +1654,6 @@ var FIXTURES = [
     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.`
     ]
@@ -1655,7 +1665,6 @@ var FIXTURES = [
     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)."
@@ -1667,8 +1676,7 @@ var FIXTURES = [
     source: "FE_DOC",
     docRef: "Screen 9 \xB7 Verifying identity",
     screen: 9,
-    stateKey: "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
-    complete: true
+    stateKey: "KYC/NO_ACTION_REQUIRED:IN_REVIEW"
   },
   {
     id: "screen-10-kyc-on-hold",
@@ -1677,7 +1685,6 @@ var FIXTURES = [
     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."]
   },
   {
@@ -1687,7 +1694,6 @@ var FIXTURES = [
     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."
@@ -1700,7 +1706,6 @@ var FIXTURES = [
     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."
     ]
@@ -1711,8 +1716,7 @@ var FIXTURES = [
     source: "FE_DOC",
     docRef: "Screen 13 \xB7 Success",
     screen: 13,
-    stateKey: "ORDER/CREATED",
-    complete: true
+    stateKey: "ORDER/CREATED"
   },
   {
     id: "screen-14-order-failed",
@@ -1721,7 +1725,6 @@ var FIXTURES = [
     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."]
   },
   {
@@ -1730,8 +1733,7 @@ var FIXTURES = [
     source: "FE_DOC",
     docRef: "Screen 15 \xB7 Refund on the way",
     screen: 15,
-    stateKey: "ORDER/CREATED",
-    complete: true
+    stateKey: "ORDER/CREATED"
   },
   {
     id: "screen-16-blocked",
@@ -1740,7 +1742,6 @@ var FIXTURES = [
     docRef: "Screen 16 \xB7 Not available",
     screen: 16,
     stateKey: "BLOCKED",
-    complete: true,
     notes: ["The only flatly terminal state entry in the table."]
   },
   {
@@ -1749,7 +1750,6 @@ var FIXTURES = [
     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."]
   },
   {
@@ -1757,8 +1757,7 @@ var FIXTURES = [
     file: "worked-example-02-session-auth.json",
     source: "CONTRACT_DOC",
     docRef: "\xA7Worked example, step 2 (session challenge)",
-    stateKey: "SESSION_AUTH",
-    complete: false
+    stateKey: "SESSION_AUTH"
   },
   {
     id: "worked-example-04-payment-instruct",
@@ -1766,7 +1765,6 @@ var FIXTURES = [
     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)."
     ]
@@ -1815,17 +1813,11 @@ var formatIssues = (error) => {
     return path ? `${path}: ${issue.message ?? "invalid"}` : issue.message ?? "invalid";
   });
 };
-function assertEnvelope(json) {
-  const result = StepResponseSchema.safeParse(json);
+function assertFiatStepResponse(json) {
+  const result = FiatStepResponseSchema.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);
@@ -1920,7 +1912,7 @@ function walkTable(fn) {
 function assertFixture(id) {
   const meta = fixtureMeta(id);
   const json = loadFixture(id);
-  const envelope = meta.complete ? assertEnvelope(json) : assertEnvelopeFragment(json);
+  const envelope = assertFiatStepResponse(json);
   if (stateKey(envelope.state) !== meta.stateKey) {
     throw new ContractViolation(
       `fixture ${id}: manifest says ${meta.stateKey}, envelope carries ${stateKey(envelope.state)}`

package/dist/index.mjs

@@ -8,7 +8,7 @@ import {
   isTerminal,
   stateKey,
   tableEntry
-} from "./chunk-UWR2DRHB.mjs";
+} from "./chunk-3R5GGUAK.mjs";
 
 // src/codes.ts
 var COUNTRY_CURRENCY_LIST = [
@@ -468,13 +468,32 @@ var $params = z.record(z.string(), JsonSchema).superRefine((params, ctx) => {
 var TransitionParamsSchema = $params;
 var $inputs = z.record(z.string(), $fieldSpec);
 var TransitionInputsSchema = $inputs;
+var MAX_DELAY_MS = 2 ** 31 - 1;
+var MIN_INTERVAL_MS = 500;
 var $pollSpec = obj({
   endpoint: $endpoint,
   params: $params.optional(),
-  intervalMs: z.number(),
-  backoffFactor: z.number().optional(),
-  maxIntervalMs: z.number().optional(),
-  giveUpAfterMs: z.number().optional()
+  intervalMs: z.number().int().min(MIN_INTERVAL_MS).max(MAX_DELAY_MS),
+  // Not `.int()` — 1.5 is the recorded factor and a legitimate one. `.finite()` is load-bearing:
+  // zod 3's `z.number()` admits Infinity, and `Infinity >= 1` satisfies `.min(1)` on its own.
+  backoffFactor: z.number().finite().min(1).optional(),
+  maxIntervalMs: z.number().int().min(MIN_INTERVAL_MS).max(MAX_DELAY_MS).optional(),
+  giveUpAfterMs: z.number().int().nonnegative().max(MAX_DELAY_MS).optional()
+}).superRefine((spec, ctx) => {
+  if (spec.backoffFactor !== void 0 && spec.maxIntervalMs === void 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["maxIntervalMs"],
+      message: "maxIntervalMs is required when backoffFactor is present \u2014 an unbounded backoff grows the interval past 2^31-1, where setTimeout truncates the delay to 0 and the poll hot-loops."
+    });
+  }
+  if (spec.maxIntervalMs !== void 0 && spec.maxIntervalMs < spec.intervalMs) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["maxIntervalMs"],
+      message: `maxIntervalMs (${spec.maxIntervalMs}) is below intervalMs (${spec.intervalMs}) \u2014 a ceiling under the starting interval caps the poll at less than its own first delay.`
+    });
+  }
 });
 var PollSpecSchema = $pollSpec;
 var $reportSpec = obj({
@@ -607,15 +626,7 @@ var $stepResponse = obj({
   transitions: z.array($transition),
   orderId: z.string().optional()
 });
-var StepResponseSchema = $stepResponse;
-var $stepResponseFragment = obj({
-  state: $flowState,
-  provider: $provider.optional(),
-  transitions: z.array($transition),
-  orderId: z.string().optional()
-});
-var StepResponseFragmentSchema = $stepResponseFragment;
-var EnvelopeSchema = StepResponseSchema;
+var FiatStepResponseSchema = $stepResponse;
 
 // src/fixtures/data.ts
 var FIXTURE_DATA = {
@@ -1033,6 +1044,7 @@ var FIXTURE_DATA = {
         "expiresAt": "2026-08-11T21:33:00Z"
       }
     },
+    "provider": "TRANSAK",
     "transitions": [
       {
         "id": "continue",
@@ -1054,6 +1066,7 @@ var FIXTURE_DATA = {
       "kind": "SESSION_AUTH",
       "channel": "EMAIL_OTP"
     },
+    "provider": "TRANSAK",
     "transitions": [
       {
         "id": "verify",
@@ -1103,6 +1116,7 @@ var FIXTURE_DATA = {
         "expiresAt": "\u2026"
       }
     },
+    "provider": "TRANSAK",
     "transitions": [
       {
         "id": "confirm_paid",
@@ -1121,8 +1135,7 @@ var FIXTURES = [
     source: "FE_DOC",
     docRef: "Screen 1 \xB7 Quote / review",
     screen: 1,
-    stateKey: "QUOTE",
-    complete: true
+    stateKey: "QUOTE"
   },
   {
     id: "screen-02-session-auth",
@@ -1130,8 +1143,7 @@ var FIXTURES = [
     source: "FE_DOC",
     docRef: "Screen 2 \xB7 Verification code (OTP)",
     screen: 2,
-    stateKey: "SESSION_AUTH",
-    complete: true
+    stateKey: "SESSION_AUTH"
   },
   {
     id: "screen-03-kyc-input-required",
@@ -1140,7 +1152,6 @@ var FIXTURES = [
     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."]
   },
   {
@@ -1150,7 +1161,6 @@ var FIXTURES = [
     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.`
     ]
@@ -1162,7 +1172,6 @@ var FIXTURES = [
     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)."
@@ -1174,8 +1183,7 @@ var FIXTURES = [
     source: "FE_DOC",
     docRef: "Screen 9 \xB7 Verifying identity",
     screen: 9,
-    stateKey: "KYC/NO_ACTION_REQUIRED:IN_REVIEW",
-    complete: true
+    stateKey: "KYC/NO_ACTION_REQUIRED:IN_REVIEW"
   },
   {
     id: "screen-10-kyc-on-hold",
@@ -1184,7 +1192,6 @@ var FIXTURES = [
     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."]
   },
   {
@@ -1194,7 +1201,6 @@ var FIXTURES = [
     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."
@@ -1207,7 +1213,6 @@ var FIXTURES = [
     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."
     ]
@@ -1218,8 +1223,7 @@ var FIXTURES = [
     source: "FE_DOC",
     docRef: "Screen 13 \xB7 Success",
     screen: 13,
-    stateKey: "ORDER/CREATED",
-    complete: true
+    stateKey: "ORDER/CREATED"
   },
   {
     id: "screen-14-order-failed",
@@ -1228,7 +1232,6 @@ var FIXTURES = [
     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."]
   },
   {
@@ -1237,8 +1240,7 @@ var FIXTURES = [
     source: "FE_DOC",
     docRef: "Screen 15 \xB7 Refund on the way",
     screen: 15,
-    stateKey: "ORDER/CREATED",
-    complete: true
+    stateKey: "ORDER/CREATED"
   },
   {
     id: "screen-16-blocked",
@@ -1247,7 +1249,6 @@ var FIXTURES = [
     docRef: "Screen 16 \xB7 Not available",
     screen: 16,
     stateKey: "BLOCKED",
-    complete: true,
     notes: ["The only flatly terminal state entry in the table."]
   },
   {
@@ -1256,7 +1257,6 @@ var FIXTURES = [
     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."]
   },
   {
@@ -1264,8 +1264,7 @@ var FIXTURES = [
     file: "worked-example-02-session-auth.json",
     source: "CONTRACT_DOC",
     docRef: "\xA7Worked example, step 2 (session challenge)",
-    stateKey: "SESSION_AUTH",
-    complete: false
+    stateKey: "SESSION_AUTH"
   },
   {
     id: "worked-example-04-payment-instruct",
@@ -1273,7 +1272,6 @@ var FIXTURES = [
     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)."
     ]
@@ -1322,17 +1320,11 @@ var formatIssues = (error) => {
     return path ? `${path}: ${issue.message ?? "invalid"}` : issue.message ?? "invalid";
   });
 };
-function assertEnvelope(json) {
-  const result = StepResponseSchema.safeParse(json);
+function assertFiatStepResponse(json) {
+  const result = FiatStepResponseSchema.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);
@@ -1427,7 +1419,7 @@ function walkTable(fn) {
 function assertFixture(id) {
   const meta = fixtureMeta(id);
   const json = loadFixture(id);
-  const envelope = meta.complete ? assertEnvelope(json) : assertEnvelopeFragment(json);
+  const envelope = assertFiatStepResponse(json);
   if (stateKey(envelope.state) !== meta.stateKey) {
     throw new ContractViolation(
       `fixture ${id}: manifest says ${meta.stateKey}, envelope carries ${stateKey(envelope.state)}`
@@ -1449,7 +1441,6 @@ export {
   CryptoAmountSchema,
   DOCUMENTED_ENDPOINTS,
   ENDPOINT_PATTERN,
-  EnvelopeSchema,
   FIAT_CURRENCY_NAMES,
   FIELD_SPEC_TYPES,
   FIXTURES,
@@ -1460,6 +1451,7 @@ export {
   FiatCurrencyCode,
   FiatEndpointSchema,
   FiatProviderSchema,
+  FiatStepResponseSchema,
   FieldSpecSchema,
   FlowStateSchema,
   FormDescriptorSchema,
@@ -1493,8 +1485,6 @@ export {
   SelectOptionSchema,
   SessionAuthStateSchema,
   StatusHistoryEntrySchema,
-  StepResponseFragmentSchema,
-  StepResponseSchema,
   SurfaceSchema,
   TABLE_VERSION,
   TERMINAL_ORDER_STATUSES,
@@ -1504,8 +1494,7 @@ export {
   TransitionSchema,
   TxSchema,
   assertAllFixtures,
-  assertEnvelope,
-  assertEnvelopeFragment,
+  assertFiatStepResponse,
   assertFixture,
   assertLegalEmission,
   assertLegalReturn,

package/dist/schemas.d.ts

@@ -27,11 +27,7 @@
  * 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, StepResponse, Surface, Transition, TransitionInputs, TransitionParams, Tx } from './types';
-/** The envelope as doc excerpts show it: `provider` elided. Never valid on the wire. */
-export type EnvelopeFragment = Omit<StepResponse, 'provider'> & {
-    provider?: FiatProvider;
-};
+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';
 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. */
@@ -91,8 +87,6 @@ export declare const PaymentInstructStateSchema: z.ZodType<State<'PAYMENT', 'INS
 export declare const OrderAwaitingConfirmationStateSchema: z.ZodType<State<'ORDER', 'AWAITING_CONFIRMATION'>>;
 export declare const OrderCreatedStateSchema: z.ZodType<State<'ORDER', 'CREATED'>>;
 export declare const FlowStateSchema: z.ZodType<FlowState>;
-export declare const StepResponseSchema: z.ZodType<StepResponse>;
-export declare const StepResponseFragmentSchema: z.ZodType<EnvelopeFragment>;
-export declare const EnvelopeSchema: z.ZodType<StepResponse>;
+export declare const FiatStepResponseSchema: z.ZodType<FiatStepResponse>;
 export {};
 //# sourceMappingURL=schemas.d.ts.map

package/dist/table.d.ts

@@ -20,9 +20,11 @@
 import type { FiatEndpoint, FlowState, OrderStatus, TransitionMode } from './types';
 /**
  * The package version IS the capability handshake's table version (contract §Conformance
- * package → Versioning). Must equal `package.json#version` — asserted in the test suite.
+ * package → Versioning). Derived from `package.json#version` at build time so the two can
+ * never drift — a version bump is one edit, in package.json. The test suite asserts the
+ * wiring still resolves to the package version.
  */
-export declare const TABLE_VERSION = "0.3.0";
+export declare const TABLE_VERSION: string;
 /**
  * State identity = kind + phase + the state's named discriminant (FE doc §Decisions).
  * The table keys on kind + phase (+ `reason` for KYC, whose three reasons differ in terminality

package/dist/table.js

@@ -30,7 +30,12 @@ __export(table_exports, {
   tableEntry: () => tableEntry
 });
 module.exports = __toCommonJS(table_exports);
-var TABLE_VERSION = "0.3.0";
+
+// package.json
+var version = "0.5.0";
+
+// src/table.ts
+var TABLE_VERSION = version;
 var TERMINAL_ORDER_STATUSES = [
   "SETTLED",
   "EXPIRED",

package/dist/table.mjs

@@ -7,7 +7,7 @@ import {
   isTerminal,
   stateKey,
   tableEntry
-} from "./chunk-UWR2DRHB.mjs";
+} from "./chunk-3R5GGUAK.mjs";
 export {
   DOCUMENTED_ENDPOINTS,
   STATE_KEYS,

package/dist/types.d.ts

@@ -56,7 +56,7 @@ export type HttpVerb = 'GET' | 'POST';
  * cannot express "no slash", so `GET /fiat/orders/${string}` also admits sub-paths. Precision at
  * that level is the table's job (`allowedTransitions` + `endpointMatches`), not the type's.
  */
-export type FiatEndpoint = '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/${string}` | `GET /fiat/orders/${string}/instructions` | `POST /fiat/orders/${string}/confirm-payment` | `POST /fiat/orders/${string}/reference` | `POST /fiat/orders/${string}/cancel` | `POST /fiat/orders/${string}/surface-result`;
+export type FiatEndpoint = 'GET /fiat/payment-methods' | 'POST /fiat/quote' | 'POST /fiat/auth' | 'POST /fiat/payment-session' | 'POST /fiat/session' | 'POST /fiat/session/verify' | 'GET /fiat/kyc' | 'POST /fiat/kyc/form' | 'POST /fiat/kyc/document' | 'POST /fiat/instruments' | 'POST /fiat/orders' | `GET /fiat/orders/${string}` | `GET /fiat/orders/${string}/instructions` | `POST /fiat/orders/${string}/confirm-payment` | `POST /fiat/orders/${string}/reference` | `POST /fiat/orders/${string}/cancel` | `POST /fiat/orders/${string}/surface-result`;
 /**
  * FiatProvider is metadata: it selects the embedded provider SDK for CLIENT_SURFACE steps and
  * feeds analytics. It never drives sequencing (contract §The envelope).
@@ -64,7 +64,7 @@ export type FiatEndpoint = 'GET /fiat/payment-methods' | 'POST /fiat/quote' | 'P
  * (contract §Decisions 3; Swapped-headless does not exist yet, Banxa is Tradeoff #4).
  * `SWAPPED` added at fun-backend's request (2026-08-17) so its legacy fops payment-provider id
  * has one shared vocabulary instead of a second fun-backend-local enum — it never appears as a
- * `StepResponse.provider` value since Swapped's fops flow doesn't emit this envelope.
+ * `FiatStepResponse.provider` value since Swapped's fops flow doesn't emit this envelope.
  */
 export type FiatProvider = 'TRANSAK' | 'SWAPPED';
 /**
@@ -311,12 +311,45 @@ export type FieldSpecType = FieldSpec['type'];
 export type TransitionParams = Record<string, JsonValue>;
 /** Client-collected specs — the harness renders + locally validates, then merges values in. */
 export type TransitionInputs = Record<string, FieldSpec>;
+/**
+ * Timing for an `AWAIT` poll.
+ *
+ * The numbers are bounded by `PollSpecSchema`, not by the type — TypeScript can't express a range.
+ * The bounds are part of the contract, enforced on the emitter by conformance tests, so a client
+ * can consume these fields directly and does not need to sanitize them:
+ *
+ * | field | bound |
+ * | --- | --- |
+ * | `intervalMs` | integer, `500 … 2^31-1` |
+ * | `backoffFactor` | finite, `>= 1` (**not** an integer — 1.5 is the recorded value) |
+ * | `maxIntervalMs` | integer, `500 … 2^31-1` |
+ * | `giveUpAfterMs` | integer, `0 … 2^31-1` |
+ *
+ * `2^31-1` is the ceiling because a larger `setTimeout` delay is silently truncated to 0, which
+ * hot-loops exactly as `intervalMs: 0` would.
+ *
+ * Two cross-field rules, both enforced by the schema:
+ *
+ * 1. **`maxIntervalMs` is required whenever `backoffFactor` is present.** A backoff with no ceiling
+ *    reaches that same truncation by a slower route. The factor itself is deliberately not capped —
+ *    only 1.5 has ever been recorded, so any cap would be arbitrary, whereas requiring the ceiling
+ *    that already exists is not.
+ * 2. **`maxIntervalMs >= intervalMs`.** A ceiling below the starting interval caps the poll at less
+ *    than its own first delay.
+ *
+ * Note there is deliberately no `giveUpAfterMs >= intervalMs` rule: a deadline shorter than the
+ * first interval means "give up without polling", which is coherent and legitimately emittable.
+ */
 export interface PollSpec {
     endpoint: FiatEndpoint;
     params?: TransitionParams;
+    /** Integer, `500 … 2^31-1`. */
     intervalMs: number;
+    /** Finite, `>= 1`. Not constrained to an integer: 1.5 is legitimate. Requires `maxIntervalMs`. */
     backoffFactor?: number;
+    /** Integer, `500 … 2^31-1`. Required when `backoffFactor` is present. */
     maxIntervalMs?: number;
+    /** Integer, `0 … 2^31-1`. */
     giveUpAfterMs?: number;
 }
 export interface ReportSpec {
@@ -449,7 +482,7 @@ export type FlowState = {
     /**
      * TODO(open-decision): `orderId` placement — envelope sibling (contract §Worked example,
      * steps 4–5) vs inside state (FE doc v0, Screen 6). Both are accepted here; the FE doc's
-     * in-state placement is the current shape, `StepResponse.orderId` covers the other.
+     * in-state placement is the current shape, `FiatStepResponse.orderId` covers the other.
      */
     orderId?: string;
     instructions: Instructions;
@@ -476,13 +509,11 @@ export type FlowStateKind = FlowState['kind'];
  * Every `/fiat/*` response. `transitions: []` = nothing the wizard can do; whether the *flow*
  * is over is read from the table (`terminal`), never from array emptiness (ON_HOLD is the proof).
  */
-export interface StepResponse {
+export interface FiatStepResponse {
     state: FlowState;
     provider: FiatProvider;
     transitions: Transition[];
     /** TODO(open-decision): `orderId` placement — see `PAYMENT{INSTRUCT}.orderId` above. */
     orderId?: string;
 }
-/** The envelope as it appears in the docs' JSON — alias kept because both names are in use. */
-export type Envelope = StepResponse;
 //# sourceMappingURL=types.d.ts.map

package/package.json

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