cx-platform-flow

workflow; its CLI verbs stay in the binary

Why reach for it

A workflow is an ordinary CX document. cx-platform-flow validates, simulates and runs a flow: steps with acts named by qualified name, a pivot after which nothing is undone, compensation for what came before it, and a run record that is a journal of transitions rather than a status field. We run this site's own documentation pipeline through it.

The document is the whole contract. validate answers the closed set of vocabulary words the flow uses and the address every act resolved to, so a reader knows what they must know and nothing else. The runner law is pure — given the document, the folded record and one event it yields the transitions to append and at most one side effect — which is what makes simulate the same function as advance: a dry run over a supplied result table is provably what the live run will do.

Every step contributes two transitions, :running when its act goes in flight and its outcome after, so a crashed advancer's record says exactly where it stopped and a racing one appends nothing. The record is read, never assembled: what the run reached is a fold over its own transitions. The documentation flow that generates, checks and assembles this site is one such document, docs-src/flow/docs.flow.cx, run by make docs — a generate pivot, then every check, then the assembled site, each failed target named in the record.

What it gives you

One module, cx-platform/flow: validate, simulate, run and the record readers. Its CLI verbs stay in the binary — cx flow validate, cx flow simulate, cx flow run — so a flow document is checked from the shell before any act exists.

module	import it as	where it lives	reference
`flow`	`[?lib 'cx-platform/flow']`	Ring 1 · the platform group	flow reference

Try it

A checkout flow validated against a resolver: the answer carries the flow's content address, its step count, the exact vocabulary words the document uses, and the address each act resolved to.

input.cx

        [flow name="checkout" stall-after=2d
  [args [sku::string] [qty::int] [acct::string] [order::string] [amount::decimal]]
  [step name="reserve-inventory"
        [do 'inventory/reserve' [sku $args/sku] [qty $args/qty]]]
  [step name="authorize-payment"
        [do 'payments/authorize' [acct $args/acct] [amount $args/amount]]]
  [step name="approve-large" when="$args[> $_/amount 10000]" deadline=1d
        [do 'orders/approve' [order $args/order] [amount $args/amount]]]
  [step name="place-order" pivot=true
        [do 'orders/place' [order $args/order]]]
  [step name="arrange-shipping" deadline=4h
        [do 'logistics/arrange' [order $args/order]]]
  [step name="notify" [do 'notify/send' [order $args/order]]]]

prog.cx

        [?lib 'cx-platform/flow']
[?let [= $e [resolver
  [act name='inventory/reserve'  resolved='sha2-256:11' compensates='inventory/release']
  [act name='payments/authorize' resolved='sha2-256:22' compensates='payments/void']
  [act name='orders/approve'     resolved='sha2-256:33' compensates='orders/unapprove']
  [act name='orders/place'       resolved='sha2-256:44']
  [act name='logistics/arrange'  resolved='sha2-256:55']
  [act name='notify/send'        resolved='sha2-256:66']]]
  [$flow:validate $doc $e]]

        $ cx --data=input.cx prog.cx
[valid flow=sha2-256:d471bf2ce3ea3a8024780cb3af7c0a697f1d0fc53a86a50de07c80b255c93d4c steps=6 words='flow step pivot when deadline' [act name='inventory/reserve' resolved='sha2-256:11'] [act name='payments/authorize' resolved='sha2-256:22'] [act name='orders/approve' resolved='sha2-256:33'] [act name='orders/place' resolved='sha2-256:44'] [act name='logistics/arrange' resolved='sha2-256:55'] [act name='notify/send' resolved='sha2-256:66']]

Fixture flow-001-validate-checkout in deps/cx-platform-flow/conformance/platform/flow.cxd — replayed against this cx when the page was built.

Status

The workflow repository ships as a package: its module is bundled into the platform build from the pin, and its specification and corpus live with it.

fact	as the registry records it
ships as	`package`
status	extracted
pinned at	`44f9a4546`
builds on	cx-core-code, cx-platform-store
built on by	cx-platform-ux
bundled modules	1

Fig. — what cx-platform-flow plugs into: the repositories it builds on (left), the modules it ships (centre), the repositories that build on it (right) · drawn from registry/repos.cxd, deps.cxd and registry/modules.cxd when this page was built

cx-platform-flow

Why reach for it

What it gives you

Try it

Status

Links