V05 in Rails, a shared feature: one order-lines feature placed by two pages

October 10, 2026 · ALA · V05 · Ruby · Rails · features · checklist

Spray adds a Features layer when an application gets too big for one wiring: a 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 Elixir side has had it since V46, and V51’s UndoRemoval story is placed by both the cart and the portal pages. On the Rails side, V04’s cart and portal screens each built a CartLines and an Undo and wired the same five wires between them and their store. V05 moves those into one feature that both pages place.

The feature

module Features
  class OrderLines
    include Foundation::Ports
    output :items, ProgrammingParadigms::RequestResponse
    output :products, ProgrammingParadigms::RequestResponse
    output :changed, ProgrammingParadigms::DataFlow
    output :fetch, ProgrammingParadigms::DataFlow
    output :rows, ProgrammingParadigms::DataFlow
    output :row_changed, ProgrammingParadigms::DataFlow
    output :contents, ProgrammingParadigms::DataFlow
    output :undo_pending, ProgrammingParadigms::DataFlow, many: true
    # ... fourteen outputs in all

    input(:bump, ProgrammingParadigms::DataFlow) { |change| @lines.input_port(:bump).push(change) }
    input(:undo, ProgrammingParadigms::Event) { @undo.input_port(:restore).send_event }
    input(:lines, ProgrammingParadigms::RequestResponse) { |query| @lines.input_port(:lines).request(query) }
    # ... thirteen inputs in all

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

    def initialize(cart_id:, links:, undo_lines:, undo_window:)
      @lines = DomainAbstractions::CartLines.new(cart_id:, links:)
      @undo = DomainAbstractions::Undo.new(lines: undo_lines, cart_id:, window: undo_window)

      @lines.wire_to(@undo, from: :removed, to: :capture)
      @lines.on(:products) { |ids| ask(:products, ids) }      # a request passed up to whoever the page wires
      @lines.on(:row_changed) { emit(:row_changed, _1) }
      @undo.on(:pending) { emit(:undo_pending, _1) }
      @undo.on(:restored) { |id| emit(:fetch, id); emit(:restored, id) }
      # ...
    end
  end
end

Inside, a value and an undo are wired to each other. Outside, ports. The Foundation’s wire_to and on are the whole mechanism; ask and emit inside the feature forward an inner port to an outer one, including a request/response output, so the feature asks its page’s product index without knowing it. There is no other public surface beyond parts, which the drawing and the coverage test read.

Two pages place it

# the cart page, kept across requests (V04), with the storefront's links and a five-second window
@order = Features::OrderLines.new(cart_id:, undo_lines: CartItem, undo_window: Store::UNDO_WINDOW,
                                  links: ->(id) { { quantity: urls.cart_item_path(id), remove: urls.cart_item_path(id), ... } })
@order.wire_to(@items, from: :items, to: :lookup)
@order.wire_to(@items, from: :fetch, to: :fetch)
@items.wire_to(@order, from: :found, to: :arrived)
@order.wire_to(@totals, from: :contents, to: :contents)     # CartTotals, with promo and shipping
@order.wire_to(@saved, from: :saved, to: :stash)
@order.wire_to(patch(:replace, ->(row) { dom.cart_line_id(row[:id]) }, line_html), from: :row_changed)

# the portal page, built per request, with the portal's links and a ten-second window
@order = Features::OrderLines.new(cart_id:, undo_lines: CartItem, undo_window: Store::PORTAL_UNDO_WINDOW,
                                  links: ->(id) { { quantity: urls.portal_line_path(id), remove: urls.portal_line_path(id) } })
@order.wire_to(@totals, from: :contents, to: :contents)     # OrderTotals, with volume tiers
@flow.wire_to(@order, from: :lines, to: :lines)             # the submit flow asks it for the lines

The two pages differ in links, window, totals, and what each does with saved and line: the cart wires them to saved-for-later and the wishlist; the portal leaves them open, listed in the wiring test as grounded on purpose. The feature knows none of that. The cart’s long-lived composition keeps the feature between requests exactly as it kept the two parts, and the portal’s per-request screen loads it before each input exactly as before. Neither execution model changed.

The drawing walks in

Foundation::Ports#parts is empty for a leaf and the feature’s two parts for the feature, so the drawing generator draws a feature as a Mermaid subgraph with its own wires inside, and the wiring test checks that every inner output is wired. Both run on the built object graph. The portal:

flowchart LR
  screen[[Screens::Portal]]
  subgraph order [order: OrderLines]
  order_lines[lines: CartLines]
  order_undo[undo: Undo]
  end
  catalog[catalog: Records]
  add_line[add_line: AddLine]
  totals[totals: OrderTotals]
  flow[flow: SubmitOrder]
  products[products: ProductIndex]
  items[items: CartItemsStore]
  order -- items → lookup --> items
  order -- products → lookup --> products
  order -- changed → apply --> items
  order -- adding → add --> items
  order -- fetch → fetch --> items
  order -- rows --> screen
  order -- contents → contents --> totals
  order -- undo_pending --> screen
  order_lines -- removed → capture --> order_undo
  order_lines -- items --> order
  order_lines -- products --> order
  order_lines -- changed --> order
  order_lines -- rows --> order
  order_lines -- row_changed --> order
  order_lines -- contents --> order
  order_undo -- pending --> order
  order_undo -- restored --> order
  catalog -- rows --> screen
  add_line -- added --> screen
  totals -- summary --> screen
  flow -- lines → lines --> order
  flow -- step --> screen
  flow -- form --> screen
  items -- added → arrived --> order
  items -- found → arrived --> order

An inner output wired to a forwarding block lands on the feature’s box, the way an output wired to a block on a screen lands on the screen. A few edges are left out here for room.

Forwarding, a running trace, and the checkout kept

Added 2026-10-11. Three more things went into this variant rather than a V06.

Forwarding. The feature’s twelve on { emit } lines became two. Foundation::Ports#forward wires each of a part’s outputs to a block that delivers on the feature’s output of the same, or a renamed, name, through the same path emit and ask use, so a request/response output is answered by whoever the feature is wired to:

forward(@lines, :items, :products, :changed, :adding, :rows, :row_added, :row_changed, :row_removed, :contents, :saved, :line)
forward(@undo, pending: :undo_pending)

The wiring as it ran. V51B records every hop a page routes under its test suite and fails if a declared output never routed. The Ruby variants have the built graph as objects, so V05’s wiring test could already prove every output is wired. Nothing proved every wire carried something. Now Foundation::Trace is a table of hops, counted by the sender’s class, the output, the class of what it reached and the input, filled by the Foundation’s deliver while a test run has it on. After the suite, the drawing generator draws each screen with the wires the trace saw solid and the rest dotted, into docs/diagrams/running/, and the run exits non-zero if any wire never carried anything and the run was the whole suite.

Its first run reported four wires. One was a test gap, the cart’s wishlist.dropped: no test took a wishlisted item off from its cart line, and one does now. Three were a design finding: the checkout wired its CartLines value’s write ports to the lines store, and the checkout only reads the lines, so those wires could never fire. They are gone, and the ports are listed as grounded in the wiring test. V51B’s first run found the same kind of thing, which is the argument for the check.

The match is by class, not by instance, so a wire that carried something in one screen counts for the same wire in another, and a domain test’s hops count too. That is coarser than V51B’s per-page hops and precise enough to find what it found; the structural drawing and the wiring test stay per instance, and the two reports are read together.

The checkout, kept. V04 kept the cart and left the checkout per request because its payment ran in a job that rebuilt the screen. LongLived registries now have names, PushLater enqueues a push naming the registry, and the job delivers with LongLived.named(registry).with(key). In the web process the job finds the kept composition; in a separate job process it builds one, which reloads from the stores, delivers, and bumps the stamp so the web process reloads on its next request. The Checkout and Order models bump the cart’s stamp like the line models, and the checkout’s controller renders inside the composition’s turn. The portal stays per request on purpose: it is the demonstration that the same feature serves a composition that is rebuilt.

Two linter findings on the way, both fixed rather than accepted: the job read Rails.configuration to find its registry (ALA R9, an endpoint), which is why the registries are named on LongLived itself; and two ifs inside the checkout controller’s wiring blocks (ALA R11), which are its redirect-or-render choice and moved to private methods. One accepted: the registries’ table is class-level state in the execution model, listed with its reason.

What it scores

V04V05
ala_lint default / --strict / --super-strict100 / 100 / 100100 / 100 / 100
Rules met under --super-strict (of 10 checked)1010
Functions with no scored findingall268 / 268
Accepted lines (--list-accepted)69
Wires that never carried anything under the full suitenot known0
Layers declared in .ala_lint.rb56
Integration tests6670
Browser tests (Cuprite)55
Cart screen, lines160157
Non-blank lines in app/2,2122,345
Familiarity33

The build’s one finding was in the drawing generator, not the feature: it asked a part respond_to?(:parts) to decide whether to walk into it, duck typing to a peer’s own message (ALA R9). Giving every ported object a parts message in the Foundation removed it. The three new tests wire fakes to the feature’s ports and run it without a store: a removal is held inside the feature and undo asks the page’s store for the line back; the same feature carries a page’s own links; a request for the lines passes through to the value.

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). It found three pieces of logic written twice here, and each is now one abstraction: Rules::LineRow (a held line shown as its product, with the fields and links the page chooses), ProgrammingParadigms::PersistedSteps (the step flow both the checkout and the portal keep in a record), and Rules::Pricing.summary (subtotal, discount, shipping on the subtotal, total). The pages build the row and the steps and hand them in. No accepted line was added (still nine). The same day CartLines#find was written def find(id) = … or raise …, and Ruby attaches the or raise to the method definition, so a line it didn’t hold came back nil instead of raising; it is bracketed now, with a test. Later that day the fixes for the defects found in V07 were ported here, each with a test that failed first: gift wrap now clears on removal, the portal says “Item restored”, the checkout button’s total is patched with every change, and a page waiting on a payment asks for the outcome once its stream is connected. (V05 already put a restored row back over Turbo.) Now: 100 at every tier, 10 of 10 rules, 281 functions; 86 integration tests 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)

Until now a change made elsewhere reached open pages through LiveUpdate. The screen that made the change rendered a product row or a stock badge and broadcast it on the catalog stream, and each page caught it by DOM id or class. So the publisher knew every view it reached (R1, R10), and anything it didn’t target never updated. A staff stock or price edit at /products reached the product lists and no open cart or portal. And because the portal’s catalogue row had the same DOM id as the /products row, a staff edit replaced it with the staff row, Edit and Delete buttons included.

ProgrammingParadigms::ChangeFeed replaces it. It is the checklist’s “live subscription port”: outside change as one programming paradigm, in the layer Spray keeps for paradigm interfaces (§2.2), with the observer inside the paradigm, where “the subscriber does not know the publisher” (§4.4.2). The screen that makes a change wires an output to a Publish sink configured with a topic and a kind. A page places a Subscription configured with the topic and the kinds it listens to, and wires each kind like any part’s output:

# the checkout: a purchase's stock levels go to a sink
@settle.wire_to(ChangeFeed::Publish.new(topic: Store::CATALOG_TOPIC, kind: :stock, fact: ->(level) { level }), from: :stock_changed)

# the cart: a feed of two kinds, wired into the feature
@feed = ChangeFeed::Subscription.new(topic: Store::CATALOG_TOPIC, kinds: %i[stock product])
@feed.wire_to(@order, from: :stock, to: :product)
@feed.wire_to(@order, from: :product, to: :product)

What travels is a fact, a kind and identity keys ({ product_id: }, { product_id:, stock: }, a cart’s payment outcome), as JSON in a <turbo-stream action="change_feed"> on Turbo’s own stream. It carries no markup. A Rails page is not a process, so the paradigm’s browser half (change_feed_controller.js) posts a fact the page listens to back to the page’s own live URL, and the page’s composition answers with what changed: patches on the cart, the outcome on the checkout, the lists drawn again on the catalogue and the portal. The kept cart is already current when the fact arrives, because the change’s commit bumped its stamp first.

LiveUpdate, its three rendered broadcasts and the screens’ render lambdas for them are gone. CartLines, SavedItems and Wishlist gained a product input (the line asks for its product again and reprices), which the feature forwards. The staff-edit gap closed with one kind and one wire on the cart, and the portal no longer receives the staff row. The price is a round trip per fact per open page, where LiveUpdate rendered once and sent the HTML to everyone. A forged fact only makes a page look again through its tables. The linter’s new R11 reading also found three step templates chosen by an interpolated name; they read literal STEP_PARTIALS tables now. Now: 100 at every tier, 10 of 10 rules, 303 functions, ten accepted lines (none for the paradigm; the tenth is a stamp on Product, from a 2026-10-19 fix for kept carts showing an old price that this post didn’t record); 108 integration tests, 14 of them for the paradigm, and 9 browser tests. How this differs from Turbo’s broadcasts_to is in the Rails post.

What it shows

Against the Elixir side: V51’s shared story was the undo alone, and editing was two stories; V51B now shares the editing too, the way V05 does. The thing that made it possible in Ruby is V03’s pure core. A value with ports can be wired inside a feature and still be asked by a page’s flow; a domain abstraction that owned its model could not have been placed by two pages with different stores and windows. The Features layer in Rails is a class with ports, which is to say nothing new, and that is the finding.

The code is in ala_variants_ruby/v05-shared-feature.

← all posts