@fun-xyz/fiat-contract 0.5.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # 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:
@@ -10,7 +10,7 @@ Four things, zero runtime logic beyond validation:
 | `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/` | `assertFiatStepResponse` · `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
@@ -74,11 +74,11 @@ removals also ride a minor, with no deprecated aliases kept — consumers pin an
 import { assertFiatStepResponse, assertLegalEmission, walkTable } from '@fun-xyz/fiat-contract';
 
 assertLegalEmission(state, transitions);                     // per emission: adapter conformance
-assertFiatStepResponse(outgoing);                            // outgoing-envelope validation in dev/test
+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.
@@ -91,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
@@ -101,7 +101,7 @@ 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
@@ -142,17 +142,17 @@ production-safe: types erase, `./table` is 13.8 KB with no zod.
 import { isTerminal, stateKey } from '@fun-xyz/fiat-contract/table';
 import type { FiatStepResponse } from '@fun-xyz/fiat-contract/types';
 
-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
+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);
 }
 ```
 
@@ -165,11 +165,11 @@ re-derive that rule locally.
 ```ts
 import type { FiatStepResponse, Transition } from '@fun-xyz/fiat-contract/types';
 
-function useTransitions(env: FiatStepResponse) {
+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
   };
 }
 
@@ -191,7 +191,7 @@ 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
 
 `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
@@ -201,10 +201,10 @@ listing every problem. Use it on the way out of `fun-backend` (dev/test) and on
 import { assertFiatStepResponse, ContractViolation } from '@fun-xyz/fiat-contract';
 
 try {
-  const envelope = assertFiatStepResponse(await res.json());
+  const stepResponse = 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
+  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', …]
@@ -265,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();
   });
 });
@@ -284,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.
 
@@ -435,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. |
@@ -443,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,7 +3,7 @@
  * 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.
@@ -49,7 +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;
-    envelope: FiatStepResponse;
+    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-3R5GGUAK.mjs → chunk-EHYDQU4T.mjs}

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.5.0";
+var version = "0.6.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -412,4 +412,4 @@ export {
   tableEntry,
   isTerminal
 };
-//# sourceMappingURL=chunk-3R5GGUAK.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.
  *
- * Every fixture is a full envelope (`state` + `provider` + `transitions`). The contract doc's worked
+ * 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-envelope shape.
+ * wire, and the contract has no half-response shape.
  */
 import type { StateKey } from '../table';
 export type FixtureSource = 'FE_DOC' | 'CONTRACT_DOC';
@@ -20,7 +20,7 @@ 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;
@@ -29,7 +29,7 @@ export interface FixtureMeta {
 }
 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 {
@@ -38,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

@@ -718,7 +718,7 @@ var $stepResponse = obj({
 var FiatStepResponseSchema = $stepResponse;
 
 // package.json
-var version = "0.5.0";
+var version = "0.6.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -1766,18 +1766,18 @@ var FIXTURES = [
     docRef: "\xA7Worked example, steps 4\u20135 (order + bank instructions)",
     stateKey: "PAYMENT/INSTRUCT",
     notes: [
-      "The envelope-sibling `orderId` case. TODO(open-decision): orderId placement (envelope sibling here vs inside state in the FE doc v0)."
+      "The response-level `orderId` case. TODO(open-decision): orderId placement (beside `state` here vs inside it in the FE doc v0)."
     ]
   }
 ];
 var FIXTURE_COVERAGE_GAPS = [
   {
     stateKey: "FUN_AUTH",
-    reason: "No envelope exists in either doc \u2014 shape owned by the auth spike, and FUN_AUTH never renders in fomo. TODO(open-decision): contract \xA7Auth & ref binding, item 5."
+    reason: "No step response exists in either doc \u2014 shape owned by the auth spike, and FUN_AUTH never renders in fomo. TODO(open-decision): contract \xA7Auth & ref binding, item 5."
   },
   {
     stateKey: "KYC/CAPTURE",
-    reason: "Dropped from v1 (FE Screen 8 tombstone, no UK module coverage); no envelope was ever published. Kind retained as handshake-gated vocabulary."
+    reason: "Dropped from v1 (FE Screen 8 tombstone, no UK module coverage); no step response was ever published. Kind retained as handshake-gated vocabulary."
   }
 ];
 var fixtureMeta = (id) => {
@@ -1815,7 +1815,7 @@ var formatIssues = (error) => {
 };
 function assertFiatStepResponse(json) {
   const result = FiatStepResponseSchema.safeParse(json);
-  if (!result.success) throw new ContractViolation("invalid envelope", formatIssues(result.error));
+  if (!result.success) throw new ContractViolation("invalid fiat step response", formatIssues(result.error));
   return result.data;
 }
 function endpointMatches(template, actual) {
@@ -1912,14 +1912,14 @@ function walkTable(fn) {
 function assertFixture(id) {
   const meta = fixtureMeta(id);
   const json = loadFixture(id);
-  const envelope = assertFiatStepResponse(json);
-  if (stateKey(envelope.state) !== meta.stateKey) {
+  const stepResponse = assertFiatStepResponse(json);
+  if (stateKey(stepResponse.state) !== meta.stateKey) {
     throw new ContractViolation(
-      `fixture ${id}: manifest says ${meta.stateKey}, envelope carries ${stateKey(envelope.state)}`
+      `fixture ${id}: manifest says ${meta.stateKey}, step response carries ${stateKey(stepResponse.state)}`
     );
   }
-  assertLegalEmission(envelope.state, envelope.transitions);
-  return { meta, envelope };
+  assertLegalEmission(stepResponse.state, stepResponse.transitions);
+  return { meta, stepResponse };
 }
 function assertAllFixtures() {
   return FIXTURES.map((meta) => assertFixture(meta.id));

package/dist/index.mjs

@@ -8,7 +8,7 @@ import {
   isTerminal,
   stateKey,
   tableEntry
-} from "./chunk-3R5GGUAK.mjs";
+} from "./chunk-EHYDQU4T.mjs";
 
 // src/codes.ts
 var COUNTRY_CURRENCY_LIST = [
@@ -1273,18 +1273,18 @@ var FIXTURES = [
     docRef: "\xA7Worked example, steps 4\u20135 (order + bank instructions)",
     stateKey: "PAYMENT/INSTRUCT",
     notes: [
-      "The envelope-sibling `orderId` case. TODO(open-decision): orderId placement (envelope sibling here vs inside state in the FE doc v0)."
+      "The response-level `orderId` case. TODO(open-decision): orderId placement (beside `state` here vs inside it in the FE doc v0)."
     ]
   }
 ];
 var FIXTURE_COVERAGE_GAPS = [
   {
     stateKey: "FUN_AUTH",
-    reason: "No envelope exists in either doc \u2014 shape owned by the auth spike, and FUN_AUTH never renders in fomo. TODO(open-decision): contract \xA7Auth & ref binding, item 5."
+    reason: "No step response exists in either doc \u2014 shape owned by the auth spike, and FUN_AUTH never renders in fomo. TODO(open-decision): contract \xA7Auth & ref binding, item 5."
   },
   {
     stateKey: "KYC/CAPTURE",
-    reason: "Dropped from v1 (FE Screen 8 tombstone, no UK module coverage); no envelope was ever published. Kind retained as handshake-gated vocabulary."
+    reason: "Dropped from v1 (FE Screen 8 tombstone, no UK module coverage); no step response was ever published. Kind retained as handshake-gated vocabulary."
   }
 ];
 var fixtureMeta = (id) => {
@@ -1322,7 +1322,7 @@ var formatIssues = (error) => {
 };
 function assertFiatStepResponse(json) {
   const result = FiatStepResponseSchema.safeParse(json);
-  if (!result.success) throw new ContractViolation("invalid envelope", formatIssues(result.error));
+  if (!result.success) throw new ContractViolation("invalid fiat step response", formatIssues(result.error));
   return result.data;
 }
 function endpointMatches(template, actual) {
@@ -1419,14 +1419,14 @@ function walkTable(fn) {
 function assertFixture(id) {
   const meta = fixtureMeta(id);
   const json = loadFixture(id);
-  const envelope = assertFiatStepResponse(json);
-  if (stateKey(envelope.state) !== meta.stateKey) {
+  const stepResponse = assertFiatStepResponse(json);
+  if (stateKey(stepResponse.state) !== meta.stateKey) {
     throw new ContractViolation(
-      `fixture ${id}: manifest says ${meta.stateKey}, envelope carries ${stateKey(envelope.state)}`
+      `fixture ${id}: manifest says ${meta.stateKey}, step response carries ${stateKey(stepResponse.state)}`
     );
   }
-  assertLegalEmission(envelope.state, envelope.transitions);
-  return { meta, envelope };
+  assertLegalEmission(stepResponse.state, stepResponse.transitions);
+  return { meta, stepResponse };
 }
 function assertAllFixtures() {
   return FIXTURES.map((meta) => assertFixture(meta.id));

package/dist/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.
  *

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).
@@ -32,7 +32,7 @@ export declare const TABLE_VERSION: string;
  */
 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
@@ -48,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

@@ -32,7 +32,7 @@ __export(table_exports, {
 module.exports = __toCommonJS(table_exports);
 
 // package.json
-var version = "0.5.0";
+var version = "0.6.0";
 
 // src/table.ts
 var TABLE_VERSION = version;

package/dist/table.mjs

@@ -7,7 +7,7 @@ import {
   isTerminal,
   stateKey,
   tableEntry
-} from "./chunk-3R5GGUAK.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
- * `FiatStepResponse.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.
@@ -437,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';
@@ -480,7 +480,7 @@ 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, `FiatStepResponse.orderId` covers the other.
      */
@@ -495,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[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fun-xyz/fiat-contract",
-  "version": "0.5.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": {