@fun-xyz/fiat-contract 0.5.0 → 0.7.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,14 +10,14 @@ 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
 
 | Import | Weight | Contains | Used by |
 | --- | --- | --- | --- |
 | `@fun-xyz/fiat-contract/types` | **0.1 KB** (types erase) | every type; no runtime values | production, both repos |
-| `@fun-xyz/fiat-contract/table` | **13.8 KB**, zero deps | `TRANSITION_TABLE`, `stateKey`, `tableEntry`, `isTerminal`, `walkTable`, `TABLE_VERSION`, `TERMINAL_ORDER_STATUSES`, `DOCUMENTED_ENDPOINTS` | **production frontend** + backend |
+| `@fun-xyz/fiat-contract/table` | **13.8 KB**, zero deps | `TRANSITION_TABLE`, `stateKey`, `tableEntry`, `isTerminal`, `walkTable`, `TABLE_VERSION`, `TERMINAL_ORDER_STATUSES`, `DOCUMENTED_ENDPOINTS`, `UNOFFERED_ENDPOINTS`, `UNREACHABLE_STATES`, `unofferedEndpoints`, `unreachableStates` | **production frontend** + backend |
 | `@fun-xyz/fiat-contract` | 47.6 KB, needs zod | the above + 46 zod schemas + assertions + 16 fixtures | tests, and backend dev/test guards |
 
 `./table` is not a micro-optimisation. Terminality is table data a **shipped** client must read
@@ -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-OGNYHIOE.mjs}

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.5.0";
+var version = "0.7.0";
 
 // src/table.ts
 var TABLE_VERSION = version;
@@ -30,22 +30,46 @@ var TRANSITION_TABLE = {
         endpoint: "POST /fiat/session",
         when: "no valid provider session token (own-tables check)"
       },
+      {
+        id: "open_session",
+        mode: "SUBMIT",
+        endpoint: "POST /fiat/payment-session",
+        when: "returning user, session + KYC valid, capture-first rail \u2014 the method authorises before any order exists",
+        note: "Returns PAYMENT{CAPTURE} carrying the Surface. Without this entry the capture-first rail has no legal way in: a transition-following client takes POST /fiat/orders instead, and the backend refuses that when the provider declares the capture-first capability and no authorisation is present. Named open_session per the Fiat Contract 0.7 doc, which adds quote-time-minted surface rows beside it."
+      },
       {
         id: "continue",
         mode: "SUBMIT",
         endpoint: "POST /fiat/orders",
-        when: "returning user, session + KYC valid \u2014 the quote screen doubles as review"
+        when: "returning user, session + KYC valid, order-first rail \u2014 the quote screen doubles as review",
+        note: "Narrowed to the order-first rail: on a capture-first method the order cannot be created before the payment is authorised, so the sibling payment-session entry is the one that applies."
       },
       {
         id: "continue",
         mode: "SUBMIT",
         endpoint: "POST /fiat/auth",
         when: "no ambient Fun identity (non-fomo surfaces only)"
+      },
+      {
+        id: "capture",
+        mode: "CLIENT_SURFACE",
+        endpoint: "POST /fiat/orders",
+        when: "capture-then-order rail whose session is minted at quote time (inline pay sheet)",
+        note: "The 0.7 row that makes the single-screen Apple Pay design legal: the surface rides QUOTE, the provider component IS the primary CTA, and its result creates the order. Apple policy forbids a visible step between an Apple-branded tap and the sheet, and TransakApplePay exposes no programmatic trigger, so a two-step via payment-session cannot serve this rail. Requires state.surface (\u03942)."
+      },
+      {
+        id: "capture",
+        mode: "CLIENT_SURFACE",
+        endpoint: "POST /fiat/orders/:id/surface-result",
+        when: "order-then-capture rail whose provider order was created with the quote-time session",
+        note: "Same quote-time placement, other topology: the order already exists, so the surface reports against it rather than creating one."
       }
     ],
     mayReturn: [
       "SESSION_AUTH",
       ...KYC_ANY,
+      "PAYMENT/CAPTURE",
+      "PAYMENT/INSTRUCT",
       "PENDING_ORDER",
       "ORDER/AWAITING_CONFIRMATION",
       "ORDER/CREATED",
@@ -53,8 +77,10 @@ var TRANSITION_TABLE = {
     ],
     terminal: false,
     notes: [
-      "Re-quote on amount change is a client-local event, not a transition.",
-      'If the PENDING_ORDER removal lands, QUOTE additionally returns PAYMENT{INSTRUCT} / ORDER{CREATED} directly. TODO(open-decision): contract \xA7"Proposal: remove PENDING_ORDER".'
+      "Re-quote on amount change is a client-local event, not a transition. A new quote carries a new surface; the client remounts the adapter rather than reusing the old session.",
+      "A surface on QUOTE and a SUBMIT to the same endpoint may not coexist \u2014 two paths to one order. assertLegalEmission enforces it; the server picks one per rail.",
+      `Both PAYMENT states are reachable directly from QUOTE: the FE doc canvas draws S1 \u2192 S5 (card, capture-first) and S1 \u2192 S6 (bank). This entry was first ported from the FE doc's bindings table, whose "May receive back" column omits both \u2014 the canvas is the correct source of the two.`,
+      'TODO(open-decision): contract \xA7"Proposal: remove PENDING_ORDER" would additionally have QUOTE return ORDER{CREATED} for an active order. That decision does not gate the PAYMENT edges above.'
     ]
   },
   FUN_AUTH: {
@@ -352,6 +378,7 @@ var DOCUMENTED_ENDPOINTS = [
   "GET /fiat/payment-methods",
   "POST /fiat/quote",
   "POST /fiat/auth",
+  "POST /fiat/payment-session",
   "POST /fiat/session",
   "POST /fiat/session/verify",
   "GET /fiat/kyc",
@@ -366,6 +393,54 @@ var DOCUMENTED_ENDPOINTS = [
   "POST /fiat/orders/:id/cancel",
   "POST /fiat/orders/:id/surface-result"
 ];
+var UNOFFERED_ENDPOINTS = [
+  {
+    endpoint: "GET /fiat/payment-methods",
+    reason: "Discovery, called before any flow state exists \u2014 there is no state to hang it off."
+  },
+  {
+    endpoint: "POST /fiat/kyc/document",
+    reason: "FILE fields stream to it directly; the harness owns that upload path and it is not a transition (see KYC/INPUT_REQUIRED notes)."
+  },
+  {
+    endpoint: "POST /fiat/instruments",
+    reason: "No state offers it and no published doc explains why. TODO(open-decision): saved instruments may simply be unreached in v1 \u2014 confirm, or wire it to the state that should offer it."
+  },
+  {
+    endpoint: "GET /fiat/orders/:id/instructions",
+    reason: "PAYMENT{INSTRUCT} carries its instructions in state and offers no fetch. TODO(open-decision): that state also notes no re-issue endpoint exists, which sits oddly beside this one being published \u2014 confirm or retire it."
+  },
+  {
+    endpoint: "POST /fiat/orders/:id/reference",
+    reason: "The bank-reference submission is offered by no state. TODO(open-decision): PAYMENT{INSTRUCT} is the plausible home \u2014 confirm or wire it."
+  }
+];
+var UNREACHABLE_STATES = [
+  {
+    stateKey: "FUN_AUTH",
+    reason: "No bindings row published (docStatus UNSPECIFIED) and never rendered in fomo, where identity is ambient. Entered out-of-band, not by a mayReturn edge."
+  }
+];
+function unofferedEndpoints() {
+  const offered = /* @__PURE__ */ new Set();
+  for (const key of STATE_KEYS) {
+    for (const allowed of TRANSITION_TABLE[key].allowedTransitions) offered.add(allowed.endpoint);
+  }
+  return DOCUMENTED_ENDPOINTS.filter((endpoint) => !offered.has(endpoint));
+}
+function unreachableStates(from = "QUOTE") {
+  const seen = /* @__PURE__ */ new Set([from]);
+  const queue = [from];
+  while (queue.length > 0) {
+    for (const target of TRANSITION_TABLE[queue.pop()].mayReturn ?? []) {
+      if (!seen.has(target)) {
+        seen.add(target);
+        queue.push(target);
+      }
+    }
+  }
+  return STATE_KEYS.filter((key) => !seen.has(key));
+}
 function stateKey(state) {
   switch (state.kind) {
     case "QUOTE":
@@ -408,8 +483,12 @@ export {
   TRANSITION_TABLE,
   STATE_KEYS,
   DOCUMENTED_ENDPOINTS,
+  UNOFFERED_ENDPOINTS,
+  UNREACHABLE_STATES,
+  unofferedEndpoints,
+  unreachableStates,
   stateKey,
   tableEntry,
   isTerminal
 };
-//# sourceMappingURL=chunk-3R5GGUAK.mjs.map
+//# sourceMappingURL=chunk-OGNYHIOE.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.
  *