A field guide: which technique solves which checklist rule

September 24, 2026 · ALA · checklist · techniques · LiveView

Updated 2026-10-29: the ports-free form of the live subscription (V57’s ChangeFeed) under R1. Updated 2026-10-21: the live subscription port (ChangeFeed) under R1 and in the LiveView table. Updated 2026-10-02: the wiring forms of every variant side by side (under R8), the techniques the max variants used to reach the top of the full walk, Spray’s definition of features, and the stricter reading of page-specific LiveComponents (under R11). Updated 2026-09-30. The ALA Checklist was revised rule by rule against John Spray’s site, and this guide follows the revised rules. The checklist now carries every technique below under its rule, so it works as a reference on its own; this post is the tour. The 2026-09-30 update adds two “should” items (R6’s tramp parameters and R9’s configure-once) and the techniques that come out of Spray’s remarks on functional programming. Section numbers like §3.8 refer to his site.

The variants in this project were whole designs, each answering “what should an ALA LiveView app look like?” from scratch. But if you already have an app and you are iterating it toward ALA, you almost never want a whole variant. You want the one move that clears the one finding in front of you: the linter flagged a peer call, or a literal in the wrong layer, or a struct two features share. So the useful residue of twenty-odd experiments is not the designs. It is a catalog of techniques, each of which pays down one or two rules of the ALA Checklist.

This is that cross-reference, rule by rule. Most techniques help more than one rule, so a few appear twice. Where a technique came from a specific variant I have named it. Where it hasn’t been tried in a variant yet, I say so: several came out of working the thermometer through Spray’s later steps (the thermometer grows up) and are sketched and run there, but not yet used in a full app. Treat all of these as ingredients, not recipes. Each has a small Elixir sketch, the shape rather than runnable code.

R1: every edge between abstractions drops to a lower layer

This is the rule everything else serves, and it has the most techniques. It’s defined by layer: a call from one abstraction into another must land in a lower layer, and calls inside one abstraction aren’t edges (§2.1.3, §3.4).

Emit an outcome instead of calling a peer. A feature returns a description of what happened, or what should happen, rather than calling the sibling that should act on it (V10’s and V36’s typed outcomes, V14’s signals, V35’s typed facts). The sideways call never exists. It’s the most effective structural move for R1, because it removes the temptation rather than policing it. What the outcome may say, and what it may not name, is R9’s business, covered below.

# Wishlist doesn't call Cart; it reports what happened.
def remove(%Wishlist{} = wl, id), do: {drop(wl, id), [{:wishlist_removed, id}]}

Wire cross-feature work in one place. V26, V28, and V36 put every join between features in the composition, a handle/3 clause whose job is wiring. Features stay ignorant of each other, and the one module allowed to know both does the connecting. Spray’s version: “features can also have ports and be wired together” by the application (§2.2).

# only the composition names two features:
def handle(:remove_item, %{id: id}, page) do
  {cart, removed} = Cart.remove(page.cart, id)
  %{page | cart: cart, recent: RecentlyViewed.record(page.recent, removed.product)}
end

Make the wiring declarative. V29’s manifest and V30’s committed codegen route one feature’s typed fact to another’s reaction through generated glue. The routing lives in a data table.

reactions: [{Cart.Facts.ItemRemoved, RecentlyViewed.Intents, :track_removed}]

Pass callbacks down; never let a receiver register itself. A function the composition passes down is a port, and it’s Spray’s legitimate way to call up the layers (§4.4.1). A module that subscribes itself to a topic, or registers with a sender, is a peer edge in disguise (§4.4.2). The page’s mount/3 does the subscribing and routes messages on. (V30, V33–V35, and V38 already subscribe in the page’s mount/3, through a small Broadcast wrapper; making it a rule is new.)

def mount(_params, _session, socket) do
  if connected?(socket), do: Phoenix.PubSub.subscribe(MyApp.PubSub, "stock")   # the page subscribes
  {:ok, socket}
end

When pages must show changes made elsewhere, make the subscription a part. Added 2026-10-21. A page that subscribes and then writes a handle_info clause per kind of message grows a clause for every new kind of outside change, and misses whatever nobody wrote a clause for. The checklist’s live subscription port makes outside change a programming paradigm (§2.2): a part the page mounts, configured with a topic and the facts it wants, and wired to the parts that care like any other output. A publish side of the same paradigm takes the change from the composition that makes it. What travels is a fact keyed by identity, never rendered rows, and the observer stays inside the paradigm, where “the subscriber does not know the publisher” (§4.4.2). The topic is a symbolic connection (§4.7.4), so it is named once and passed to both ends. It is built as ChangeFeed in V50, V51 and V51B, and in the Ruby variants V05 to V07, and moving onto it found the same gap in all six: a staff stock edit at /products never reached an open cart or portal. How close can a LiveView app come to ideal ALA? explains why it isn’t LiveView.

|> ChangeFeed.mount([topic: Catalog.changes_topic(), facts: [:stock]], out(:feed))   # V51B's portal
defp wire(s, :feed, {:stock, change}),
  do: s |> to(:edit_lines, :stock, change) |> to(:catalog, :stock, change)

Without ports, when the page calls its parts. Added 2026-10-29. In light ALA, where a page calls its parts instead of wiring them, the same idea needs no ports. V57 builds it as a 39-line GoodDeal.ChangeFeed in the platform layer. A context publishes a fact once its change has committed (a kind, the identity it is about, the values that changed), and a page declares once, in mount, which kinds it listens to and what each does. Each kind is its own topic, so a page receives only the kinds it named, and a hook dispatches each fact to its handler, so the page writes no handle_info clause per message.

ChangeFeed.publish(:price, product.id, %{amount: product.amount})   # Catalog.update_product, after commit (simplified: V57 loops over the kinds that changed)

socket
|> ChangeFeed.subscribe(%{price: &refresh_product/2, stock: &refresh_product/2,
                          product_removed: &reload_rows/2})          # V57's cart, in mount

Measured over the ten-change sequence, against the same app without it (form 1c), it cost 3% more and made one change cheaper, live prices (S10), because a price fact was one more entry in each page’s map. It reached no page that the app’s plain product broadcast did not already reach, and the one defect it carried came from a page that declared too few kinds (a checkout that did not listen for deletions). So the light form earns its keep where pages hand-build their own channels, and adds little where the framework already broadcasts every change. Name the kinds a page must hear in its tests as well as its map.

a custom Credo check that fails the build on an upward or cross-peer call. ala_lint’s R1 check does the same given a layer map, including domain → domain calls. Neither prevents the coupling, but both catch it the moment it appears.

mix ala.lint --layers-module MyApp.AlaLayers --min-score 90

R2: wires meet only at the top

Give each feature a private struct. V24’s isolated capsules and V26’s and V36’s per-feature structs leave no shared mutable thing for two peers to fight over. Immutability does the rest.

defmodule Wishlist do
  defstruct products: []   # only Wishlist reads or writes this
end

Keep one source of truth and derive the rest. V13’s reactive split (source fields, with derived fields recomputed from them) kills the classic bug where a handler updates items but forgets total.

def total(%Cart{items: items}), do: Enum.reduce(items, 0, &(&1.amount + &2))

Let the composition supply cross-slot values. V35’s composed inputs is the sharpest R2 move. A feature that needs a sibling’s data doesn’t read the shared session slot. The composition reads it and passes the value in, and a detector flags any session.<peer_slot> access.

def pay(session, stock_levels), do: ...   # the composition resolved stock_levels

Turn a value everything touches into an abstraction one layer down. A wire joining many ports is Spray’s “ground symbol” smell: “a new abstraction may be waiting to be discovered” (§3.6.1). His example is a game score most instances interact with. Rather than wiring every feature to it, make it a domain abstraction they depend on as knowledge. Not tried in a variant yet.

R3: application literals live at the composition

Put the store’s constants in one place at the top. V34’s manifest holds calibration per feature, V36 keeps it in a @pricing attribute on the composition, and V38 uses a GoodDeal.Catalog module.

defmodule GoodDeal.Catalog do
  def shipping_rates, do: %{standard: 500, express: 1500}
  def gift_wrap_cents, do: 299
end

Make the domain take calibration as configuration. The abstractions below take the constants from the composition, so they hold no store-specific number and drop into a different product unchanged. Pass them once, as a configuration value, rather than mixed into each call’s data (R9’s configure-once “should”, below).

def cost(%{rates: rates}, method, subtotal), do: ...   # config first, set by the composition

Compute a derived value once, instead of threading the literal. V38’s low-stock threshold was used seven times in a template as a display helper. Instead of passing the bare number through all seven calls, the status is computed once from the configured threshold and flows down as data, which also made the badge components pure.

Pass rules in as predicates. A requirement like “free shipping over $100” can be a function the page passes to a generic abstraction, the way Spray writes new Filter(x => x>=0) (§3.11.3). The rule is stated once, at the top, and a generic abstraction runs it. Not tried in a variant yet.

Shipping.new(free_when: &(&1.subtotal >= 10_000))

Watch for words and codes that look like data. Three kinds slipped past earlier walks of the storefront variants. A feature built the text “free over $50.00” from each shipping rate. The address and PO forms wrote their validation messages in the features’ schemas. A line-item builder wrote the currency "usd". Each is an application literal below the composition. The max variants project the values instead (cost and free_above as money), take the form’s messages as configuration, and build the builder once with its currency. A fourth kind is R5’s: a label like “Gift wrap ($2.99)” that restates a configured fee goes stale when the fee changes, so build it from the same attribute.

Supply every word from the page as a map. The page holds its words in one @texts map, merges in the words the store shares, and passes each component or panel its part as an attribute (t). Components render only what they’re given. Used by all three max variants.

@texts %{cart: %{discount: "Discount", row: %{save: "Save for later", each: " each"}}}
defp texts, do: update_in(@texts, [:cart], &Map.merge(&1, StoreConfig.summary_texts()))

<.cart_item_row row={row} t={@texts.cart.row} ... />   <%!-- the row shows @t.save, never a literal --%>

Give forms their messages as configuration. A feature’s embedded schema validates, but the words of the error come from the page. V41-max and V39-max pass messages when they build Checkout and PortalSubmit.

def changeset(address, params, messages) do
  address |> cast(params, @fields) |> validate_format(:postal_code, ~r/^\d{4,10}$/, message: messages.postal_code)
end

Checkout.new(flow: @flow, messages: %{postal_code: "must be 4–10 digits"}, ...)

Project values, not words. A feature returns the amounts a sentence needs, and the component writes the sentence with the page’s words. The max variants replaced a price_label the Cart feature built (“free over $50.00”) with money values.

# feature: values only
%{method: rate.method, label: rate.label, cost: Money.new(rate.cost),
  free_above: rate.free_above && Money.new(rate.free_above)}

# component: the page's words
{opt.cost}<span :if={opt.free_above}> ({@t.free_over} {opt.free_above})</span>

Keep store-wide literals in one application module. Rates, thresholds, currency and the words several pages share live in one module in the application layer that both pages read (V41-max and V39-max’s StoreConfig, V38’s GoodDeal.Catalog). Domain modules never read it; pages pass its values down.

defmodule ZeroCoupledWeb.StoreConfig do
  def rates, do: %{standard: %{label: "Standard (5–7 days)", cost: 599, free_above: 5000}, ...}
  def low_stock_at, do: 5
  def currency, do: "usd"
  def summary_texts, do: %{items: "Items", subtotal: "Subtotal", total: "Total", free: "Free"}
end

R4: state lives with its owner, not hidden

Write a functional core over owned state. V10’s typed TEA, V36, and V38 keep feature logic as pure functions over the feature’s own struct. The module that owns the state is the only one that reads or changes it; callers store the new struct back without looking inside. Spray’s reason: state that is part of a concept belongs with that concept (§3.9, §3.11.2).

def add(%Cart{} = cart, item), do: %{cart | items: [item | cart.items]}

Partition state by owner. V9’s split of the page struct into CartState, UIState, and CheckoutState makes each piece of state visibly belong to one concept.

defstruct cart: %CartState{}, ui: %UIState{}, checkout: %CheckoutState{}

Let the composition value carry step state. When the page builds a program from stages (see “Past the pipe” below), each stage’s memory lives inside its own struct, and the runner stores the updated program. The page holds one opaque value and never names a stage’s state. Run in the thermometer post, not tried in a variant.

Give unowned state its own abstraction. State that belongs to no concept becomes Spray’s State<T>: an abstraction with input and output ports, wired in like any other (§3.9). Not tried in a variant yet.

R5: no silent contracts

A silent contract is an agreement two modules share that appears in neither’s signature: a magic string, a tuple shape, a session key. Spray’s rule is that “no two modules know the meaning of data or a message” (§7.8).

Keep the meaning in the composition. Spray’s first fix: both ends take the name or format as configuration from the page, so only the page knows they agree.

Display.new(format: "#.#")   # the page chose the format; the formatter and display never agree on it

Type your effects. V10’s and V36’s outcome constructors turn “return {:flash, :info, msg} and hope the other side matches” into Outcome.flash(:info, msg), where a typo is a compile error.

Outcome.flash(:info, "Order placed")

Declare names once, and keep them in the page. V35’s Contracts module holds every event, stream, and hook name, so a rename happens in one file. V38 does the same with tiny single-source modules (CartSession for a session key). The revised checklist adds a caution. A names module used only by the page (its HEEx, handlers, and JS hooks) is fine. Once features use it to agree with each other, it becomes a registry of global names, which Spray calls “symbolic wirings” (§4.7.4). V35’s features do call Contracts.stream_name/1, which is worth a second look.

defmodule Web.Contracts do
  def stream_name(:cart), do: "cart-items"
end

Make both ends one abstraction. When a sender and a receiver must share a format, Spray’s second fix is that “they are two instances of the one abstraction” (§7.8). One module owns both the encoding and the decoding. Not tried in a variant yet.

defmodule StockMessage do
  def encode(id, count), do: %{"id" => id, "n" => count}
  def decode(%{"id" => id, "n" => n}), do: {id, n}
end

Check the places signatures can’t reach. V32’s component-purity checker looks inside HEEx templates, where a phx-click="save" string is a contract the compiler never sees.

Derive a label from the value it states. A label that quotes a configured number is built from the same attribute, so changing the fee can’t leave the label stale (V41-max, V39-max).

@gift_wrap_unit 299
put_in(texts, [:cart, :gift_wrap_label], "Gift wrap (#{Money.new(@gift_wrap_unit)})")

State a domain constant once, and ask for it. When a rule’s constant (“a line can’t go below 1”) is needed in two places, the module that owns the rule answers the question instead of the other repeating the number (V38-max’s first version, in Lines).

@minimum 1
def update_quantity(items, id, delta), do: ... max(@minimum, item.quantity + delta) ...
def at_minimum?(%{quantity: q}), do: q <= @minimum     # the Cart feature's row asks this

Not every duplicated string is a contract, which is why R5 still needs a reader. A ~p"/cart" route is checked by the router at compile time. And V38 found "products" used as a PubSub topic in one place and an Ecto table name in another: two meanings that happen to share a spelling. Its one real silent contract was a session key written as an atom by a plug and read as a string by three LiveViews.

R6: every abstraction names a learnable concept

This one resists tooling; it’s mostly judgement. These habits help.

Slice by feature, and name the slice. V4’s feature slices, V23’s composable units, and V36’s one-module-per-feature all make you name the concept before you write it.

Name domain abstractions by their kind, not their use. OffsetAndScale, Boiler, LowPassFilter: each names what it is, so a reader learns it once. A good abstraction “separates the knowledge of different worlds” (§7.2.5).

Ask “what do you know about?” The answer should be one thing. Spray’s refinement: know “an operation on some data, or the meaning of some data, but not both” (§7.25). A module that defines what an order means and computes shipping on it knows two things.

Write the short moduledoc. Spray calls it “critically important” to document the concept, its ports, its configuration, and an example (§2.1.1). Two lines usually cover it.

@moduledoc "Smooths a stream of numbers. In: a number. Out: the smoothed number. Config: strength."

Should: don’t carry parameters you never read. This one is new, and it comes from Spray’s comparison of ALA with functional programming. When functions call down through several layers, “the middle layer functions end up with extra parameters that don’t have anything to do with them, just so they can pass state data through to even lower functions. This makes these intermediate functions not great abstractions in themselves” (§3.11.1). Elixir invites exactly this: threading opts, a context map, or a session down three calls is the path of least resistance. Each function in the middle ends up with a signature that knows what something further down needs.

# V35, simplified: pay/2 never reads stock_levels, and neither does Cart.check_ready/2
def pay(session, stock_levels), do: with(:ok <- Cart.check_ready(session.cart, stock_levels), do: ...)
def check_ready(%Cart{items: items}, stock_levels), do: CheckStock.call(items, stock_levels)

The fixes all move the knowledge back to the composition. Give the lower abstraction its input or configuration directly. Or configure the lower instance at the composition and pass that down, so the middle function uses an instance rather than carrying its raw inputs. Or make it a wire, as V40 does when Checkout takes its stock source as configuration. One hop isn’t the smell: a function handing its own input to the abstraction that processes it is just using that abstraction. Nor is a runner carrying a payload to a port, since carrying is its job.

It’s a “should”, not a “must”, because Spray offers it as a reason functions become poor abstractions, not as a constraint. ala_lint now reports it as an advisory tramp check that looks for two hops of carrying. Run over the published variants without layer maps, it finds four cases, all in V30 and V35 (the stock_levels pair above, and checkout form params carried through CheckoutFlow to Address). With their real layer maps it finds none, because Cart and CheckStock share a layer.

R7: every abstraction earns its existence

Carry the least machinery that works. V36 reaches strong compliance with almost no apparatus. When you find yourself adding a layer to hold a layer, that is the smell R7 names.

Let the linter catch proliferation. ala_lint’s pass-through and dead-code detectors flag the one-in, one-out forwarding function that adds a name and a hop but hides no decision.

def save(x), do: Repo.insert(x)   # 1-in/1-out, hides no decision: flagged

Mind both size bounds. Spray’s rule of thumb is 100 to 500 lines per abstraction, and averaging under 100 means “more abstractions than we need” (Summary). “Abstractness decreases with more ports” (§7.2.3), so a module with a long list of inputs is probably too specific.

Use what the standard library already names. Spray is blunt about monad libraries: “There would be no sense in reinventing that functionality as 2-port classes” (§6.3). In Elixir, don’t write Filter, Map, or Sort domain abstractions when Enum and Stream exist. If you need one as a step in a composition, write one generic step configured with the function. Not tried in a variant yet.

%Transform{fun: &Stream.filter(&1, fn row -> row.qty > 0 end)}

Don’t build wiring for an algorithm. “If your whole problem is just an algorithm, and therefore suits a functional programming style, then you can still compose abstractions with function abstractions, provided all function calls are knowledge dependencies” (§7.5). Pricing arithmetic that calls Money and a tax-rate function is fine as plain calls down the layers. Ports and runners are for where instances communicate.

Derive a declaration instead of restating it. A LiveComponent panel wires some of its feature’s outputs itself and sends the rest to the page as port outputs. Declaring only the ones it wires and deriving the sent list from the feature’s ports/0 means the two can’t drift (V41-max).

@wired_here [:rows]
def sent_port_outputs, do: Keyword.keys(Cart.ports().out) -- @wired_here

R8: the composition reads as the requirements

Clauses count as one place. Wiring written as function clauses in one module, whether handle_info clauses on a page or one wire/3 clause per port, meets R8: Spray asks that connections “belong in one place” (§3.3.1), and one module is one place. A wiring value (a map, a route table, a circuit) is a technique on top: it can be printed and checked by key, and it costs vocabulary.

Make the wiring a document. V29’s and V30’s manifest is the page’s requirements as data: which features, which reactions, which config. V33’s flows channel does the same for wizards.

page :cart, features: [Cart, Wishlist, Checkout], reactions: [...]

Keep the page legible. V36’s handle/3 clauses read top to bottom as the page’s behaviour, one clause per user action.

def handle(:remove_item, %{id: id}, page), do: Cart.remove(page, id)
def handle(:checkout, _args, page),        do: Checkout.start(page)

Wire with clauses, one per port. V38-max runs each feature step through a small runner that folds every output into the page’s own wire/3. Its storefront and portal pages have 44 clauses between them. The clauses, one per declared port and all in one place, are the wiring. There is no catch-all, so a missing wire crashes instead of vanishing, and a test reads the clause heads from the source and checks them against each feature’s declared ports. It needs nothing beyond Elixir. The cost is that the wiring is code a reader follows, not a value a tool can print.

defp wire(s, :cart, {:summary, summary}), do: assign(s, :summary, summary)
defp wire(s, :cart, {:checkout_requested, order}), do: run(s, :checkout, &Checkout.pay(&1, order))

Keep the composition inspectable. Spray prefers explicit wiring to monads partly because monad 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). A composition held as data (named structs plus a wire list) can be printed, diffed, and checked for unwired ports. One held as nested closures or a Stream can’t. He also keeps creating an instance separate from wiring it, so the code can follow the diagram line by line (§6.2.2).

Hold cross-component wiring in one route table. When feature instances are LiveComponents that send port outputs to the page, one map per page says where each one goes, and one handle_info clause applies it through a generic router with a few target kinds. Spray: connections “are typically cohesive, and belong in one place” (§3.3.1). V41-max; the cost is one hop per cross-feature effect.

@routes %{
  {:cart, :removed} => [pass: {Undo.Banner, "undo", :capture}],
  {:undo, :restored} => [pass: {Cart.Panel, "cart", :receive}, flash: {:info, "Item restored"}],
  {:checkout, :step} => [patch: @step_paths]
}
def handle_info({_, _, _} = port_output, socket),
  do: {:noreply, Instance.route(socket, @routes, port_output)}

Run clause wiring with a tiny runner. The clause-wiring technique above needs one generic function in the paradigm layer that runs a feature step, stores the new state, and folds each output through the page’s wire/3 (V38-max’s Steps: run, feed for a source’s answer, stream_change, patch, and a named timer, 56 lines).

def run(socket, key, step, wire) do
  {state, outputs} = step.(socket.assigns[key])
  Enum.reduce(outputs, assign(socket, key, state), &wire.(&2, key, &1))
end

Test that every port is wired. Each wiring form needs a coverage test, because an unwired output is lost or crashes only at run time. It’s one small test per page (or per wiring form), generated over the declared ports, not one test per port. V41-max sends every port output its panels declare to the page. V39-max checks its map’s keys against ports/0 and a grounded/0 list of ports deliberately left unbound. V38-max reads its clause heads from source.

# V39-max: every declared output is bound or grounded
for {key, feature} <- page.features(), port <- Keyword.keys(feature.ports().out),
    do: assert({key, port} in Map.keys(page.bindings(1)) ++ page.grounded())

# V38-max: collect wire/3 clause heads from the page source
Macro.prewalk(Code.string_to_quoted!(File.read!(@source)), [], fn
  {:defp, _, [{:wire, _, [_, key, {port, _}]} | _]} = n, acc -> {n, [{key, port} | acc]}
  n, acc -> {n, acc}
end)

Wait for async work in page tests. When a page starts a task (start_async), a test that reads the page right after the click is racing it. Use render_async/1, which waits for the page’s async results. V39-max’s payment-retry test passed or failed by timing until it did.

lv |> element("button", "Pay") |> render_click()
assert render_async(lv) =~ "Payment failed."

Name instances in the wiring instead of reading assigns. A clause that needs a configured instance names it, and the runner looks it up in one map the page builds at mount. No clause reads s.assigns, and a wrong name fails where it’s named (V45).

instances: %{add_line: %AddLine{carts: Carts, products: Products, cart_id: cart_id}, charge: %Charge{...}}

defp wire(s, :wishlist, {:taken, product}),
  do: Steps.feed(s, :cart, &Cart.receive/2, {:add_line, &AddLine.run/2}, product, &wire/3)

Make the coverage check one line, or a compile error. A paradigm-layer Wiring.gaps/1 reads a page’s source from its compile info and compares its clause heads with every port its features declare, so each page’s test is one line. use Wiring makes the same check while the page compiles; it’s optional, because a macro with definition hooks costs familiarity (V45).

assert Wiring.gaps(GoodDealWeb.CartLive.Show) == %{unwired: [], unknown: []}
# opt in: `use GoodDealWeb.Paradigms.Wiring` fails the build with
# "wire/3 wiring gaps in GoodDealWeb.CartLive.Show: %{unknown: [], unwired: [ui: :tab]}"

Type every port, and check the whole composition before it runs. V47 gives every port a type and refuses, at mount, a wire between two types, an output neither bound nor grounded, an unbound input, or an anonymous function. A Call instance declares the payload types it accepts and what each answers (AddLine turns a product into an item); a plain function’s answer type is written in its binding; sinks have types (a stream takes :row_change). V42 checked its flat circuit the same way.

{:via, &Carts.list_items/1, :items, [{:input, :cart, &Cart.load/2}]}
# refused at mount: "gappy: lines.summary (summary) → a stream takes row_change, not summary"

Draw the diagram from the value that runs. V47’s Diagram.mermaid/1 renders a page’s stories and the links between them, and mermaid_story/2 one story’s insides, from the composition the page mounts. The picture can’t drift from the code. A wiring value draws the same way: V39-max’s bindings map and V41-max’s route table each have a drawer. Wiring written as clauses draws by reading the page’s source: V48’s wire/3 clauses, V46’s page and story clauses, and V49’s handle_info and handle_async clauses. Those drawers depend on the shape the clauses are written in, so a test checks the edges that matter.

Let LiveView carry a store answer to a component. With plain clauses and no runner, a page that takes one abstraction’s answer and passes it to another is handling the data (§1.6.3). V49 starts the store work as a start_async task and sends the answer on from handle_async, so LiveView carries it.

def handle_info({:wishlist, :taken, product}, socket) do
  add_line = socket.assigns.instances.add_line
  {:noreply, start_async(socket, :add_line, fn -> AddLine.run(add_line, product) end)}
end

def handle_async(:add_line, {:ok, line}, socket) do
  send_update(Cart.Panel, id: "cart", receive: line)
  {:noreply, socket}
end

Fail loudly on an instance the page didn’t configure. V45’s runner looks a named instance up with instance!/2, which raises no configured instance :charge instead of calling nil somewhere deeper.

Bind every port in one map, run by a binder. V39 gives each page one map from {feature, port} to a list of bindings, and a generic Binder in the paradigm layer applies each kind: stream, assign, call, input, via, flash, and so on, thirteen in all. V39-max adds a paradigm protocol, Ports.Call, that the configured store-work instances implement, so a binding can name the instance instead of wrapping it in a function.

{:cart, :removed} => [{:input, :undo, &Undo.capture/2}],
{:wishlist, :taken} => [{:via, %AddLine{carts: Carts, products: Products, cart_id: id}, [{:input, :cart, &Cart.receive/2}]}]
defprotocol ZeroCoupled.Ports.Call do def call(instance, payload) end

Run the page as a circuit of instances and wires. V40 builds a value of named instances (features, transforms, and sinks such as an assign or a flash) plus a wire list, and a generic runner delivers outputs along the wires. It’s Spray’s diagram as data. V42 types every port, checks each wire and unused output when the page mounts, and draws the diagram from the value that runs.

circuit |> Circuit.wire({:order, :removed}, {:undo, :capture}) |> Circuit.wire({:order, :summary}, {:summary, :value})

Send port outputs from a component to the page. A feature LiveComponent wires some ports to itself (its @wired_here list) and sends the rest to the page as {name, port, payload} through a generic Instance.send_port_output/3. sent_port_outputs/0 lists them for the coverage test (V41, V41-max).

defp wire(s, {:summary, summary} = out), do: s |> assign(summary: summary) |> Instance.send_port_output(:cart, out)

Give a route table a few kinds of target. V41-max’s Instance.route/3 knows nine: pass (to another instance’s input by send_update), assign, flash, flash_by, patch, call (a store function or a named instance), feed (ask a named instance and pass the answer on), async (run a named instance in start_async) and redirect. The named instances sit in one instances map built at mount, as in V45.

{:wishlist, :taken} => [feed: {:add_line, &AddLine.run/2, {Cart.Panel, "cart", :receive}}, flash: {:info, "Added to cart"}],
{:checkout, :ready_to_pay} => [async: {:payment, :payment, &StartPayment.call/2}]

Wiring forms side by side

Every form below wires the same storefront. Hops are message hops per cross-feature effect, and familiarity runs from 1 to 5.

FormVariantsWhere the wiring livesHow it runsHopsCoverage checkFamiliarity
Manifest plus generated glueV30, V35a data file per pagegenerated, committed handlers0mix zc.gen --check fails on drift3
Handler clauses (handle/3)V36the page’s clausesa small shell folds outcomes0none5
Plain LiveView handlers, logic keptV38the page’s callbacksLiveView0none5
Bindings map plus binderV39, V39-maxone map per pagea generic Binder with binding kinds0V39-max: every port bound or grounded4, 3
Circuit of instances and wiresV40, V42a circuit value per page (V42: a diagram module)a generic circuit runner2V42: every wire and unused output at mount2
Feature LiveComponents plus handle_infoV41the panels’ own wires plus the page’s clausesLiveView, send_update2a test sends every port output5
Feature LiveComponents plus a route tableV41-maxthe panels’ @wired_here plus one @routes mapInstance.route/3, nine kinds1a test sends every port output4
wire/3 clauses plus a runnerV38-max, V45, V48, V50 (V50: no named instances, so familiarity 5)one clause per port in the pageSteps (V45: named @instances)0clause heads read from source (V45: Wiring.gaps/1, optional compile-time check)4
Generic host plus slots (unpublished toy)slot-split toythe page’s template and routesParadigms.Hosted runs any feature1as V41-max3
Story clausesV46each story’s wire/4, input/4, event/4; the page’s wire/3 between storiesStory (nests), Sinks0Wiring.gaps/1, story_gaps/1, event_clashes/13
Typed story mapsV47each story’s bindings map; the page’s map of {:to, story, port}Binder (nests)0every port typed; the composition checked at mount and drawn3
Feature LiveComponents plus plain clausesV49the panels’ own wires plus one handle_info clause per port; store work through start_asyncLiveView, send_update1clause heads read from source, both ways5
Plain story modulesV51each story’s private wire/4 between its parts, its input/4 and its handle_event/4; the page’s wire/3 between storiesV50’s Steps; each story given an out function0Wiring.gaps/1 for pages and stories, input_gaps/1, event_gaps/1; no event claimed by two stories4

The ones that reached the top of the full walk all hold their wiring in one place with a coverage check (V41-max, V39-max, V38-max, V45), or, split by user story, in one place per story plus the page (V46, V47, V51). Without the check, every form loses an output silently or crashes on it at run time. Which of them to adopt is in How close can a LiveView app come to ideal ALA?.

R9: ports are typed by a paradigm; no module owns an interface but its configuration

Put port protocols in the paradigm layer. A protocol or behaviour used as a port belongs to no domain abstraction. A domain module gets a port by implementing it. The thermometer post’s Step protocol is the example (push(step, data) :: {:emit, out, step} | {:quiet, step}). V39-max tries it in a variant: a request/response protocol, Ports.Call, is implemented by the configured AddLine, PlaceOrder and StartPayment, so the page’s bindings name those instances instead of wrapping page helpers in closures.

defimpl Step, for: LowPassFilter do
  def push(%{strength: k, last: last} = f, v), do: (out = last + (v - last) / k; {:emit, out, %{f | last: out}})
end

Don’t define a @callback for a peer. A behaviour defined by Checkout for StripeClient to implement is a “required interface”, and moving it to a shared module doesn’t make it more abstract (§2.3.4, §6.5.5). Implementing the callbacks of something far more general, like GenServer or Plug, is fine.

Let the app supply the type; don’t share a DTO. Two domain abstractions “may not … share a DTO”, but “T may be passed in by the application” (§4.8.1). A struct the app defines and a generic module carries without matching on it is fine. A struct one peer defines and another pattern-matches on is not.

Collapse I/O into one paradigm value. The coffee maker’s SensorReading (all inputs) and HardwareCommand (all outputs) give the application ports shaped by their kind, not by any particular device. V25’s projections do the same for cross-feature reads: peers read a projection, never the struct.

%HardwareCommand{boiler_heater: :on, warmer_heater: :off, relief_valve: :closed}

Outputs announce; they don’t command. “An output port from an abstraction may say ‘This has happened’ or ‘Here is my result’, not ‘do this next’” (§7.2.6). A common Elixir outcome like Outcome.stream_insert(:cart, item) bundles a verb (“insert”), a target (:cart), and a payload, and the checklist treats them differently:

The checklist doesn’t prescribe how. Three techniques meet the “must”, with different costs:

  1. Announce facts; the page maps them. The feature returns {:item_added, item}, and the page decides that means “insert into the cart stream and flash ‘Added’”. It meets both halves and is closest to Spray, but it costs a page clause per fact, and every feature needs its own fact vocabulary. V35’s typed facts plus manifest reactions are the closest variant.
  2. Results on the feature’s own ports, bound once by the page. The feature returns {:rows, {:added, item}}, a collection change on a port it names itself. The page binds that port once (rows: {:stream, :cart}), and a generic interpreter applies the binding. It meets both halves with one line per port rather than per fact. V39 does this with its Binder. An unbound port is dropped silently, so V39-max adds a test that every declared port is bound or deliberately grounded.
  3. Pass the target in as configuration. Wishlist.new(stream: :wishlist), with the feature returning stream_insert(config.stream, item). It’s the smallest change to a V10/V36-style app, and it meets the “must”. It meets the “should” only weakly, because the page can change which stream, but not what kind of receiver.
{:item_added, item}                   # 1: a fact; the page maps it
{:rows, {:added, item}}               # 2: a result on the feature's own port; the page binds :rows
stream_insert(config.stream, item)    # 3: an operation on a target the page configured
Outcome.stream_insert(:cart, item)    # fails the "must": the feature names the page's stream

Earlier versions of this guide said “return instructions, not events”. Where the instruction is built matters. In V10 the page composition (CartPage) builds stream_insert(:cart_items, item), so the page names its own streams, which is fine. In V36 the features do: Wishlist.remove/2 returns Outcome.stream_delete(:wishlist, product) and the flash text “Removed from wishlist”. That fails the “must” as it stands. Technique 3 is the cheapest fix.

Configure once, apart from run-time data (a “should”). Spray’s §3.9 derives ALA’s objects from procedures, and one of his reasons is configuration: passing it with every call “would be awkward. It would also mix the data parameters of the function with the configuration parameters, breaking the Interface Segregation Principle.” His own §1.6.3 thermometer still passes its settings on every call, a rung he climbs past, so the checklist makes this a “should”. Three Elixir forms meet it:

  1. Configuration as the first argument. A map or struct built once at the composition comes first, run-time inputs after it, the same order as Regex.run(regex, string). The composition holds the value and passes it, or captures it once for a pipe.
  2. A struct that carries its configuration. Build %LowPassFilter{strength: 10} once, then Step.push(filter, v) many times. The struct can also carry the concept’s state (R4).
  3. A function built once. The composition closes over the configuration and passes the function. It works, but the closure can’t be inspected.
@shipping %{rates: %{standard: 500, express: 1500}, free_over: 10_000}
Shipping.cost(@shipping, order)             # 1: config first
cost = &Shipping.cost(@shipping, &1)        # 3: captured once, handed down as a function
Shipping.cost(:standard, order, @rates)     # doesn't meet it: settings mixed into the data

Adapt mismatched ports with a lambda at the wiring. When one port’s shape doesn’t fit another’s, Spray’s adapter “can be as simple as a lambda expression passed to the WireTo operator” (§6.17.4). In Elixir, an fn in the composition.

Test against ports. “You always test with dependencies in place, but you mock the ports” (Summary). The rule is that a test never replaces a knowledge dependency. Pass a fake into the port: a stub struct, a function, or a test pid as the output. Mox is fine for a paradigm-layer behaviour, since that is a port. Mocking a lower-layer module the subject calls by name is the failing case.

Configure domain instances once, configuration first. Every rule the pages used per call became a struct the page builds once and passes down: rates, promo codes, the gift-wrap fee, the low-stock level, the currency. Run-time data comes after it.

BuildLineItems.new(currency: StoreConfig.currency())        # built once by the page
BuildLineItems.call(c.line_items, Cart.items(cart))          # used with config first
Inventory.status(Inventory.new(low_at: 5), product.stock)

Implement a paradigm port for request/response. A protocol in the paradigm layer that no domain module owns lets configured instances that do I/O be named in the wiring instead of wrapped in closures (V39-max’s Ports.Call, request/response in Spray’s §4.6).

defprotocol ZeroCoupled.Ports.Call do
  def call(instance, payload)
end

defimpl ZeroCoupled.Ports.Call, for: ZeroCoupled.Domain.StartPayment do
  def call(%{gateway: g, urls: urls, cart_key: key}, {line_items, cart_id}),
    do: g.create_checkout_session(line_items, %{key => cart_id}, urls)
end

{:checkout, :ready_to_pay} => [{:async, :payment, %StartPayment{gateway: ..., urls: ..., cart_key: ...}}]

Name outputs as facts, and let the wiring turn them into actions. persist became changed, Undo’s timer became captured, payment became ready_to_pay, and the cart’s “pay” became checkout_requested. In V39-max the page’s bindings start and stop the undo clock on those facts.

{:undo, :captured} => [{:set, :undo_pending, true}, {:start_timer, :undo, StoreConfig.undo_window_ms()}],
{:undo, :restored} => [{:stop_timer, :undo}, {:input, :cart, &Cart.receive/2}]

R10: no two features know the meaning of the same data

The rule is a property: no domain struct is read or destructured by two features, so either can change its data’s shape without editing the other (Spray’s “no data coupling”, §3.8). These techniques meet it.

Read the shared aggregate strictly (2026-10-03). Spray says use cases depending on entities “is incompatible with ALA”, and that an identity “should not be used as the carrier of information between two use cases” (§6.17.2). So two things now miss R10, each −1 on the full walk, and ala_lint scores a domain struct several features read from --strict up. One is a consumer that receives another feature’s whole aggregate: checkout took %Cart{} to use three facts of it. The other is a struct carrying one use case’s data that another use case shares: the portal’s order lines are built on the storefront’s cart, promo and gift wrap included.

Send a consumer only what it needs. A dataflow carries “only the data that is needed by the use case” (§6.17.2). V46, V48 and V49 send checkout the cart’s id and stored lines, and checkout owns the readiness rule it used to borrow from the cart:

# the cart's state: the id and lines go out, not the cart
def request_checkout(%Cart{} = cart, _), do: {cart, [checkout_requested: {Cart.id(cart), Cart.items(cart)}]}

# checkout: pays for lines
def pay(%__MODULE__{} = c, {cart_id, items}) do
  case ready(items, c.stock_levels.(Enum.map(items, & &1.product.id))) do

Share the abstract part, not the entity. The other half is splitting one use case’s data out of the struct another shares. V46 to V49 give the portal’s OrderLines its own struct and pricing, and put what both use cases need underneath both: Lines, plain functions over a list of stored lines that hold no prices, codes or flags.

def add(%__MODULE__{} = order, {item, quantity}) do
  items = Lines.add(order.items, item)
  # ...the order's own volume-tier pricing follows in recalc/1

Give features private structs and share only a key. V24’s isolated capsules, V26’s dual capsules, and V36’s per-feature structs mean two features never hold the same data struct. They share an identity (a product id) and keep their own data.

%Wishlist{product_ids: [id]}         # share the id...
%Cart{items: [%{product_id: id}]}    # ...not each other's struct

Mediate cross-feature reads through a projection or the composition. V25 hands feature A a projection of B, not B’s struct, and V35 has the composition resolve the value and pass it in.

def projection(%Inventory{count: n}), do: %{in_stock?: n > 0}

Make both ends one abstraction. When two features must share a format, one module can own it and both use an instance of it (Spray §7.8; see R5’s codec sketch). Not tried in a variant yet.

R11: the composition layers are composition only

Spray’s application has “no normal programming language code such as assignments and if statements” (§3.5). His own examples show what that covers. Naming an instance so it can be wired twice is fine (§1.6.6), and so is passing a predicate as configuration (§3.11.3). Deciding what runs, and computing data between calls, is not. The checklist sorts page ifs into five kinds, and each has a move.

Features are compositions too. When an application outgrows the size limit, Spray adds a Features layer under it, and “Each feature creates instances of domain abstractions, configures the instances with feature specific details, and connects them together as needed to express the feature or user story” (§2.2). A feature’s UI layout and “the bindings of the UI elements to data” go with it, built from domain UI abstractions (§7.14). So R11 holds for a feature exactly as it does for the application. That’s not what this project’s variants mean by a feature. Their Features.Cart and Features.Undo are state and rules with ports, which Spray would call stateful domain abstractions. Since 2026-10-02 the checklist scores that name as an R8 “should” (−0.5), and ala_lint treats a layer named for features as a composition layer. How close can a LiveView app come to ideal ALA? measures where a page would split into real features.

Don’t contain a sub-component. “There is no analog of a sub-module or sub-component, no such thing as a sub-abstraction. Abstraction layers replace hierarchical containment” (§2.2). A page-specific LiveComponent, like the FormComponent that phx.gen.live generated in every storefront here, has its own state, lifecycle and handlers, and it’s used only inside one page. That makes it a contained sub-component, which costs −1 on the full walk, or −2 when a page has several, as V40’s and V42’s circuit panels do. Spray’s provision for app-specific UI is layout and bindings: “Using one in a specific application only requires a label and a binding to an action” (§7.14).

Build a page’s form from a generic record form. A domain UI component takes the fields, the words and a form as attributes, emits validate and submit events with the params, and shows the errors it’s given. A small RecordEdit state holds which record is open, and the page wires its submit to the save instance and the outcome back. V46 and V47 replaced the generated FormComponent this way.

<.record_form id="product" form={@form} fields={@product_fields} t={@texts.form}
              on_validate="validate_product" on_submit="save_product" />
# V46
defp wire(s, :product_form, {:submit, request}),
  do: Steps.feed(s, :product_form, &RecordEdit.saved/2, &SaveProduct.save/1, request, &wire/3)

defp wire(s, :product_form, {:saved, {action, product}}),
  do: s |> stream_insert(:products, product) |> put_flash(:info, @saved[action]) |> push_patch(to: ~p"/products")

Split a page along its user stories. When a page outgrows Spray’s size limit, give it a Features layer of his kind. Each story module instantiates and configures its parts, wires them with its own clauses or map, lays out its own view from domain UI components, and declares the few ports that leave it. The page wires the stories. V46 does it with clauses and V47 with maps. On the cart page the cut gave 12 links between five stories, three of them links that had been hidden in shared assigns.

# V46: inside a story, then on the page
def wire(s, me, :cart, {:removed, item}), do: Story.send_out(s, me, :removed, item)
defp wire(s, :edit_cart, {:removed, item}), do: Story.input(s, :undo, :capture, item)

Split the shell: generic interpreter below, page dispatch in the page. V36’s shell reduces a list of outcomes into view state. That interpreter is generic, so in Spray’s layers it’s an execution model below the page (Programming Paradigms). The part that names the page’s composition is page code. Splitting them keeps any page’s name out of the lower layer. (V35’s EffectInterpreter is the same idea.)

# paradigm layer, shared by every page:
def apply_all(socket, outcomes), do: Enum.reduce(outcomes, socket, &apply_outcome/2)

Guards go into the connection mechanism. “Only if there’s a value” or “stop on error” belongs in the thing that connects the steps, as Spray factors the ifs “into the Compose function” (§6.1.3). In Elixir that’s with, a runner that stops when a stage returns :quiet, or Stream filtering. The :quiet runner is run in the thermometer post, not tried in a variant.

with {:ok, order} <- Checkout.submit(page.checkout),
     {:ok, receipt} <- Payments.charge(order), do: ...

Requirement conditions become configured instances; history becomes a state machine. A rule becomes a predicate passed to a generic abstraction (R3 above), or a small logic abstraction like the coffee maker’s AND gate (§2.9.3). A rule that depends on what happened before becomes a state machine (§4.16). V33’s flows channel, a pure transitions table, is the closest variant.

Keep an abstraction’s own rules inside it. The coffee maker’s Boiler enforces “the heater is off whenever I am empty or my valve is open” itself. The application asks it to heat, and it refuses when that would be unsafe, so the rule never reaches the top.

Route outcomes; don’t decide on them. A case whose arms only send the ok and error results to different places is routing two output ports, which is how the checklist reads Spray’s activity-flow If (§4.9.1). A case that computes in its arms is logic, and belongs in a feature.

Move iteration and compound conditions out of the page template. A for over rows in the page’s HEEx is iteration in the application. A generic table component should do it (§4.12). A compound :if is logic, so compute the boolean in a feature and wire it. A :if={@flag} on one boolean a feature produced is just a “display when” wire.

<.table rows={@streams.items} />   <%!-- the component iterates, not the page --%>

Move lifecycle guards out of mount/3. An on_mount hook is LiveView’s own extension point. V39 and V41 use a generic hook in the paradigms layer for the if connected?(socket) subscription, configured on the page as on_mount {Subscribed, {Broadcast, :subscribe}}, so their mount/3 has no branch. Auth redirects fit the same hook; no variant here has auth, so that part is untried.

Make mount an event on the diagram. Loading rows in mount/3 and handing them to a feature is the page handling data. V39-max delivers a {:page, :mounted} event through its bindings, where it’s bound to {:via, &Carts.list_items/1, [{:input, :cart, &Cart.load/2}]}. V38-max configures its cart feature with the store, so the feature loads itself, as V41’s panels do.

Replace a composed input with an output. A handler that reads assigns to build another feature’s input (fetching stock before paying, finding a line to wishlist it) becomes one input on the first feature, whose output carries the value onward. In V39-max, pay runs Cart.request_checkout/2, and its checkout_requested output is bound to Checkout.pay/2.

Generate the glue. V30’s committed codegen makes the page’s wiring a generated file, so the hand-written page stays thin. Spray keeps generated wiring code apart too, “because it is not source code” (§2.5.1).

mix zc.gen --check  # fail the build if the committed glue drifted from the manifest

Place parts with generic components instead of comparing in the template. Comparisons a template needs (which tab, which step, is a count zero, is the button disabled) move into generic components that take the current value and the name. All three max variants use them.

<.tabs current={@active_tab} event="switch_tab"><:tab name={:items} label={@texts.tabs.items} /></.tabs>
<.pane current={@active_tab} name={:items}>...</.pane>          <%!-- kept mounted, hidden --%>
<.only_on current={@step} name={:payment}>...</.only_on>       <%!-- rendered only when current --%>
<.none count={@saved_count}>{@texts.saved.empty}</.none>

Put a rule’s display beside the rule. A product page’s case on stock status became a domain UI component that takes the configured rule and the page’s labels (StockIndicator, in all three max variants). It sits in the domain, next to the rule it uses, so the edge drops (R1).

<.stock_indicator stock={product.stock} rule={@stock_rule} labels={@stock_labels} />

Move store work out of page helpers. A private page function that the wiring calls is still application code. V39’s and V40’s finalize/2 places the order, loops over the lines to decrement stock, and broadcasts each change, and add_line/2 passes a product read straight into a cart write. Make each a domain abstraction that does its own I/O, configured with its stores, the way Spray’s Display writes to the screen itself. The max variants all did: AddLine, PlaceOrder (V38-max and V45: SettleOrder), and a payment instance, each named once at mount and wired like any other instance.

instances: %{place_order: %PlaceOrder{orders: Orders, carts: Carts, products: Products, announce: &Broadcast.stock_changed/2, cart_id: cart_id}}

Let rows carry the booleans the template needs. A feature’s row projection includes what the template would otherwise compute (at_minimum, not quantity <= 1), or a row component takes the list it checks membership in.

at_minimum: Lines.at_minimum?(line)                      # in the feature's row/2
<.cart_item_row row={row} wishlist_ids={@wishlist_ids} />  # the component decides the mark

Configure a feature with its store so it loads itself. Instead of reading the store in mount/3 and handing rows to a feature, give the feature its store as configuration and a load input (V41’s panels, and V38-max’s first version). The other route is a runner that feeds a source’s answer into an input, Steps.feed(:cart, &Cart.load/2, &Carts.list_items/1, cart_id, &wire/3), as V38-max does now.

Cart.new(cart_id: cart_id, store: Carts, shipping: Shipping.new(...), ...)
def load(cart, _), do: (cart = %{cart | items: cart.store.list_items(cart.cart_id)}; {cart, [rows: {:reset, rows(cart)}]})

Add the foundation function that removes a hand-off. Products.get!(id) |> Products.delete() in a handler is the page passing one store result into another call. A store function that does both (Products.delete_by_id/1) keeps the handler to one call.

def handle_event("delete", %{"id" => id}, socket) do
  {:ok, product} = Products.delete_by_id(id)
  {:noreply, stream_delete(socket, :products, product)}
end

What remains after all that is framework-imposed: the multi-clause handlers that route events (the checklist reads each clause as a wire), decoding the browser’s string params, and a lookup from URL to step. The checklist records these as departures, kept small and never used for logic; the linter doesn’t count routing clauses, with, or a connected?/1 guard. With those moves a page can reach zero R11 findings, and V41 does. The max variants go further: V41-max, V39-max, V38-max and V45 scored 100 on the full hand walk, and 98 to 99 since the two stricter readings above (each still has the generated FormComponent and a Features namespace). V46 and V47 meet both readings and score 100, and so do V48 (V45 with only the two fixes, familiarity 4) and V49 (V41-max with plain clauses instead of a route table, familiarity 5). V39 and V40 get their handlers there too, but keep some store work (an order-placement loop, a read passed straight into a write) in page helpers, which R11 now reports. ala_lint still scores R11 only under --super-strict, because getting there means choosing a design (a binding map, a circuit, or announcing instances) that a CI gate shouldn’t choose for a team. How close can a LiveView app come to ideal ALA? goes through each departure.

LiveView, rule by rule

LiveView gives a page a handful of tools, and each can be used in a way that meets a rule or misses it. The checklist keeps this table; it’s this project’s Elixir reading of Spray, settled while rescoring the variants on 2026-10-01.

LiveView featureMeets the rule whenMisses it whenRule
mount/3it configures instances and assigns their starting values; a read happens through a runner or a pull port (Steps.feed, source={&Carts.list_items/1})it reads a store and hands the rows to a feature or componentR11
handle_event/3, handle_info/2, handle_async/3 clauseseach clause forwards one event, message or async result to one input, decoding params at the edge; all clauses sit in one modulea clause computes, decides, or builds one feature’s input from another’s state or from assignsR11, R8
handle_params/3it looks the step up in a page-owned table and passes it to the feature that decidesit encodes which steps may follow whichR11
Assignsthey are the landing points of outputs and the page’s configurationthe page derives values in them (assign(:total, Enum.sum(...)))R11
HEEx in the pageit places UI abstractions, passes data in through attributes and slots, names events; :if on one boolean, field readsa comparison, arithmetic, case, :for, or a call into a lower module (use pane, only_on, none, stream_list, or a row that carries the boolean)R11
Streamsa feature’s rows output lands as stream_insert/stream_delete; a generic stream_list iteratesthe page iterates them with :forR11
Function componentsthey render passed-in data, take their words from the page, emit events they’re given names forthey hold words, fetch, persist, or decide product rulesR3, R6
Slots and :letthe page passes markup into a container or host (the UI-layout port)no common misuseR6, R8
LiveComponent stateit is the component’s own interaction state (open, draft, selected), or a feature value the component rendersit is the product’s state together with I/O (V41’s panels)R6
LiveComponent datadata comes in as attributes, slot values, or a pull port (a read function the page passes)it calls a store or repo by name, or requires a store module’s API (store.list_items, store.apply_change): the component owns the interface it needsR6, R9
LiveComponent changesa change goes out as a port output (send_port_output) or an event, and the page wires it to the storethe component saves it itselfR6
send_update/2the page passes an output to another instance’s input (a wire)an instance sends to a sibling it namesR1, R2
send(self(), ...) from a componentit sends a port output to the page that placed it, under the name the page gave it (name={:cart})it targets a specific peer, or names itself in its own code so the page must match a literal (V41, V41-max)R9, R5
start_async/3the page (or a generic host) runs a configured I/O instance and routes the outcome back to the featurea feature component makes the gateway call itselfR6, R11
Timers (Process.send_after)a paradigm or the page starts one on a feature’s fact (captured) and routes the tick to an inputa feature component keeps a clock as part of the product logicR9, R11
PubSuban on_mount hook subscribes; handle_info routes the fact to an input; for outside change, a live subscription port the page wires (ChangeFeed, under R1)a module subscribes itself to a topic it names; a feature caches another’s data to keep it current, or a context broadcasts rendered rowsR1, R5, R10
push_patch, push_navigate, redirectthe page patches on a feature’s step through its path table, or redirects to a URL an output carriesa component patches, or a feature names a pathR3, R9
Forms and changesetsa feature or domain module validates; the page supplies the messages; the form posts events to the page or hostvalidation messages live in the feature; the page validatesR3, R11
JS commands and hooksJS.navigate, phx-hook named in the templatea hook carries product rulesR3
Page-specific LiveComponents (FormComponent, a page’s own panels)never: a page composes its UI from domain UI abstractions it configures (a generic record form), and its function components hold only markupa LiveComponent with its own state and handlers is used only inside one page: a contained sub-component (§2.2)R11

Four readings sit behind it.

Clauses in one module meet R8. A page’s handle_event and handle_info clauses, or one wire/3 clause per port, are one place, which is what Spray asks of connections (§3.3.1). A route table or bindings map is a technique you can add, not a requirement.

A UI component that does I/O is an R6 bundle. Spray keeps the UI element that displays data apart from the data source wired to it (§5.2.2). A LiveComponent that loads its rows from a store and saves changes back is three abstractions in one module. Keep the component and take the I/O out: rows come in through attributes or a pull port, changes go out as port outputs, and the page wires the store. That’s how V41-max got back to 100.

A pull port is wiring; a required store module isn’t. Passing a read function (source={&Carts.list_items/1}) wires a data source into the component, the way Spray’s Grid “is able to pull rows of data as needed”. Passing a store module and calling store.list_items and store.apply_change on it makes the component define the API it needs from a store, an interface it owns (R9).

A page-specific LiveComponent is a contained sub-component. Settled on 2026-10-02, this replaces the earlier reading that such a component is part of the application and may wire. The R11 section above has the reasons and the fix.

ala_lint checks the second reading as ui_io: a LiveComponent or component module below the composition that calls a store, a configured I/O abstraction, or a module held in a variable or assigns. It checks the fourth as subcomponent: a LiveComponent in the application or a Features layer. Both are scored by --strict.

Past the pipe: composition techniques from Spray’s later steps

These come from Spray’s §1.6.4–1.6.6, where the application stops handling the data at all. All are run in the thermometer post and its code. None has been tried in a full variant yet.

How to use this when starting from scratch

Don’t adopt a variant. Adopt the checklist, run ala_lint against what you have, and let the findings send you shopping in this list. Most well-structured Elixir apps are already close on R1, R2, and R4, because immutability and ordinary module boundaries hand you a lot. The work that remains is usually:

Reach for the heavier techniques (typed outcomes, a manifest, committed codegen, a composition value with a runner) only when a rule you care about isn’t holding by discipline alone. The lightest technique that clears the rule is the right one.

← all posts