V40, circuit instances: Spray's diagram, run as data

September 29, 2026 · ALA · V40 · LiveView · circuit

John Spray’s ALA applications are diagrams: instances of abstractions with ports, and wires between the ports. The application layer is the diagram, and the code that runs it is generated or trivial. V40 asks what that looks like when a LiveView page is built that way at full size, with the same requirements as V39: a storefront cart with tabs, undo, promo, shipping, gift wrap, a checkout flow with an async payment, live stock, and a B2B portal with volume pricing and a PO form.

Everything is a Step

One protocol, Ports.Step, is the port: push {input, payload} in, get {:emit, [{port, payload}], step} or {:quiet, step} back. Features implement it through an Adapter that turns V39’s plain {state, outputs} functions into steps, so the feature modules are the same as V39’s and still import no Phoenix. Sinks implement it directly: ToStream, ToAssign, ToFlash, ToStore, ToTimer, ToPatch, ToAsync, ToRedirect, ToComponent, plus FromStore as a source and Via as a transform. A Circuit holds named parts and wires from {instance, port} to {instance, input}; pushing into one part delivers along the wires and returns whatever reaches an unwired port.

The page builds its circuit at mount:

Circuit.new(
  lines: %FromStore{read: &Carts.list_items/1},
  cart: Adapter.new(Cart, Cart.new(cart_id: cart_id, pricing: @pricing)),
  undo: Adapter.new(Undo, Undo.new([])),
  cart_rows: %ToComponent{module: CartPanel, id: "cart"},
  undo_clock: %ToTimer{name: :undo, ms: @undo_window_ms, into: {:undo, :expire}},
  restored_notice: %ToFlash{text: "Item restored"},
  charge: %ToAsync{name: :payment, fun: &charge/1, ok: {:checkout, :succeeded}, error: {:checkout, :failed}},
  ...
)
|> Circuit.wire({:lines, :loaded}, {:cart, :load})
|> Circuit.wire({:cart, :removed}, {:undo, :capture})
|> Circuit.wire({:undo, :restored}, {:cart, :receive})
|> Circuit.wire({:undo, :restored}, {:restored_notice, :any})

Loading is a wire like any other: mount pushes {:load, cart_id} into the store source and the rows travel to the cart and on to the component without the page ever holding them. Timers and async jobs come back as {:feed, instance, data} messages that a 62-line Runner returns to the circuit, so the page has one handle_info clause for all of them.

Components own their events

The cart rows, the saved and wishlist tabs, the checkout form and the portal panels are LiveComponents with phx-target={@myself}. A click is a push into a named input, Emitter.feed(socket, :cart, {:remove, %{item_id: id}}), delivered to the page process that holds the circuit. CartPage has no handle_event at all. Where a feature needs another’s data, the composition is a wire: the cart emits checkout_requested with its aggregate, and the circuit carries it into checkout.pay. The page never touches a value, which is the property Spray’s §1.6.4 describes and the linter’s handling-data check measures.

What it costs

The honest part. A click is two message hops: component to page, circuit to component. The tests settle a page with two renders after each action and poll for async results. The cart circuit names 38 instances and 41 wires; every flash text is an instance with a name, which is what makes the wiring read as a diagram and also what makes it long. And the vocabulary of sinks is a thing to learn, the same way V39’s binding kinds are, though here adding a kind is a new small module rather than a new clause.

One shortcut I would undo: a controls component is rendered twice, once for the tabs and once for the totals, so that one module owns all of the cart’s non-row events. It is really two components sharing a module, and it should be split.

What the linter said

ala_lint scores V40 at 98 by default, 97 under --strict and 95 under --super-strict (re-scored 2026-09-30), level with V39. Its handlers don’t branch or compute, and the linter no longer counts the one connected? guard V39 also carried. The three R11 findings it does report are in the page’s private helpers, which the circuit calls: finalize/2 loops over the order’s lines to decrement stock, and add_line/2 (with the portal’s ensure_line/2) passes a product read straight into a cart write. That’s store work that belongs in a domain abstraction, not in the page; the linter only started seeing it on 2026-09-30. The findings that remain are shared with V39: the shipping table repeated across pages, the domain aggregate read by three features, V35’s product pages. The linter cannot see the two hops, and it cannot see the doubled component. That gap between what the tool scores and what the design costs is the reason V39 and V40 exist side by side.

Re-scored 2026-10-01 with the template-aware linter and a layer map that covers every module (the product pages and paradigms were outside the earlier one): 96 by default, 95 under --strict, 84 under --super-strict. The new R11 findings (34 in all) are comparisons and loops in its UI components’ and product pages’ markup, and R3 now counts their words.

The full checklist, by hand

Walked through every rule of the ALA Checklist with an explicit deduction per finding (the method from the V42 post), V40 scores 86, the lowest of the four circuit-and-component variants. Its page helpers do store work (−2), and the page makes the payment call (−1). UI instances feed circuit inputs from inside their components, outside the circuit (−2). Five closures hide what their instances do (−1), and a misnamed output is dropped silently at the circuit’s edge (−1). A click takes two message hops (−1). Smaller items and the findings the family shares (a baked threshold, the rate table written twice, the shared aggregate) make up the rest. V42 is V40 with most of these fixed, and scores 90.

Rescored 2026-10-01: 81. Later walks found findings this one missed, in code V40 shares with the other storefronts. The line-item builder writes the currency "usd" in the domain (R3, −1). Words sit below the composition: the row components hold their labels, the forms’ validation messages live in the features, and the cart feature builds “free over $50.00” (R3, structural, −2). The page says “Gift wrap ($2.99)” beside its configured fee of 299 (R5, −0.5). And the markup decides more than the tab comparison already counted: comparisons, ifs and loops in the UI components and product pages (R11, −1.5). 85.5 becomes 80.5, which rounds to 81.

Rescored 2026-10-02: 79. Two of Spray’s statements are now read strictly. A page-specific LiveComponent is a contained sub-component. Spray has “no analog of a sub-module or sub-component, no such thing as a sub-abstraction” (§2.2), and his provision for page-specific UI is layout and bindings built from domain UI abstractions (§7.14). V40 has nine: the generated FormComponent and eight circuit panels in instances.ex (CartPanel, CheckoutForm, PoForm and the rest), each a LiveComponent with its own handlers and markup that only its page uses (R11, structural, −2). And Spray’s features are compositions: “Each feature creates instances of domain abstractions, configures the instances with feature specific details, and connects them together” (§2.2). The modules this variant calls Features are coded state and rules, which he would call stateful domain abstractions, so the name misleads a reader who knows his vocabulary (R8 “should”, −0.5). 81 becomes 78.5, which rounds to 79. The linter now reports each of the nine as subcomponent, scored by --strict: 95 becomes 92.

Rescored 2026-10-03: 77. Spray’s §6.17.2 is now read strictly under R10. Checkout receives the whole cart (%Cart{}) to use three facts of it; the checklist already named that as missing R10, and every walk had passed it (−1). And the storefront’s cart, which carries promo, gift-wrap and shipping state, is the struct the portal’s order lines are built on: one use case’s data in a struct another use case shares, which Spray says an identity “should not be used as the carrier of” (−1). 78.5 becomes 76.5, which rounds to 77. Lint under --strict is 91, meeting 5 of 10 rules: the linter now scores the shared aggregate from --strict up.

The code is in ala_variants_elixir/v40-circuit-instances.

← all posts