V59, light ALA: twelve rules on plain Phoenix

October 24, 2026 · ALA · light ALA · V59 · LiveView · checklist · ala_lint

Light ALA is the part of ALA that cost about what conventional Phoenix costs when seven variants of this store went through the same ten requirement changes. V59 is the variant that holds it. It starts from V0, the conventional app, and adds twelve rules. Nine come from the forms measured in that post, one from the hybrid that added composition roots, and two from what the hybrid’s run caught. It implements the base requirements, so you can read it as a starting point rather than as the end of a change run. The code is at ala_variants_elixir/v59-light-ala.

This is a reading of the checklist, not Spray’s ALA. Spray’s applications also compose by ports (§3.5, §7.2.3): a feature “creates instances of domain abstractions, configures the instances with feature specific details, and connects them together” (§2.2). V59 keeps the creating and configuring and replaces the connecting with calls.

What stays Phoenix

Everything a Phoenix team already writes stays as it is: contexts, LiveViews, handle_event, streams, PubSub, start_async, Mox, ExUnit. Pages branch, loop and pass values between calls. CheckoutLive.Index checks stock, calls the payment provider and completes the order in its own handlers, as V0’s does. There are no ports, no wire/3, no stories and no running trace. If you know V0, you can read V59 without a glossary.

The layers (rules 1–3)

Four layers, each depending only on the ones below:

LayerPeers may call each otherModules
appyesLiveViews, ShopComponents, UndoRemoval, CartSession, Plugs.EnsureCart, Router, Calibration
contextsnoCatalog, ShoppingCart, Orders, Payments
domainnoGoodDeal.Domain.{Pricing, ShippingMethod, VolumeTier, PromoCode, StockStatus}
platformyesRepo, ProductEvents, Channel, Shop, the Ecto schemas, the payment provider

Rule 1: no context calls another. In V0, Orders called ShoppingCart.Pricing to price the order it was writing. In V59 the page already holds the priced summary, so it passes it in: Orders.complete_checkout(shop, summary). This is what kept order history (S04) at V0’s cost in the change runs, where strict ALA paid 1.9× to carry the summary along wires.

Rule 2: calibration at the top. Every application literal lives in GoodDealWeb.Calibration, one %Channel{} per channel: shipping methods, promo codes, gift-wrap price, volume tiers, the low-stock threshold, the PO format. Lower layers read it from the struct they are handed, so StockStatus.of(channel, stock) reads channel.low_stock_threshold, and no context or rule holds a number from the requirements.

Rule 3: rules as named pure modules. A rule is a module named for its concept, configured by its caller, with no I/O: ShippingMethod.cost(method, subtotal), VolumeTier.discount(channel, subtotal), PromoCode.valid?(channel, code). One-line calls stay where they are; a rule earns its module by having a name and edge cases of its own.

Interfaces that don’t break (rules 5–9)

These came from measuring. Form 1, the first three rules alone, ran at V0’s cost but broke 1.44× as many existing tests per change, and every extra break was an interface: a context function growing an argument for each value passed down, an accessor renamed when a value split by channel, a rule’s return reshaped. Five rules fixed it:

A composition root per page (rule 10)

Each LiveView that uses configured parts has one private parts function, called from mount, that builds them. The cart and the portal edit a cart the same way, so their roots share one builder and pass their own channel, stream and repricing:

# CartLive.Index
defp parts(session),
  do: CartSession.editor_parts(session, :storefront, :items, &assign_summary/1)

# CartSession
def editor_parts(session, channel, stream, reprice) do
  shop = session_shop(session, channel)

  %{
    shop: shop,
    pricing: &Calibration.pricing(shop.channel, &1),
    undo: %UndoRemoval{shop: shop, stream: stream, reprice: reprice, window_ms: Calibration.undo_window_ms()}
  }
end

mount assigns it once as parts, and handlers call parts.shop, parts.pricing.(cart) and parts.undo, where removing or restoring a line is one call that reprices through the page’s own function. No handler calls Calibration, CartSession or Application.fetch_env! itself. Nothing is wired: the parts are called and their results used, as anywhere in Phoenix.

PageParts
CartLive.Indexthrough editor_parts: shop (storefront), pricing, undo (stream :items)
PortalLive.Indexthrough editor_parts: shop (portal), pricing, undo (stream :lines)
CheckoutLive.Indexshop, pricing, success_url
ProductLive.Indexshop
ProductLive.Showchannel, for the stock badge

How to read a page: start at its parts. It tells you which channel the page sells on, how it prices a cart, how removal is undone and which session cart it writes to. Then read the handler, then the context function it calls, then the rule that function hands a channel to.

The shared builder is a trade the linter forced. Each page first wrote its own root, and the two were alike enough for the clone check to flag them; sharing the builder fixed that, but a reader of the cart page now follows one call to CartSession to see what the page is made of. For two pages that edit a cart the same way, that is a concept with a name, editor_parts, so I kept it. A page that composes differently keeps its root inline, as checkout and the product pages do.

In the change run the roots cost 49 production lines over ten changes, and no later change went around them. They do not show everything: the promo form, shown prices and the live subscription sit outside them, which is how one missing check went unnoticed on the checkout page.

Two guards from the run (rules 11–12)

Rule 11: builders take keyword overrides, and tests build through them. A builder of a config or context struct takes the values it cannot do without as arguments and the rest as options, handed to struct!/2, which refuses a missing enforced key and an unknown one:

def shop(channel, overrides),
  do: struct!(Shop, [channel: Calibration.channel(channel)] ++ overrides)

Tests never write a struct literal; they call shop(:storefront, cart_id: cart.id) and Calibration.channel(:portal, volume_tiers: []). In the run, a positional shop builder that gained one argument broke 119 tests at once through the shared fixture. Under rule 11 a new field is one more option.

Rule 12: a write to a session cart sees a current cart. In the run, a reorder written as a LiveView event used the shop its page built at mount. After the portal’s Submitted step, the LiveView session still named the completed draft, and the reordered lines went into it and were lost. In V59, each root’s mount attaches a guard:

|> CartSession.guard_open_cart(shop, ~p"/cart")

Before every event it asks ShoppingCart.cart_closed?/1. If the cart has closed, it drops the event, flashes “That cart is closed, so nothing changed. Please try again.” and reloads the page with a full request, so Plugs.EnsureCart puts an open cart in the session. Behind it, every ShoppingCart function that writes cart contents, and both Orders writers, refuse a closed cart with {:error, :cart_closed}, each with a context test. A write that gets past the page fails loudly instead of landing in a cart nobody reads again.

A LiveView can’t write the session, which is why the guard reloads rather than looking up a new cart in the event: a cart the session doesn’t name would be replaced on the next request, and the write lost the same way. Two narrow gaps remain, written up in DESIGN.md: the check and the write are not atomic, and a cart that closes during checkout’s payment gets the out-of-stock message.

Linter settings that keep it honest

The linter is how you notice when a change drifts from the design while you work. V59 runs ala_lint through a lint.exs beside the app, with the four layers above as the layer map:

cd ala_lint_elixir && mix run ../ala_variants_elixir/v59-light-ala/lint.exs
layers = [
  {:app, [~r/GoodDealWeb\.CartLive\./, ~r/GoodDealWeb\.PortalLive\./, ~r/GoodDealWeb\.CheckoutLive\./,
          ~r/GoodDealWeb\.ProductLive\./, ~r/GoodDealWeb\.CartSession$/, ~r/GoodDealWeb\.UndoRemoval$/,
          ~r/GoodDealWeb\.ShopComponents$/, ~r/GoodDealWeb\.Calibration$/, ~r/GoodDealWeb\.Plugs\./,
          ~r/GoodDealWeb\.Router$/, ~r/GoodDealWeb$/], [peer_ok: true]},
  {:contexts, [~r/^GoodDeal\.(Catalog|ShoppingCart|Orders|Payments)$/], [peer_ok: false]},
  {:domain, [~r/GoodDeal\.Domain\./], [peer_ok: false]},
  {:platform, [~r/GoodDeal\.Repo$/, ~r/GoodDeal\.ProductEvents$/, ~r/^GoodDeal\.(Channel|Shop)$/,
               ~r/^GoodDeal\.Catalog\.Product$/, ~r/^GoodDeal\.ShoppingCart\.(Address|Cart|CartItem|WishlistItem)$/,
               ~r/^GoodDeal\.Orders\.(LineItem|Order|PurchaseOrder)$/, ~r/GoodDealWeb\.CoreComponents$/], [peer_ok: true]}
]

# light ALA adopts layering, calibration at the top and named rules, not ports, wiring or
# composition-only pages, so the checks about those are off
checks = %{
  r9: :off, r10: :off, r10_aggregate: :off, r11: :off, r11_share: :off,
  ports: :off, ports_unwired: :off, ports_computed: :off,
  wiring_closure: :off, hops: :off, vocabulary: :off, subcomponent: :off
}

AlaLint.analyze(lib, layers: layers, exclude: exclude, checks: checks, strict: true)

(The full file, with the excludes and all three tiers, is lint.exs.)

What each setting holds you to:

SettingCatchesRule
peer_ok: false on contextsOrders calling ShoppingCart1
peer_ok: false on domainone rule calling another instead of being configured with it1, 3
the layer orderan upward edge: a context calling a page, a rule calling a context1
R3, scoreda §7 number or a channel name in a context or rule2
R7 clone, scored under --strictthe same logic written twice, e.g. a handler copied into a second page3, 10
R5, scoreda string two modules must agree on, such as a PubSub topic named like a table9
layer coverage (unassigned)a new module no layer pattern matches, which every layer check would then skip1
the twelve checks offports, wiring and composition-only pages, which light ALA does not adopt—

Three things to know when you read its output:

Since 2026-10-29 the twelve :off entries are one switch: the linter’s light-ALA preset, a whitelist of the checks light ALA adopts. With ala_lint as a dependency, the layer map goes in a layers module (config :ala_lint, layers_module: MyAppWeb.AlaLayers, a module whose layers/0 returns the list above) and the rest in .ala_lint.exs:

%{
  preset: :light_ala,
  checks: %{
    builder_literals: [structs: ["GoodDeal.Channel", "GoodDeal.Shop"], tests: ["test"]],
    stale_session_write: [
      writers: ["GoodDeal.ShoppingCart", "GoodDeal.Orders.complete_checkout",
                "GoodDeal.Orders.submit_portal_order", "GoodDealWeb.UndoRemoval.finalize"],
      except: [~r/^(get_|list_|cart_closed\?|check_stock)/],
      guards: ["GoodDealWeb.CartSession.guard_open_cart"]
    ]
  }
}

and mix ala.lint --strict reports R1 to R7 with R9 to R11 marked not adopted rather than met.

What it scores

What it costs and what it buys

From the change runs: form 1c, V59’s first nine rules, used 1.07× V0’s tokens over ten changes, broke 19 of the previous step’s tests against V0’s 33, and scored 4.3 for design fit against V0’s 4.0. The composition roots added 49 production lines over the same ten changes. The two guards here have not been through the change sequence, so their cost over time is unmeasured; they and the clone fix add 75 production lines and 291 test lines to V58’s baseline, most of it the open-cart tests.

Change cost against breakage avoided, for each variant measured Scatter of tokens per change relative to V0 against previous-step tests broken avoided relative to V0. V56 (form 1c) reaches 0.42 at 1.07 times V0; strict ALA reaches the same 0.42 at 1.34 times. The frontier flattens after V56. 1.0× 1.1× 1.2× 1.3× 1.4× -40% -20% 0% +20% +40% +60% Change cost: tokens per change, relative to V0 Previous-step tests broken, fewer than V0 past the knee: more cost, no more benefit V0, conventional V51B, strict ALA V52, R11 relaxed (8 changes) V54, form 1 (6 changes) V55, form 1b (6 changes) V56, form 1c V57, form 2 V58, hybrid 1
Each variant through the change sequence, against V0 over the same changes. Filled square: strict ALA (ports and wiring on every part). Filled circle: built up from V0; the large one is form 1c, the knee. Hollow: measured over six changes only; V55's ring marks a gain partly bought by weaker contracts. Breakage is counted with each step's own test fixtures. V50, V51 and V53 were built but not run through the sequence, and V59 is V58 with two guards, not yet run. One run per step; two runs of a step differed by up to 7% in tokens.

What it doesn’t buy: a drawing of the program, a running trace, or a part you can rewire into a second page without touching it. Those come with ports, which is where the change runs found ALA’s cost.

← all posts