V51, plain stories: Spray's Features layer, and every lint rule at its strictest
Two gaps were left after V50. Spray’s Features layer cost a familiarity point wherever a variant had it: V46 and V47 are at 3. And every top variant missed the same one rule under ala_lint --super-strict, R7’s public-surface check, because the cart’s state module had 17 to 19 public functions against a limit of 12. The end of the LiveView post named the two fixes as the strongest pair to try together, and V51 is that pair.
A story is a module of plain functions
V46’s stories have a struct holding their parts, instances, timers and view values, a behaviour, and a 146-line runner that nests. V51 drops all three. A story’s parts are plain assigns, as in V50, and V50’s Steps.run/4 runs them. What’s left is a module with a small public surface:
defmodule GoodDealWeb.Stories.UndoRemoval do
def parts, do: %{undo: Undo}
def events, do: ~w(undo_remove)
def ports, do: %{in: [capture: :item, expire: :item], out: [restored: :item, expired: :item_id, pending: :flag]}
def mount(s, opts, _out), do: assign(s, undo: Undo.new([]), undo_timer: {opts[:timer], opts[:window_ms]})
def handle_event("undo_remove", _params, s, out), do: run(s, &Undo.restore(&1, nil), out)
def input(s, :capture, item, out), do: run(s, &Undo.capture(&1, item), out)
def input(s, :expire, item, out), do: run(s, &Undo.expire(&1, item.id), out)
defp run(s, step, out), do: Steps.run(s, :undo, step, &wire(&1, &2, &3, out))
defp wire(s, :undo, {:restored, item}, out) do
{timer, _} = s.assigns.undo_timer
s |> Steps.stop_timer(timer) |> out.({:pending, false}) |> out.({:restored, item})
end
# ...
end
out is the page’s wire/3 with the story’s key already bound. A story sends an output by calling it, so it never knows its own key, the page, or any other story. Its own parts are wired in its private wire/4 clauses, which is what Spray’s features do: “Each feature creates instances of domain abstractions, configures the instances with feature specific details, and connects them together” (§2.2). Its view is plain function components, so its layout stays inside it, composed from the domain UI components (§7.14).
The page wires stories
The page binds each story’s key into an out function and sends to a story’s input with to/4. Its wire/3 clauses are the links between stories:
defp to(socket, key, port, payload), do: @parts[key].input(socket, port, payload, out(key))
defp out(key), do: &wire(&1, key, &2)
defp wire(s, :edit_cart, {:removed, item}), do: to(s, :undo, :capture, item)
defp wire(s, :undo, {:restored, item}),
do: s |> to(:edit_cart, :receive, item) |> put_flash(:info, "Item restored")
defp wire(s, :wishlist, {:taken, product}),
do: s |> to(:edit_cart, :add_product, product) |> put_flash(:info, "Added to cart")
The cart page is 292 lines with its template, down from V50’s 516, and under Spray’s 500-line limit, which is where he adds the layer (§2.2).
Smaller state, wired inside a story
V50’s State.Cart mixed the cart’s lines, a promo code, a shipping choice and the totals. V51 splits it into three abstractions:
CartLinesholds what’s in the cart: the lines and which are gift-wrapped.Promoholds a code, checked against the store’s codes and kept in normal form.CartTotalsholds the priced summary. It joins the lines’ amounts and quantities, the discount, and the shipping method.
The pure GoodDeal.Cart aggregate goes with them. The new wires (lines to totals, promo to totals) are inside the EditCart story, so the split doesn’t add a clause to the page. That’s why the two directions go together. Smaller abstractions mean more wires, and a Features layer gives those wires somewhere to live that isn’t the page.
What the build changed
The first version had the page keep one handle_event clause per browser event, as V50 does, each calling a story’s input. It passed every test. Walking R5 before scoring showed the problem: each event name was written in a story’s template and matched in the page’s handler. The checklist’s R5 says such a contract, “a name emitted here, matched there”, is an edge the call tree can’t show. V50 never had it, because its template and handlers are one module. Splitting the page is what created it. The undo timer and the payment task had the same problem, since a story started them and the page matched their names.
The fixes are R5’s own. For events, both ends now sit in one abstraction: each story declares events/0 and handles them in handle_event/4, as a LiveComponent handles its own. The page dispatches from the declaration:
@edit_cart_events EditCart.events()
def handle_event(event, params, socket) when event in @edit_cart_events,
do: {:noreply, EditCart.handle_event(event, params, socket, out(:edit_cart))}
For the timer and the task, the meaning stays in the composition. The page passes timer: :undo and task: :payment into the stories’ mount, so only the page knows the names match. A new check, Wiring.event_gaps/1, compares the events a story’s templates fire with its events/0 and its handle_event/4 clauses.
One other change came from R10. CartLines first sent CartTotals whole line items, product names and stock included. It now sends only what pricing reads, each line’s quantity and amount.
The cart page and its main story, drawn from their clauses
The page:
flowchart LR
payment -->|"done → succeeded"| check_out
payment -->|"done → failed"| check_out
timer_undo -->|"fired → expire"| undo
edit_cart -.->|"summary"| page_assign["page: assign"]
edit_cart -.->|"promo_error"| page_assign["page: assign"]
edit_cart -->|"removed → capture"| undo
edit_cart -->|"saved → stash"| saved
edit_cart -.->|"saved"| page_put_flash["page: put_flash"]
edit_cart -->|"line → toggle"| wishlist
edit_cart -->|"checkout_started → start"| check_out
edit_cart -->|"checkout_requested → pay"| check_out
undo -.->|"pending"| page_assign["page: assign"]
undo -->|"restored → receive"| edit_cart
undo -.->|"restored"| page_put_flash["page: put_flash"]
undo -->|"expired → confirm_removal"| edit_cart
saved -.->|"count"| page_assign["page: assign"]
saved -->|"moved → receive"| edit_cart
saved -.->|"moved"| page_put_flash["page: put_flash"]
wishlist -.->|"count"| page_assign["page: assign"]
wishlist -.->|"ids"| page_assign["page: assign"]
wishlist -->|"taken → add_product"| edit_cart
wishlist -.->|"taken"| page_put_flash["page: put_flash"]
ui -.->|"tab"| page_assign["page: assign"]
check_out -.->|"step"| page_assign["page: assign"]
check_out -.->|"form"| page_assign["page: assign"]
check_out -.->|"address"| page_assign["page: assign"]
check_out -->|"pay_requested → request_checkout"| edit_cart
EditCart inside, with the cart’s lines, promo and totals wired to each other:
flowchart LR
ev_update_quantity[/"update_quantity"/] -->|"update_quantity → update_quantity"| lines
ev_remove_item[/"remove_item"/] -->|"remove_item → remove"| lines
ev_save_for_later[/"save_for_later"/] -->|"save_for_later → save_for_later"| lines
ev_toggle_gift_wrap[/"toggle_gift_wrap"/] -->|"toggle_gift_wrap → toggle_gift_wrap"| lines
ev_toggle_wishlist[/"toggle_wishlist"/] -->|"toggle_wishlist → line"| lines
ev_select_shipping[/"select_shipping"/] -->|"select_shipping → select_shipping"| totals
ev_apply_promo[/"apply_promo"/] -->|"apply_promo → enter"| promo
ev_start_checkout[/"start_checkout"/] -->|"start_checkout → start_checkout"| totals
in_request_checkout((request_checkout)) -->|"request_checkout → request_checkout"| lines
in_receive((receive)) -->|"receive → receive"| lines
in_add_product((add_product)) -->|"add_product via AddLine.run → receive"| lines
in_confirm_removal((confirm_removal)) -->|"confirm_removal → confirm_removal"| lines
in_stock((stock)) -->|"stock → set_stock"| lines
lines -.->|"rows"| page_stream["page: stream"]
lines -->|"contents → contents"| totals
lines -.->|"changed"| call_Carts_apply_change["call Carts.apply_change"]
lines -->|"removed → removed"| out_removed[["removed"]]
lines -->|"saved → saved"| out_saved[["saved"]]
lines -->|"line → line"| out_line[["line"]]
lines -->|"checkout_requested → checkout_requested"| out_checkout_requested[["checkout_requested"]]
promo -->|"discount → discount"| totals
promo -->|"applied → promo_error"| out_promo_error[["promo_error"]]
promo -.->|"applied"| page_put_flash["page: put_flash"]
promo -->|"rejected → promo_error"| out_promo_error[["promo_error"]]
promo -.->|"rejected"| page_put_flash["page: put_flash"]
totals -->|"summary → summary"| out_summary[["summary"]]
totals -->|"checkout_started → checkout_started"| out_checkout_started[["checkout_started"]]
What it scores
| V46 | V50 | V51 | |
|---|---|---|---|
| Full checklist, by hand | 100 | 100 | 100 |
ala_lint default / --strict / --super-strict | 100 / 100 / 99 | 100 / 100 / 100 | 100 / 100 / 100 |
Rules met under --strict / --super-strict (of 10 checked) | 10 / 9 | 10 / 9 | 10 / 10 |
| Spray’s Features layer | yes | no | yes |
| LiveView relays between components | none | none | none |
| Cart page lines, with template | 277 | 516 | 292 |
Non-blank lines in lib/ | 5,171 | 4,548 | 4,916 |
| Tests | 125 | 118 | 126 |
| Familiarity | 3 | 5 | 4 |
The tests include V50’s cart, portal and product acceptance tests, byte for byte. On the same machine in one session, V51’s mean test took 4.9 ms against V50’s 4.5.
The walk finds nothing to deduct, with two judgement calls. CartTotals keeps the last value it received on each input, including the amounts and quantities CartLines owns. It reads nothing inside CartLines; the values arrive on a port, the way a filter keeps its memory. And the R5 finding above was fixed before scoring, not after.
The linter needed two changes to read V51 correctly, both listed in the lint post. It now counts out.(socket, {port, payload}) as a story sending that output, and it no longer reports the page binding a key to its own wire/3 as an opaque closure. Re-linting V46 to V50 after both left every score the same.
What it costs
- A new kind of module. V50 has none. A Phoenix developer meets a story module, the
outfunction and per-story event dispatch. All are plain functions and clauses, which is why I put it at 4 and not V46’s 3. That’s my judgement, as always. - A longer path for Pay. The Pay button is in the checkout’s view, but the cart’s lines are in
EditCart. SoCheckOutsendspay_requestedout, the page sends it toEditCart, and the lines come back through the page toCheckOut. V50 did it in one page. The path is visible in the drawing, but it’s longer. - A shared namespace. Stories on one page store their parts in the page’s assigns. Two stories using the same key would overwrite each other without an error. The current keys don’t overlap, and nothing checks that they never will. V46’s story structs, held under the page’s own key, can’t collide.
Later: the clone check (2026-10-19)
A clone check joined the linter on 2026-10-19 (R7, reported at the default tier and scored from --strict; a copy inside one module is reported and never scored). It found four pieces of logic written twice across modules. The checkout’s and the portal’s step machine (advance and goto) now lives in the Transitions paradigm, and the cart’s and order’s row in Lines.row. One is accepted with its reason in the code: set_stock already shares its logic through Lines.set_stock, and what is left is each state’s own port adapter. Later the same day V51B’s defect fixes were ported here (the portal’s “Item restored”, held removals kept out of settlement, distinct flash ids, and holds marked in the database so a closed page can’t lose a removal), and save for later was fixed in all three Elixir variants: a saved line is now marked in the database, so it stays in the Saved tab across a reload and is never charged, deducted or recorded at checkout. Now: 100 at every tier, 10 of 10 rules, 158 tests.
The step machine went into each variant’s own Transitions module, and the three did it differently: V50’s is a struct answering {:moved, to, machine} or :stayed, V51’s a struct answering {:moved, machine} or {:stayed, machine}, and V51B’s two plain functions answering the next state. The names and APIs are left as they are for now, so a reader comparing the variants meets the same idea three ways.
Later: a change feed (2026-10-21)
Changes made elsewhere used to reach a page through the on_mount hook Subscribed and a handle_info clause per message kind (stock_changed, product_created, product_updated), with Foundation.Broadcast and SaveProduct doing the sending. They now reach it through one part, GoodDealWeb.Paradigms.ChangeFeed, the checklist’s “live subscription port”, in the layer Spray keeps for paradigm interfaces (§2.2). %ChangeFeed{topic, format, facts} is both ends. A page mounts it with the same out(:feed) a story gets and wires feed.stock like a story’s output; the cart’s purchase publishes through the same struct:
feed = %ChangeFeed{topic: Catalog.product_topic(), format: ProductFacts, facts: [:stock]}
socket |> ... |> ChangeFeed.mount(feed, out(:feed)) # cart and portal subscribe
settle: %SettleOrder{announce: &ChangeFeed.publish(feed, &1), ...} # the cart's purchase publishes
defp wire(s, :feed, {:stock, change}), do: to(s, :edit_cart, :stock, change)
GoodDeal.Domain.ProductFacts owns the facts and declares the feed’s ports (stock: {product_id, stock}, product: the saved record), so the page’s @parts names it and the gap check and trace cover it. Delivery is one handle_info hook (attach_hook/4) that takes its own topic’s messages and passes every other message on, so the page writes no clause per kind of change. The running diagrams now draw feed -->|"stock → stock"| edit_cart where they drew an arrow from outside.
The move closed a gap: a staff stock edit at /products sent only product_updated, which carts and the portal ignored, so an open cart never saw it. The product pages now publish :stock too, and a test for each failed first. Two gaps are not closed, and neither is a one-line wire: a new product doesn’t appear in an open portal’s catalogue, and a price edit doesn’t reach an open cart. Each needs an input port on the state that holds the rows. Now: 100 at every tier, 10 of 10 rules, 168 tests.
Isn’t this just LiveView? No. LiveView keeps a process per open page and pushes rendered diffs from it to the browser, which solves page to browser. ChangeFeed solves world to page: it gets another session’s purchase or a staff edit into the stories inside that process, as identity-keyed facts over Phoenix.PubSub, wired like any story. LiveView then re-renders the new state and sends the diff, as always. How close can a LiveView app come to ideal ALA? has the longer answer.
What it shows
The Features layer doesn’t need its own runtime. A story can be plain functions over V50’s runner, and splitting the cart’s state is what reaches the linter’s strictest tier, once the extra wires have a story to live in. The surprise was R5. Splitting a page into modules turned names that one module used to agree with itself into contracts between two modules. Every split along stories has to settle again who owns each event, timer and task name.
For a page under Spray’s size limit, V50 is still simpler. V51 is the shape to grow into.
The wiring as it ran
Added 2026-10-16. The trace first built for V51B is now part of V51: Steps.to/7 and Steps.out/5 record every hop a page routes under the suite, the pages’ to/4 and out/1 became one-line calls into them, and the stories did not change. The suite writes docs/diagrams/running/ from the hops and fails if a declared output never routed. Its first run found the cart’s tab switch and the portal’s undo expiry wired and untested; both are tested now, 129 tests in all. Scored with a layer map, kept as lint.exs, V51 is 100 at every tier.
The code is in ala_variants_elixir/v51-plain-stories.