FlowState — a flow-focused DSL over xState

// FlowState — flow-focused DSL.
//   Statechart semantics; symbolic actions; schemas at boundaries;
//   no mutable JS context, no inline functions, no foot-guns.

defineFlowState({
  id: "shop.checkout",
  version: "1.0.0",
  inputSchema:  z.object({ userId: z.string(), cartId: z.string() }),
  outputSchema: z.object({ orderId: z.string() }),
  initial: "loading",
  states: {
    loading: {
      invoke: { action: "action:cart.load@^1", input: "$.cartId" },
      on: { DONE: "pricing", ERROR: "failed" },
    },
    pricing: {
      invoke: { action: "action:cart.price@^2", input: "$.cart" },
      on: { DONE: "review" },
    },
    review: {
      type: "parallel",
      states: {
        humanApproval: { invoke: { action: "action:human.approve@^1" } },
        fraudCheck:    { invoke: { action: "action:fraud.check@^3" } },
      },
      onDone: "charging",
    },
    charging: {
      invoke: {
        action: "action:payment.charge@^1",
        input:  "$.total",
        idempotencyKey: "$.cartId",
      },
      on: { DONE: "done", ERROR: "refunding" },
    },
    refunding: {
      invoke: { action: "action:payment.refund@^1" },
      on: { DONE: "failed" },
    },
    done:   { type: "final", output: { orderId: "$.orderId" } },
    failed: { type: "final" },
  },
})

// Compiles to:
//   • Canonical JSON (RFC 8785) — registry-publishable
//   • xState v5 machine config — Stately Studio + devtools
//   • SCXML — W3C interop

// Same flow shape, three authoring surfaces.

// xState v5 (general purpose statechart):
createMachine({
  id: "shop.checkout",
  context: { userId: "", cartId: "", total: 0 },        // ← mutable
  initial: "loading",
  states: {
    loading: {
      invoke: {
        src: fromPromise(async ({ input }) => loadCart(input.id)),
        input: ({ context }) => ({ id: context.cartId }),
        onDone: { target: "pricing", actions: assign({...}) },
      },
    },
    // ... lots of mixing of definition + runtime concerns
  },
})

// FlowState (flow-focused subset + xFlow extensions):
defineFlowState({
  id: "shop.checkout",
  inputSchema:  z.object({...}),                        // ← schema-typed
  initial: "loading",
  states: {
    loading: {
      invoke: { action: "action:cart.load@^1" },        // ← symbolic ref
      on: { DONE: "pricing" },
    },
    // ... structural and addressable
  },
})

// What FlowState removes:
//   • context (mutable JS object)
//   • inline action functions (assign, raise, send, sendTo)
//   • after / always (delayed / eventless transitions) — express explicitly
//   • src as inline factory — only id@version refs

// What FlowState adds (xFlow-specific):
//   • action: id@version (registry-resolved + signed)
//   • inputSchema / outputSchema per state (zod or JSON Schema)
//   • placement / claim / exposure declarations
//   • idempotencyKey on action invocations