V51, plain stories: Spray's Features layer, and every lint rule at its strictest

October 3, 2026 · ALA · V51 · LiveView · features · stories · checklist

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:

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

V46V50V51
Full checklist, by hand100100100
ala_lint default / --strict / --super-strict100 / 100 / 99100 / 100 / 100100 / 100 / 100
Rules met under --strict / --super-strict (of 10 checked)10 / 910 / 910 / 10
Spray’s Features layeryesnoyes
LiveView relays between componentsnonenonenone
Cart page lines, with template277516292
Non-blank lines in lib/5,1714,5484,916
Tests125118126
Familiarity354

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

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.

← all posts