@fun-xyz/fiat-contract 0.4.0 → 0.6.0

package/README.md

@@ -1,16 +1,16 @@
 # fiat-contract
 
-The **published contract** between `fun-backend` (emits envelopes) and `funkit`/`connect-core`
+The **published contract** between `fun-backend` (emits step responses) and `funkit`/`connect-core`
 (renders them). Both repos test against it; neither owns it.
 
 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 step responses (inlined as data — no filesystem, so React Native can bundle it) |
 
 ## Three entry points — production vs test-time
 
@@ -29,7 +29,7 @@ Metro before RN 0.79 ignores `exports` entirely — then greps the emitted bundl
 schemas and executes it.
 
 Source of truth: [Fiat Client Contract](https://app.notion.com/p/3b9fc3b2a002815eb270fa4c818268cc)
-(§The envelope · §Conformance package · §split `InputSpec` — ACCEPTED) and
+(§The fiat step response · §Conformance package · §split `InputSpec` — ACCEPTED) and
 [Fiat Frontend — State Machine & Screen Map](https://app.notion.com/p/3bbfc3b2a00281c994c2cebd17b1d6d3)
 (✅ Decisions · per-screen State details · Event bindings per flow state).
 Tracking: [Headless Fiat Onramp](https://linear.app/funxyz/project/headless-fiat-onramp-0147f4102399) ·
@@ -39,7 +39,7 @@ this package is [ENG-5268](https://linear.app/funxyz/issue/ENG-5268).
 
 1. **Errors are fields, never states.** Every fallible state carries `error?: FailureReason`.
    Stay-on-screen ⇒ an error field. Change-screen ⇒ a different state (session expiry just returns
-   a `SESSION_AUTH` envelope — there is no error routing table).
+   a `SESSION_AUTH` step response — there is no error routing table).
 2. **`params` = server literals · `inputs` = collected specs · `expects` = injected surface
    results.** `body = {…params, …collected(inputs), …injected(expects)}`; a key collision across
    the three is a contract violation, not last-write-wins. zod rejects a `FieldSpec` hiding in
@@ -55,27 +55,30 @@ 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 step-response validation in dev/test
 const owed = walkTable((entry) => entry.allowedTransitions); // what the adapter must emit
 ```
 
-Its own suites: adapter conformance (fixture-driven + property-generated states), outgoing-envelope
+Its own suites: adapter conformance (fixture-driven + property-generated states), outgoing step-response
 validation, and the scheduled provider-sandbox drift run diffed against `src/fixtures`.
 
 **`connect-core`** — the harness obeys `transitions` for sequencing and owns rendering.
@@ -88,7 +91,7 @@ FIXTURES.forEach(({ id }) => renderCold(loadFixture(id)));         // stale-rule
 ```
 
 Its own suites: exhaustive `computePage` table-walk, fixture-driven cold-render tests, harness units
-(any-state handling, same-state error re-entry retains form values, one-live-envelope focus gating,
+(any-state handling, same-state error re-entry retains form values, one-live-response focus gating,
 idempotency-key reuse).
 
 ## Usage
@@ -98,13 +101,13 @@ so these examples cannot drift from the API.
 
 ### Production: a backend route handler
 
-The backend *builds* envelopes, so its production use is entirely compile-time — the types are the
+The backend *builds* step responses, so its production use is entirely compile-time — the types are the
 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,19 +140,19 @@ 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 }) {
-  const page = computePage(stateKey(env.state), clientLocal); // client owns state → screen
-  const done = isTerminal(env.state);                          // table data, never inferred
+export function FiatScreen({ stepResponse }: { stepResponse: FiatStepResponse }) {
+  const page = computePage(stateKey(stepResponse.state), clientLocal); // client owns state → screen
+  const done = isTerminal(stepResponse.state);                          // table data, never inferred
 
-  if (env.state.kind === 'PAYMENT' && env.state.phase === 'INSTRUCT') {
-    return render(page, env.state.instructions); // narrowed: instructions exists here
+  if (stepResponse.state.kind === 'PAYMENT' && stepResponse.state.phase === 'INSTRUCT') {
+    return render(page, stepResponse.state.instructions); // narrowed: instructions exists here
   }
-  if (env.state.kind === 'ORDER' && env.state.phase === 'CREATED') {
-    return render(page, { status: env.state.status, done });
+  if (stepResponse.state.kind === 'ORDER' && stepResponse.state.phase === 'CREATED') {
+    return render(page, { status: stepResponse.state.status, done });
   }
-  return render(page, env.state);
+  return render(page, stepResponse.state);
 }
 ```
 
@@ -160,13 +163,13 @@ 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(stepResponse: FiatStepResponse) {
   return {
-    ctas: env.transitions.filter((t) => t.mode === 'SUBMIT'),          // render buttons
-    poll: env.transitions.find((t) => t.mode === 'AWAIT'),             // harness schedules
-    surface: env.transitions.find((t) => t.mode === 'CLIENT_SURFACE'), // harness mounts
+    ctas: stepResponse.transitions.filter((t) => t.mode === 'SUBMIT'),          // render buttons
+    poll: stepResponse.transitions.find((t) => t.mode === 'AWAIT'),             // harness schedules
+    surface: stepResponse.transitions.find((t) => t.mode === 'CLIENT_SURFACE'), // harness mounts
   };
 }
 
@@ -188,19 +191,20 @@ Screens never inspect the array themselves; they receive `ctas` and bind labels
 
 These import from the root, which carries zod. Test-time only.
 
-### Validate an envelope at the boundary
+### Validate a step response 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
-  if (envelope.state.kind === 'PAYMENT' && envelope.state.phase === 'INSTRUCT') {
-    render(envelope.state.instructions); // narrowed: instructions exists, quote does not
+  const stepResponse = assertFiatStepResponse(await res.json());
+  //    ^? FiatStepResponse — state is a narrowable discriminated union from here on
+  if (stepResponse.state.kind === 'PAYMENT' && stepResponse.state.phase === 'INSTRUCT') {
+    render(stepResponse.state.instructions); // narrowed: instructions exists, quote does not
   }
 } catch (err) {
   if (err instanceof ContractViolation) console.error(err.issues); // ['state.quote: Required', …]
@@ -261,16 +265,16 @@ TRANSITION_TABLE['PAYMENT/INSTRUCT'].mayReturn; // ['ORDER/CREATED']
 
 ### Render every fixture cold (stale-rule survival)
 
-Any call may return any state, so every screen must render from a cold envelope with no prior
-context. The fixtures are the FE doc's own envelopes, so this is a test against the spec.
+Any call may return any state, so every screen must render from a cold step response with no
+prior context. The fixtures are the FE doc's own responses, so this is a test against the spec.
 
 ```ts
 import { FIXTURES, loadFixture, assertFixture } from '@fun-xyz/fiat-contract';
 
 FIXTURES.forEach(({ id, stateKey, docRef }) => {
   it(`${id} renders cold (${docRef})`, () => {
-    const { envelope } = assertFixture(id); // validated + emission-legality checked
-    expect(() => renderCold(envelope)).not.toThrow();
+    const { stepResponse } = assertFixture(id); // validated + emission-legality checked
+    expect(() => renderCold(stepResponse)).not.toThrow();
     expect(computePage(stateKey)).toBeDefined();
   });
 });
@@ -280,7 +284,7 @@ loadFixture('screen-10-kyc-on-hold'); // raw JSON, fresh deep copy, `unknown`
 
 ### Use a schema directly
 
-All 46 schemas are exported when you need to validate a fragment rather than a whole envelope.
+All 46 schemas are exported when you need to validate a fragment rather than a whole step response.
 They are typed `z.ZodType<T>`, so you get `.parse` / `.safeParse` / `.optional()` — not `.shape` or
 `.extend`, deliberately.
 
@@ -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
@@ -431,7 +435,7 @@ The current documented shape is what ships; none of these are settled here.
 
 | Open item | How 0.1.0 encodes it |
 | --- | --- |
-| `orderId` placement | Both: optional on `PAYMENT{INSTRUCT}` (FE doc v0) **and** optional as an envelope sibling (contract worked example). One fixture of each. |
+| `orderId` placement | Both: optional on `PAYMENT{INSTRUCT}` (FE doc v0) **and** optional beside `state` (contract worked example). One fixture of each. |
 | `PENDING_ORDER` removal | Kind ships, with the removal proposal flagged on the type, the table entry, and the fixture. Screen 12 stays frozen. |
 | `[OQ7]` failure enumeration | The published `FailureReason` taxonomy only. Expired instructions, partial payment, per-rail cancel eligibility, and terminal-vs-escalating rejections are flagged unenumerated. |
 | Screen 11 escalation trigger | Encoded as published (`SUBMIT GET /fiat/kyc` + `params: {tier}`) with the doc's own warning that a GET carrying params is not a real shape. |
@@ -439,11 +443,11 @@ The current documented shape is what ships; none of these are settled here.
 | Cancel placement | `cancel` is legal on `PAYMENT{INSTRUCT}` and `ORDER{CREATED}`, marked conditional on the placement decision. |
 | `FUN_AUTH` shape | `challenge: Record<string, JsonValue>`; the table entry is `docStatus: 'UNSPECIFIED'`, so `assertLegalEmission` reports it unjudgeable instead of guessing. |
 | `statusHistory` element shape | The documented minimum (`{status}`) — no invented timestamps. |
-| `QR_IMAGE` instruction | In the union per §The envelope, flagged against OQ1's "deliberately not pre-declared". |
+| `QR_IMAGE` instruction | In the union per §The fiat step response, flagged against OQ1's "deliberately not pre-declared". |
 
-Two fixture gaps are declared in `FIXTURE_COVERAGE_GAPS` rather than filled with invented envelopes:
+Two fixture gaps are declared in `FIXTURE_COVERAGE_GAPS` rather than filled with invented step responses:
 `FUN_AUTH` (shape owned by the auth spike) and `KYC/CAPTURE` (Screen 8 tombstone, dropped from v1).
-Every other state has a recorded envelope.
+Every other state has a recorded step response.
 
 ## Not decided here — needs a human
 

package/dist/assert.d.ts

@@ -3,26 +3,21 @@
  * exactly two things: validate shapes (zod) and judge emissions against the table.
  *
  * Test *suites* live in the consumer repos next to the code they test:
- *  - `fun-backend`: adapter conformance (every emission ∈ the legal set), outgoing-envelope
+ *  - `fun-backend`: adapter conformance (every emission ∈ the legal set), outgoing step-response
  *    validation in dev/test, the scheduled provider drift run.
  *  - `connect-core`: exhaustive `computePage` table-walk, fixture-driven cold-render tests,
  *    harness units.
  */
 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'];
-    };
+    stepResponse: 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-VLQLWQPK.mjs → chunk-EHYDQU4T.mjs}

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

package/dist/fixtures/index.d.ts

@@ -1,18 +1,18 @@
 /**
  * fiat-contract — recorded fixtures + loader.
  *
- * Every `.json` file in this directory is an envelope copied **verbatim** from the docs — the FE
- * doc's per-screen "State details" envelopes plus the contract doc's worked example. The one
+ * Every `.json` file in this directory is a step response copied **verbatim** from the docs — the
+ * FE doc's per-screen "State details" responses plus the contract doc's worked example. The one
  * exception is `screen-04-order-review.json`, whose payload the doc publishes *by reference*
  * ("quote: <same shape as Screen 1, refreshed>"): its quote is Screen 1's payload verbatim.
  * They are
  * 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 step response (`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-response shape.
  */
 import type { StateKey } from '../table';
 export type FixtureSource = 'FE_DOC' | 'CONTRACT_DOC';
@@ -20,18 +20,16 @@ export interface FixtureMeta {
     id: string;
     file: string;
     source: FixtureSource;
-    /** Where in the source doc this envelope is published. */
+    /** Where in the source doc this step response is published. */
     docRef: string;
     /** 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[];
 /**
- * State entries with no published envelope to record. Declared so missing coverage is visible
+ * State entries with no published step response to record. Declared so missing coverage is visible
  * instead of silent — the fixture test asserts coverage equals (all state keys − these).
  */
 export declare const FIXTURE_COVERAGE_GAPS: readonly {
@@ -40,7 +38,7 @@ export declare const FIXTURE_COVERAGE_GAPS: readonly {
 }[];
 export declare const fixtureMeta: (id: string) => FixtureMeta;
 /**
- * Raw envelope — deliberately `unknown`, so callers validate before use.
+ * Raw step response — deliberately `unknown`, so callers validate before use.
  *
  * Reads from the generated `data.ts`: no filesystem, so this works under React Native, in a
  * browser, and in both CJS and ESM output. A fresh deep copy each call, so a consumer mutating a

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * fiat-contract — the published contract between `fun-backend` (emits envelopes) and
+ * fiat-contract — the published contract between `fun-backend` (emits step responses) and
  * `funkit`/`connect-core` (renders them). Types + zod schemas + the transition table as data +
  * recorded fixtures + assertion helpers. No runtime logic beyond validation and assertion.
  *

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.6.0";
 
 // src/table.ts
-var TABLE_VERSION = "0.4.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,20 +1765,19 @@ 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)."
+      "The response-level `orderId` case. TODO(open-decision): orderId placement (beside `state` here vs inside it in the FE doc v0)."
     ]
   }
 ];
 var FIXTURE_COVERAGE_GAPS = [
   {
     stateKey: "FUN_AUTH",
-    reason: "No envelope exists in either doc \u2014 shape owned by the auth spike, and FUN_AUTH never renders in fomo. TODO(open-decision): contract \xA7Auth & ref binding, item 5."
+    reason: "No step response exists in either doc \u2014 shape owned by the auth spike, and FUN_AUTH never renders in fomo. TODO(open-decision): contract \xA7Auth & ref binding, item 5."
   },
   {
     stateKey: "KYC/CAPTURE",
-    reason: "Dropped from v1 (FE Screen 8 tombstone, no UK module coverage); no envelope was ever published. Kind retained as handshake-gated vocabulary."
+    reason: "Dropped from v1 (FE Screen 8 tombstone, no UK module coverage); no step response was ever published. Kind retained as handshake-gated vocabulary."
   }
 ];
 var fixtureMeta = (id) => {
@@ -1815,15 +1813,9 @@ var formatIssues = (error) => {
     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));
+function assertFiatStepResponse(json) {
+  const result = FiatStepResponseSchema.safeParse(json);
+  if (!result.success) throw new ContractViolation("invalid fiat step response", formatIssues(result.error));
   return result.data;
 }
 function endpointMatches(template, actual) {
@@ -1920,14 +1912,14 @@ function walkTable(fn) {
 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) {
+  const stepResponse = assertFiatStepResponse(json);
+  if (stateKey(stepResponse.state) !== meta.stateKey) {
     throw new ContractViolation(
-      `fixture ${id}: manifest says ${meta.stateKey}, envelope carries ${stateKey(envelope.state)}`
+      `fixture ${id}: manifest says ${meta.stateKey}, step response carries ${stateKey(stepResponse.state)}`
     );
   }
-  assertLegalEmission(envelope.state, envelope.transitions);
-  return { meta, envelope };
+  assertLegalEmission(stepResponse.state, stepResponse.transitions);
+  return { meta, stepResponse };
 }
 function assertAllFixtures() {
   return FIXTURES.map((meta) => assertFixture(meta.id));

package/dist/index.mjs

@@ -8,7 +8,7 @@ import {
   isTerminal,
   stateKey,
   tableEntry
-} from "./chunk-VLQLWQPK.mjs";
+} from "./chunk-EHYDQU4T.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,20 +1272,19 @@ 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)."
+      "The response-level `orderId` case. TODO(open-decision): orderId placement (beside `state` here vs inside it in the FE doc v0)."
     ]
   }
 ];
 var FIXTURE_COVERAGE_GAPS = [
   {
     stateKey: "FUN_AUTH",
-    reason: "No envelope exists in either doc \u2014 shape owned by the auth spike, and FUN_AUTH never renders in fomo. TODO(open-decision): contract \xA7Auth & ref binding, item 5."
+    reason: "No step response exists in either doc \u2014 shape owned by the auth spike, and FUN_AUTH never renders in fomo. TODO(open-decision): contract \xA7Auth & ref binding, item 5."
   },
   {
     stateKey: "KYC/CAPTURE",
-    reason: "Dropped from v1 (FE Screen 8 tombstone, no UK module coverage); no envelope was ever published. Kind retained as handshake-gated vocabulary."
+    reason: "Dropped from v1 (FE Screen 8 tombstone, no UK module coverage); no step response was ever published. Kind retained as handshake-gated vocabulary."
   }
 ];
 var fixtureMeta = (id) => {
@@ -1322,15 +1320,9 @@ var formatIssues = (error) => {
     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));
+function assertFiatStepResponse(json) {
+  const result = FiatStepResponseSchema.safeParse(json);
+  if (!result.success) throw new ContractViolation("invalid fiat step response", formatIssues(result.error));
   return result.data;
 }
 function endpointMatches(template, actual) {
@@ -1427,14 +1419,14 @@ function walkTable(fn) {
 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) {
+  const stepResponse = assertFiatStepResponse(json);
+  if (stateKey(stepResponse.state) !== meta.stateKey) {
     throw new ContractViolation(
-      `fixture ${id}: manifest says ${meta.stateKey}, envelope carries ${stateKey(envelope.state)}`
+      `fixture ${id}: manifest says ${meta.stateKey}, step response carries ${stateKey(stepResponse.state)}`
     );
   }
-  assertLegalEmission(envelope.state, envelope.transitions);
-  return { meta, envelope };
+  assertLegalEmission(stepResponse.state, stepResponse.transitions);
+  return { meta, stepResponse };
 }
 function assertAllFixtures() {
   return FIXTURES.map((meta) => assertFixture(meta.id));
@@ -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

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

@@ -10,7 +10,7 @@
  *
  * Rules the entries obey:
  *   - Terminality of `ORDER{CREATED}` rides `status`, because terminal outcomes are OrderStatus,
- *     never kinds (contract §The envelope). The set is enumerated below as
+ *     never kinds (contract §The fiat step response). The set is enumerated below as
  *     `TERMINAL_ORDER_STATUSES` — clients read it, they never derive it.
  *   - A terminal *state* carries no transitions. A terminal *status* still can: `FAILED` with a
  *     retryable `failureReason` carries the recovery CTA (FE doc Screen 14).
@@ -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.4.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
@@ -30,7 +32,7 @@ export declare const TABLE_VERSION = "0.4.0";
  */
 export type StateKey = 'QUOTE' | 'FUN_AUTH' | 'SESSION_AUTH' | 'KYC/CAPTURE' | 'KYC/INPUT_REQUIRED' | 'KYC/NO_ACTION_REQUIRED:IN_REVIEW' | 'KYC/NO_ACTION_REQUIRED:ON_HOLD' | 'KYC/NO_ACTION_REQUIRED:REJECTED' | 'PENDING_ORDER' | 'BLOCKED' | 'PAYMENT/CAPTURE' | 'PAYMENT/INSTRUCT' | 'ORDER/AWAITING_CONFIRMATION' | 'ORDER/CREATED';
 /**
- * Terminal per the OrderStatus machine's monotonic ranks (contract §The envelope).
+ * Terminal per the OrderStatus machine's monotonic ranks (contract §The fiat step response).
  *
  * `CAPTURE_ORPHANED` is deliberately absent — see the TODO(open-decision) on the value itself.
  * Non-terminal is the safe default for an unknown status: a client that wrongly believes the flow
@@ -46,7 +48,7 @@ export type TerminalOrderStatus = (typeof TERMINAL_ORDER_STATUSES)[number];
 export type EndpointTemplate = FiatEndpoint;
 export interface AllowedTransition {
     /**
-     * The id observed in the docs' envelopes. Informational: ids are localization keys and the
+     * The id observed in the docs' step responses. Informational: ids are localization keys and the
      * docs explicitly allow unknown ids (the client falls back to `labelFallback`), so
      * `assertLegalEmission` matches on `mode` + `endpoint`, not on `id`.
      */

package/dist/table.js

@@ -30,7 +30,12 @@ __export(table_exports, {
   tableEntry: () => tableEntry
 });
 module.exports = __toCommonJS(table_exports);
-var TABLE_VERSION = "0.4.0";
+
+// package.json
+var version = "0.6.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-VLQLWQPK.mjs";
+} from "./chunk-EHYDQU4T.mjs";
 export {
   DOCUMENTED_ENDPOINTS,
   STATE_KEYS,

package/dist/types.d.ts

@@ -1,13 +1,13 @@
 /**
  * fiat-contract — types
  *
- * The published contract between `fun-backend` (emits envelopes) and
+ * The published contract between `fun-backend` (emits step responses) and
  * `funkit`/`connect-core` (renders them). Zero runtime logic lives here.
  *
  * Sources of truth (do not extend this file from anywhere else):
  *  - Contract doc: Fiat Client Contract — Step-Driven Flow & Endpoint Schematics
  *    https://app.notion.com/p/3b9fc3b2a002815eb270fa4c818268cc
- *    §"The envelope" · §"Conformance package — concrete spec"
+ *    §"The fiat step response" · §"Conformance package — concrete spec"
  *    §"Proposal (2026-08-13): split InputSpec → params + inputs + expects" (ACCEPTED)
  *  - FE doc: Fiat Frontend — State Machine & Screen Map
  *    https://app.notion.com/p/3bbfc3b2a00281c994c2cebd17b1d6d3
@@ -59,12 +59,12 @@ export type HttpVerb = 'GET' | 'POST';
 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).
+ * feeds analytics. It never drives sequencing (contract §The fiat step response).
  * TODO(open-decision): the docs name only Transak as a v1 provider for the headless flow
  * (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 response.
  */
 export type FiatProvider = 'TRANSAK' | 'SWAPPED';
 /**
@@ -101,7 +101,7 @@ export type FailureCategory = 'PAYMENT_DECLINED' | 'KYC_REJECTED' | 'PROVIDER_OU
  * (the FE doc's Screen 11 note writes `SUPPORT` as shorthand — same value).
  */
 export type Recovery = 'REQUOTE' | 'RETRY_PAYMENT' | 'CONTACT_SUPPORT' | 'NONE';
-/** Three expiries, three recoveries (contract §The envelope, FailureReason comment). */
+/** Three expiries, three recoveries (contract §The fiat step response, FailureReason comment). */
 export type ExpiredWhich = 'QUOTE' | 'PAYMENT_WINDOW' | 'INSTRUCTIONS';
 /**
  * `code?` is a copy key (e.g. `BAD_CODE`), not an error code to branch on.
@@ -121,7 +121,7 @@ export type FailureReason = {
     code?: string;
 };
 /**
- * Amounts are decimal strings in the docs' envelopes ("100.00") — never numbers.
+ * Amounts are decimal strings in the docs' step responses ("100.00") — never numbers.
  * Named to pair with `CryptoAmount`: every use site is a `fiat:` field.
  * `currency` is ISO 4217 — see `./codes`.
  */
@@ -172,7 +172,7 @@ export interface OrderRef {
 }
 /**
  * Payload of `ORDER{CREATED}` (FE doc Screens 7 · 13 · 14 · 15).
- * `crypto` is optional because the Screen 14/15 envelopes omit it (fiat-only failure/refund views).
+ * `crypto` is optional because the Screen 14/15 responses omit it (fiat-only failure/refund views).
  */
 export interface OrderSummary {
     orderId: string;
@@ -228,8 +228,8 @@ export interface InstructionField {
 /**
  * Payload of `PAYMENT{INSTRUCT}` — push rails. Values are PII-adjacent: never logged.
  * TODO(open-decision): contract OQ1 lists `QR_IMAGE` as *deliberately not pre-declared* in the
- * v1 vocabulary while §The envelope's Instructions bullet enumerates it. Kept in the union per
- * the envelope section (and the conformance-package spec); handshake-gate it if OQ1 lands the
+ * v1 vocabulary while §The fiat step response's Instructions bullet enumerates it. Kept in the union
+ * per that section (and the conformance-package spec); handshake-gate it if OQ1 lands the
  * other way.
  * TODO(open-decision): contract OQ7 — expired instructions have no documented recovery and no
  * re-issue endpoint exists.
@@ -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 {
@@ -404,7 +437,7 @@ export type FlowState = {
      *     empty transitions, NOT terminal.
      *   - `OrderStatus.ON_HOLD` = post-order compliance or amount mismatch, resolves to
      *     `PROCESSING` or `REFUNDED`.
-     * They cannot be confused in code — different types, different positions in the envelope —
+     * They cannot be confused in code — different types, different positions in the response —
      * but they can be confused in conversation, so say which one you mean.
      */
     reason: 'IN_REVIEW' | 'ON_HOLD' | 'REJECTED';
@@ -447,9 +480,9 @@ export type FlowState = {
     kind: 'PAYMENT';
     phase: 'INSTRUCT';
     /**
-     * TODO(open-decision): `orderId` placement — envelope sibling (contract §Worked example,
+     * TODO(open-decision): `orderId` placement — beside `state` (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;
@@ -462,7 +495,7 @@ export type FlowState = {
 } | {
     kind: 'ORDER';
     phase: 'CREATED';
-    /** Absent in the contract's terse worked-example envelopes, present in every FE screen. */
+    /** Absent in the contract's terse worked-example responses, present in every FE screen. */
     order?: OrderSummary;
     status: OrderStatus;
     statusHistory?: StatusHistoryEntry[];
@@ -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.4.0",
+  "version": "0.6.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": {