V42, typed circuit: the diagram declared, checked, and drawn
V40 is the most literal Spray shape in this project: each page builds a circuit of feature instances and sinks at mount, and nothing on the page decides anything. It left three things implicit. A wire could name a port that didn’t exist, and the circuit would quietly drop what flowed into it. An output nobody wired simply vanished. And the circuit was 38 instances and 41 wires of Elixir inside a 294-line page, so you could read it but not see it.
V42 is V40 with those three made explicit. It came out of gathering Spray’s remarks on functional programming for the ALA Checklist, and it answers one question: can the diagram be the source of truth, checked and drawn, without code generation and without hiding anything from the compiler or the linter?
What Spray asks of the wiring
Three of his points drive the design.
- The wiring is explicit, and in one place. Dependency injection in ALA “must be explicit. It must be specified in cohesive user story abstraction in a higher layer” (§3.11.3).
- The diagram is the source. Spray keeps generated wiring code apart from the diagram “because it is not source code” (§2.5.1), and treats the diagram as what you design and read (§3.6).
- Explicit structures beat hidden ones. His objection to monads is that their code “builds large object structures full of delegate objects, closure objects and other objects ‘under the covers’”, which “makes monads difficult to understand, trace and debug” (§3.11.3). He also keeps creating an instance separate from wiring it, because “Explicit WireIn and WireTo operators allow us to directly translate a diagram to code” (§6.2.2).
V40 already met the first. V42 goes after the other two.
Ports that declare their type
The Step protocol every instance speaks gained two functions. ports/1 declares the instance’s inputs and outputs, each with a paradigm type. feeds/1 lists the places a timer or an async job will push back into later. A feature declares its ports as data, next to the functions they name:
def ports,
do: %{
in: [capture: :item, restore: :event, expire: :item_id],
out: [captured: :item, timer: :timer, restored: :item, expired: :item_id]
}
The adapter that turns a plain feature module into an instance reports those ports, and each sink declares its own (ToFlash takes show: :any, ToForm takes value: :changeset).
A circuit that checks itself
Circuit.validate!/1 runs in each page’s mount/3, and in a test. It raises if:
- a wire names an instance or a port that doesn’t exist;
- a wire joins two different types (
cart.summary (summary) -> undo.capture (item)); - an output is neither wired nor explicitly grounded with
Circuit.ground/2; - a timer or async job feeds back into an input the target doesn’t declare;
- any instance is configured with an anonymous function.
The test seeds each of those mistakes into the real cart diagram and checks it’s caught. In V40, all five were silent: the circuit would drop the payload at its edge, and the runner would ignore it.
Both diagrams passed validation the first time they ran. I had expected a few findings from 60-odd instances, and there weren’t any. That’s partly because V40’s wiring was careful, and partly because V40’s tests already exercised most wires. The value of validate!/1 is less in what it found here than in what it will catch the next time someone rewires a page.
The diagram is a module, and a drawing
Each page’s circuit moved into its own module, CartDiagram or PortalDiagram, with the store’s literals beside it: shipping rates, promo codes, the undo window, the checkout flow, every flash message. It’s still Elixir, and deliberately so. A diagram held as data tuples would hide its storage calls from the compiler and from ala_lint; this one uses only real module references and named captures:
place_order: %PlaceOrder{
orders: Orders,
carts: Carts,
products: Products,
announce: &Broadcast.stock_changed/2,
cart_id: cart_id
},
mix circuit.draw renders each diagram to Mermaid under docs/diagrams/. A box is labelled with its kind and the configuration a reader needs; a named capture is labelled through Function.info/1 (Carts.list_items/1); a wire is an arrow labelled with its ports. A test fails when a committed drawing no longer matches the diagram, so the drawing is always the circuit that runs. That’s V30’s “the diagram is the source” without V30’s generator: nothing is generated, so nothing can drift. The cart page itself shrank from 294 lines to 140, and the portal from 163 to 62. What remains is framework glue: mount the checked circuit, turn a URL into a step, pass messages to the runner, and render.
No closures, so no hidden calls
V40 configured five instances with closures, such as &add_line(cart_id, &1) and fn _ -> Products.list() end. A closure prints as a generated name, so neither a reader nor a drawing can tell what it does, and the page helpers behind them were doing store work: finalize/2 placed the order, looped over the lines to take stock, and broadcast each change. Since the linter learned to see that loop, it scored V40’s page three R11 findings under --super-strict.
In V42 that work lives in two domain abstractions, PlaceOrder and AddLine, which do their own I/O through the stores they’re configured with. That’s Spray’s placement: his Display writes to the screen itself. Both also implement Step, so they sit in the circuit as instances. Every function left in a circuit is a named capture, which validate!/1 enforces.
What it scored, and what it cost
| V40 | V41 (revised) | V42 | |
|---|---|---|---|
ala_lint default / --strict / --super-strict | 98 / 97 / 95 | 98 / 97 / 97 | 98 / 97 / 97 |
R11 findings (--super-strict) | 3 | 0 | 0 |
| Re-scored 2026-10-01 (templates read, every module mapped) | 96 / 95 / 84 | 95 / 94 / 89 | 95 / 95 / 87 |
| R11 findings, 2026-10-01 | 34 | 16 | 28 |
Lines in lib/ | 4,464 | 4,503 | 4,913 |
| Cart page lines | 294 | 261 | 140 (plus a 169-line diagram) |
| Wiring checked at build time | no | a test that every announcement is routed | ports, types, unused outputs, feedback targets, closures |
| Familiarity | 2 of 5 | 5 of 5 | 2 of 5 |
V42’s layer map adds the two diagram modules to the application layer, since that’s what they are; without that, their literals count as sitting below the composition.
The super-strict gain is exactly V40’s three R11 findings, gone with the page helpers. The 2026-10-01 linter also reads templates, and finds comparisons and loops in both circuits’ component markup; the page helpers are still part of the difference between them. The linter can’t see the rest of what V42 adds: the type checks, the drawing, the missing closures. The cost is about 450 lines, most of them reusable paradigm code (about 80 for validation, 60 for the drawing, 40 for port declarations on the sinks), and more vocabulary. A reader now meets port types, grounds and feeds on top of V40’s circuit, sinks and runner. A click still takes the same two message hops it took in V40.
One gap validation can’t close: a UI instance (a LiveComponent) feeds a named input of the circuit from inside the component, as Emitter.feed(socket, :cart, {:remove, ...}). That call sits outside the circuit value, so a typo there is found only when the event fires.
The full checklist, by hand
I also walked V42 through the whole ALA Checklist by hand, rule by rule, with an explicit deduction for each finding. It scores 90. Every “must” in R1, R2, R4, R6 and R9 holds, and so does R11 for the modules the linter reads. The points go on what the linter can’t see:
- The wiring the diagram doesn’t hold (R8, −2). UI instances feed circuit inputs from inside their components, 17 calls in all, so part of what a click does is outside the diagram, the drawing and the checks.
- The payment call in the page (R11, −1).
CartPage.charge/1builds the return URLs and calls the gateway. It’s the same shape as the page helpers V42 removed, and it has no branch, so the linter can’t see it. - Literals (R3, −2.5). The low-stock threshold is baked into a domain rule, the shipping table is written in both diagrams, and V35’s product pages still hold a number.
- The shared cart aggregate (R10, −1). Checkout reads the aggregate’s fields instead of calling its functions.
- Smaller items. A session key repeated as a string (R5); two pass-throughs, twelve sink kinds and a controls component rendered twice (R7); three outputs that read as operations (R9’s “should”); a component handing its summary to checkout, and tab visibility decided by comparisons in the template (R11); and two message hops per click.
I then reassessed V39, V40 and V41 the same way, replacing the one-pass scores their posts first showed. The order changes. Revised V41 scored 92: it has no page helpers and no closures, and only cross-feature effects take a hop. V42 scored 90. V39 scored 88 and V40 86, both held down by store work in page helpers. (Rescored 2026-10-01: later walks found findings these missed, in code the storefront variants share: a currency code in the domain, words below the page, a label restating a fee, and logic in templates. V41 is now 90 and V39 82. V42 and V40 carry most of the same code; rescored the same way, V42 is 85 and V40 81.) V40 has every finding V42 still has, plus the page helpers, closures, silently dropped outputs and per-call configuration V42 removed. The checklist rewards what a page doesn’t do, not the machinery that checks its wiring, so V42’s validation and drawing earn back only what V40 lost to silent drops and closures.
Rescored 2026-10-01: 85. Later walks found findings this one missed, in code V42 shares with the other storefronts. The line-item builder writes the currency "usd" in the domain (R3, −1). 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 (R5, −0.5). And the components’ and product pages’ markup compares and loops beyond the tab comparison already counted (R11, −1.5). 89.5 becomes 84.5, which rounds to 85.
Rescored 2026-10-02: 83. 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). V42 has V40’s nine: the generated FormComponent and eight page-specific circuit panels (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). 85 becomes 82.5, which rounds to 83. Lint under --strict went from 95 to 92 with the nine subcomponent findings, then to 94 when the same day’s linter stopped counting interpolated text in the bottom layer (the circuit’s drawing labels and messages) as product words, which removed five R3 findings.
Rescored 2026-10-03: 81. 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). 82.5 becomes 80.5, which rounds to 81. Lint under --strict is 93, meeting 5 of 10 rules: the linter now scores the shared aggregate from --strict up.
When to reach for it
V42 is the strict reference, not the team default. If you want the wiring checked and drawn, and your team will learn a circuit, this is the most complete version of Spray’s diagram in the project. If you want the highest score in a shape Phoenix developers already write, revised V41 scores the same on the linter at familiarity 5, and its route-coverage test gives some of the same safety.
The code is in ala_variants_elixir/v42-typed-circuit.