V07 in Rails, plain features: Spray's Features layer with two more words

October 17, 2026 · ALA · V07 · Ruby · Rails · features · checklist

V06 reached familiarity 5 by spelling ports the way Ruby already spells things: an input is a method, its outputs are the Hash it returns, a screen wires with one case. V05 had shown a feature placed by two pages, over the Ports foundation and under kept compositions, at familiarity 3. V07 asks whether Spray’s Features layer can be added to V06’s shape for no more than one point, and the answer is two words.

A feature is a composition that is itself a part

class Features::OrderLines
  include ProgrammingParadigms::Wiring
  OUTPUTS = %i[changed adding rows row_added row_changed row_removed contents saved line undo_pending restored].freeze
  GROUNDED = [].freeze

  def parts = { lines: @lines, undo: @undo }

  def load(items) = collect { run(:undo, @undo.load); run(:lines, @lines.load(items)) }
  def bump(change) = collect { run(:lines, @lines.bump(change)) }
  def remove(item_id) = collect { run(:lines, @lines.remove(item_id)) }
  def undo = collect { run(:undo, @undo.restore) }
  # ... twelve inputs in all

  private

  def wire(part, output, payload)
    case [ part, output ]
    in [ :lines, :removed ] then run(:undo, @undo.capture(payload))   # wired inside
    in [ :undo, :pending ] then out(:undo_pending, payload)            # leaves, renamed
    in [ :lines, _ ] | [ :undo, _ ] then out(output, payload)           # leaves as it is
    end
  end
end

The feature includes the same Wiring a screen does and wires its parts in its own wire. What V06 lacked was a way for an arm to say “this leaves me”: a screen lands an output on itself, but a feature has a page above it that wants the output back. collect opens a buffer and returns it; out appends a pair to it. Fourteen lines in Wiring, which is now fifty lines in all. Spray’s feature “creates instances of domain abstractions, configures the instances with feature specific details, and connects them together”, and “features can also have ports and be wired together” (§2.2); the instances are initialize, the connections are the arms that run, and the ports are OUTPUTS and the arms that out.

Two pages place it

To the page, the feature is a part whose method returned its outputs:

# the cart page: the storefront's links, a five-second window; everything it sends out is wired
@order = Features::OrderLines.new(cart_id:, products: lookup, undo_lines: CartItem, undo_window: Store::UNDO_WINDOW,
                                  links: ->(id) { { quantity: urls.cart_item_path(id), remove: urls.cart_item_path(id), ... } })
def bump(change) = (load; run(:order, @order.bump(change)))

in [ :order, :changed ] then run(:items, @items.apply(payload))
in [ :order, :contents ] then run(:totals, @totals.contents(payload))
in [ :order, :saved ] then run(:saved, @saved.stash(payload)); notice @say[:saved]
in [ :order, :undo_pending ] then @undo_pending = payload; @patches.update(@dom.undo_id, undo_html(payload))

# the portal page: its own links, ten seconds; the outputs its rows never offer are grounded
@order = Features::OrderLines.new(cart_id:, products: ..., undo_lines: CartItem, undo_window: Store::PORTAL_UNDO_WINDOW,
                                  links: ->(id) { { quantity: urls.portal_line_path(id), remove: urls.portal_line_path(id) } })
GROUNDED = %i[order.row_added order.row_changed order.row_removed order.saved order.line ...]

Neither page’s other arms changed, except that lines and undo became order. The two pages differ in links, window, totals (cart totals with promo and shipping against order totals with volume tiers) and what each does with saved and line; the feature knows none of it.

The drawing opens it, and the suite proves its inside ran

Drawing now takes a built screen, since it needs the parts’ classes to know which are compositions, draws a feature as a subgraph with its inner arms, and sends an out arm’s edge to the feature node. The _ pattern is read by the structural check as “every remaining declared output of that part”, so coverage still holds per output. The trace records a feature’s inner hops under the feature’s class, so the running check covers the inside too. The portal, from its arms:

flowchart LR
  screen[[Screens::Portal]]
  subgraph order [order: OrderLines]
  order_lines[lines]
  order_undo[undo]
  end
  catalog[catalog]
  add_line[add_line]
  totals[totals]
  flow[flow]
  items[items]
  order -- changed --> items
  order -- rows --> screen
  order -- contents --> totals
  order -- undo_pending --> screen
  catalog -- rows --> screen
  add_line -- added --> screen
  totals -- summary --> screen
  flow -- step --> screen
  flow -- form --> screen
  flow -- blocked --> screen
  flow -- reference --> screen
  order_lines -- removed --> order_undo
  order_undo -- pending --> order
  order_lines -- every other output --> order
  order_undo -- every other output --> order

What the linter had to learn

Two small things, both precision rules with tests, and both leave V05 and V06 at the same scores. out and collect joined run on the list of wiring calls, so a feature’s arms are wiring and not handled data under ALA R11. And the public-surface count now leaves out parts along with initialize: it is the paradigm’s message, what a drawing or a coverage test reads, not an input a page sends. Counting it had made the feature’s twelve inputs thirteen, which is the kind of thing the count is for and the kind of thing it shouldn’t be counting.

What it scores

V06V07
ala_lint default / --strict / --super-strict100 / 100 / 100100 / 100 / 100
Rules met under --super-strict (of 10 checked)1010
Functions with no scored finding324 / 324339 / 339
Declared outputs never routed under the full suite00, the feature’s inside included
Layers declared in .ala_lint.rb56
Integration tests5760
Browser tests (Cuprite)55
Cart screen, lines145143
Non-blank lines in app/1,9812,067
Familiarity54

What it costs

Later: defects, linter changes and the clone check (2026-10-19)

An experiment that made the same requirement changes to conventional and ALA variants exposed five defects here, now fixed with regression tests: undo over Turbo didn’t put the row back or reprice, removing a line kept its gift wrap, the portal never said “Item restored”, the checkout button’s total never updated, and a payment’s outcome could be lost during the Pay redirect (the page now asks for it once its stream is connected).

A Prism upgrade had made the linter skip drawing.rb and wiring.rb. Read again, Drawing tested respond_to?(:parts), now is_a?(Wiring), and its edge labels are declared in Drawing::INHERENT_LABELS. Wiring now declares parts itself, and the linter reads a paradigm’s messages from the paradigm’s code; the paragraph above about counting parts describes the earlier linter.

Then a clone check joined the linter (R7, scored from --strict). It found nine pieces of logic written twice, all now shared: ProgrammingParadigms::StepRecord (the step flow the checkout and the portal keep in a record), Rules::HeldProducts (held entries and their product rows), Rules::LineRequest, CartItem#to_line and Rules::Pricing.summary. The pages build the held products and the step record and hand them in, as V05 does. One accepted line remains: CheckoutFlow#show is a pure delegation to the step record, reported as a pass-through. Now: 100 at every tier, 10 of 10 rules, 370 functions, one accepted line; 86 integration tests (23 for the new abstractions) and 7 browser tests.

The same concepts now carry different names in the three Ruby variants, because each variant had its own copy extracted separately on the same day: the persisted step flow is PersistedSteps in V05, Wizard in V06 and StepRecord in V07; the product row is LineRow in V05 and V06 (V06’s with a product cache) and part of HeldProducts in V07; and Pricing.summary is written in all three. The names and APIs are left as they are for now, so a reader comparing the variants meets the same idea three ways.

Later: outside change as a paradigm (2026-10-21)

Before, every change made elsewhere had its own machinery. The catalogue’s three LiveUpdate sinks rendered the product list’s row and broadcast it, and the checkout rendered a stock badge for every page that shows one. The composition making the change knew every view (R1, R10). Only a purchase published stock, so a staff stock edit at /products never reached an open cart or the portal. And the portal received the product list’s row, edit and delete buttons included, because the two shared a DOM id.

ProgrammingParadigms::ChangeFeed makes it one paradigm, built once in the layer Spray keeps for paradigm interfaces (§2.2). A Publish sink is configured with a topic, a kind and a lambda that picks the fact out of the payload. A Subscription is a part a page places, configured with the topic, the kinds it listens to and the page’s live URL, with one output per kind. The catalogue’s save now publishes stock as well as the change, and the cart wires the kind it listens to:

# the catalogue: a staff save publishes the product's stock too
in [ :records, :updated ]
  # ...
  run(:publish_changed, @publish_changed.push(payload))
  run(:publish_stock, @publish_stock.push(payload))

# the cart: a feed of one kind, and its arm
@feed = ProgrammingParadigms::ChangeFeed::Subscription.new(topic: Store::CATALOG_TOPIC, kinds: %i[stock], url: urls.live_cart_path)
in [ :feed, :stock ] then @patches.replace_all(@dom.stock_selector(payload[:product_id]), @badge_html.(payload))

What travels is a fact keyed by identity ({ product_id:, stock: }, { cart_id: }), never HTML, and ChangeFeed.encode and decode are the one format both ends share. Delivery is built once: ChangeFeed::Channel streams a signed topic, the change-feed Stimulus controller posts each fact of a listened kind to the page’s live URL, and one concern on four controllers (ChangeFeedRefresh) hands it to the screen’s live(message). The page answers with the patches its feed arms make, where V06 morph-refreshes the whole page. The arms land on the page rather than on a part, because a page rebuilt per request reads current values through its tables and has no state part to tell.

LiveUpdate is gone, and so are the pages’ turbo_stream_from tags. The two gaps closed: a staff edit now reaches open carts and the portal, and the portal renders its own catalogue row. The price is one request per fact per open page, where Turbo pushed the rendered HTML directly, and four more ports, one per page’s live. The linter’s new R11 reading found two step templates chosen by an interpolated name (render "portals/#{@s.step}"), which now read a literal STEP_VIEWS table, and the move itself drew two R11 findings, row lambdas that looped over a lookup, now a collection render. Now: 100 at every tier, 10 of 10 rules, 384 functions, one accepted line; 100 integration tests and 9 browser tests. How this differs from Turbo’s broadcasts_to is in the Rails post.

What it shows

The Features layer is a class with the same wire a page has and one word for what leaves it. That is the finding, and it is the same one the Elixir side reached: a story in V51 is a module of plain functions with an out it is handed. V07 is the leading edge in Ruby at familiarity 4, the place to go when a page outgrows V06; V05 stays the fullest expression, since its kept compositions are the one idea V07 declines. For a page under Spray’s 500-line mark, V06 is still simpler.

The code is in ala_variants_ruby/v07-plain-features.

← all posts