V47, typed story maps: Spray's features, typed ports, and a diagram that runs
V46 added Spray’s Features layer to the clause-wired V45. V47 adds it to the other zero-hop design, V39-max, whose wiring is a value: one bindings map per page. It also brings in the idea from V42 that its circuit never carried past 85 points: every port has a type, and the wiring is checked and drawn from the same value that runs.
The stories are V46’s: EditCart, UndoRemoval, SaveForLater, KeepWishlist and CheckOut on the cart page, and EditOrder, BrowseCatalog, SubmitOrder and UndoRemoval on the portal. So are two other changes. The coded state modules are ZeroCoupled.State now, and a generic record form replaces FormComponent. What differs is how the wiring is held.
A story’s wiring is a map
Each story has a bindings map: its diagram as a value. Sources are its parts’ ports and its own inputs ({:in, port}). Targets are binding kinds from V39-max’s binder, plus two new ones: {:out, port} sends a payload out of the story, and {:to, story, port} (on the page) delivers one to a story’s input.
def bindings(window_ms) do
%{
{:in, :capture} => [{:input, :undo, &Undo.capture/2}],
{:in, :expire} => [{:input, :undo, &Undo.expire/2}],
{:undo, :captured} => [{:set, :pending, true}, {:start_timer, :undo, window_ms, :expire}],
{:undo, :restored} => [{:stop_timer, :undo}, {:set, :pending, false}, {:out, :restored}],
{:undo, :expired} => [{:set, :pending, false}, {:out, :expired}]
}
end
The page is the root story. Its map has 16 entries on the cart page, almost all of them links between stories:
{:edit_cart, :removed} => [{:to, :undo, :capture}],
{:undo, :restored} => [{:to, :edit_cart, :receive}, {:flash, :info, "Item restored"}],
{:wishlist, :ids} => [{:to, :edit_cart, :wishlist_ids}],
{:check_out, :pay_requested} => [{:to, :edit_cart, :request_checkout}]
One Binder runs both levels in the page process. A part’s output follows its story’s map, {:out, port} hands it to the page’s map, and {:to, story, port} hands it down into another story. Like V46, a story’s timer and its async task report back to its own input ports, so the page has one generic clause for each.
Every port typed, checked when a page mounts
Every state module already declared types for its ports (removed: :item, summary: :summary). V47 makes them load-bearing:
- A wire joins two ports of one type.
edit_cart.removed (item) → undo.capture (item)passes; wiring the summary tocapturewould not. - A
Callinstance says what it accepts and what it answers.AddLineturns aproductinto anitem, and aproduct_quantityinto anitem_quantity. So the wishlist’staken(a product) can go through it to the cart’sreceive(an item), and the catalog’srequestedcan go to the order’sadd. - A plain function’s answer type is written in its binding:
{:via, &Carts.list_items/1, :items, [{:input, :cart, &Cart.load/2}]}. - Sinks have types too. A stream takes
:row_change, a form:changeset, a patch:step, a redirect:url. - Coverage is part of the check. Every output is bound or grounded, every declared input is bound, and a binding can’t hold an anonymous function.
Binder.mount/2 refuses an unsound composition before the page runs it, and a test asserts Diagram.problems(CartPage.composition(1)) == [] for each page. A fixture with one of each mistake shows the check names them:
gappy: in.mounted (cart_id) → lines.add takes item, not cart_id
gappy: lines.summary (summary) → a stream takes row_change, not summary
gappy: lines.rows is neither bound nor grounded
page: gappy.total is neither bound nor grounded
The diagram is drawn from what runs
Diagram.mermaid/1 draws a page’s stories and the links between them from the composition the page mounts, and Diagram.mermaid_story/2 draws one story’s insides. This is the cart page, generated, not drawn by hand:
flowchart LR
check_out["check_out<br/>CheckOut"]
edit_cart["edit_cart<br/>EditCart"]
saved["saved<br/>SaveForLater"]
undo["undo<br/>UndoRemoval"]
wishlist["wishlist<br/>KeepWishlist"]
check_out -->|"pay_requested → request_checkout"| edit_cart
edit_cart -->|"checkout_requested → pay"| check_out
edit_cart -->|"checkout_started → start"| check_out
edit_cart -->|"line → toggle"| wishlist
edit_cart -->|"removed → capture"| undo
edit_cart -->|"saved → stash"| saved
edit_cart -.->|"saved"| page_flash["page: flash"]
edit_cart -.->|"summary"| page_show["page: show"]
edit_cart -->|"summary → summary"| check_out
page -->|"mounted → mounted"| edit_cart
page -->|"mounted → mounted"| check_out
saved -.->|"count"| page_show["page: show"]
saved -->|"moved → receive"| edit_cart
saved -.->|"moved"| page_flash["page: flash"]
ui -.->|"tab"| page_show["page: show"]
undo -->|"expired → confirm_removal"| edit_cart
undo -->|"restored → receive"| edit_cart
undo -.->|"restored"| page_flash["page: flash"]
wishlist -->|"added_to_cart → receive"| edit_cart
wishlist -.->|"count"| page_show["page: show"]
wishlist -->|"ids → wishlist_ids"| edit_cart
Spray’s diagram is the source and the code is generated from it (§2.5.1). Here the value is the source and the diagram is generated from it, which is the other way round, but it holds the property that matters: the picture can’t drift from what runs.
What it scores
| V39-max | V47 | |
|---|---|---|
| Full checklist, by hand (2026-10-02 readings) | 99 | 100 |
ala_lint default / --strict / --super-strict | 100 / 100 / 99 | 100 / 100 / 99 |
Checklist rules met under --strict (of 10 checked) | 9 | 10 |
| Message hops per cross-feature effect | 0 | 0 |
| Tests (shared acceptance tests included) | 91 | 95 |
| Mean / median time per test | 5.8 / 1.4 ms | 7.7 / 2.3 ms |
Non-blank lines in lib/ | 4,148 | 4,851 |
| Familiarity | 3 of 5 | 3 of 5 |
As with V46, the walk finds nothing to deduct, and super-strict’s one finding is the shared Cart aggregate every storefront variant judges the same way. The linter needed two corrections to read V47 fairly, both now in it: an {:out, port} binding counts as an output a story sends, and a paradigm’s own diagnostics (a checker’s messages, a diagram’s labels) aren’t product words.
What it costs
- Two paradigms to learn. The binder’s kinds, now including
outandto, and the type rules. V39-max already cost a point of familiarity for its binder, and V47 doesn’t lose another, but it doesn’t earn one back either. - A check on every mount. It’s cheap: checking the cart page’s whole composition takes about 0.04 ms. It runs at mount, where V42 had it, because the composition depends on configuration built there. The tests are slower than V39-max’s (a median of 2.3 ms against 1.4), but not because of the check, and I haven’t traced where the rest goes.
- More code. About 700 more non-blank lines than V39-max: eight stories, the checker and drawer (250 lines), and the record form.
V46 or V47
They’re the same design held two ways. V46’s wiring is clauses: familiar Elixir, checked by reading clause heads, with no picture. V47’s is values: a vocabulary of binding kinds, checked by type at mount and drawn from what runs. Both score 100 with zero hops. V47 is the closer reading of Spray, who wants the diagram to be the source and port types to be a paradigm’s. V46 is easier to adopt.
Rescored 2026-10-03: 98
Spray’s §6.17.2 is now read strictly under R10. Checkout receives the whole cart (%Cart{}) to use three facts of it; the checklist already named that as missing R10, and every walk had passed it (−1). And the storefront’s cart, which carries promo, gift-wrap and shipping state, is the struct the portal’s order lines are built on: one use case’s data in a struct another use case shares, which Spray says an identity “should not be used as the carrier of” (−1). The small fix V46, V48 and V49 took wasn’t applied to V47. 100 becomes 98. Lint under --strict is 99, meeting 9 of 10 rules: the linter now scores the shared aggregate from --strict up.
Rescored 2026-10-03 (later): 100
The shared entity is gone. The portal’s OrderLines has its own struct and pricing (subtotal, volume tier, shipping), and builds, like the storefront’s cart, on a new Lines domain abstraction: plain functions over a list of stored order lines (find, add, change a quantity, remove, set stock), holding no prices, codes or flags of any use case. The cart lost set_discount/2, which its own doc said was “added for the portal consumer”. With checkout already getting only {cart_id, items} (applied to V47 today too), R10 is met, and 98 becomes 100. Lint under --strict is 100, meeting 10 of 10 rules. The linter needed one correction to read it: a story that only builds the cart (Cart.new) creates an instance, which a Spray feature does (§2.2), and doesn’t know its data, so it no longer counts as a reader.
The code is in ala_variants_elixir/v47-typed-story-maps.