namo 0.22.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6342f1cab3b5811a97d92be8ef7ba34a81191bd97a6ee2c606f8adc7d9a0d47
-  data.tar.gz: ce7db23d2907e33a80d1e263b4b9987645a6c1c47979b7f3311bf519d8f9e738
+  metadata.gz: d07dec8cde3d61366ec26720be42067c0fa10deb6aa1fd37977bf69ba16aa802
+  data.tar.gz: c355e980ff842ddc90d6a3873e98bb7185fb788f44f610c18ace363059136e6f
 SHA512:
-  metadata.gz: 5c6c26eda0a637af215eef9cab0fe369769af3e945b3a1cf980788bd34be97abeefb3cf29fb208012556c5df9e46c212c9476dc222b0f3917404c7db3003f21a
-  data.tar.gz: f71fd3ed7b8e8068b55fbb8379cd361c91c84ca1cb4fe823ff72af9fe1c9b8e1247468fb9fd818aa865cac709aa2d22e63f2c866030cacee22bf25c5930e7758
+  metadata.gz: 17ac2640764b18b17521af477f71b0e5419d24d68a35ce0a7fc79acd963f5e9210331b39ca04a242780037e1a39558bd8fd7079146331b13068f80f811da6fd9
+  data.tar.gz: b4ad7c11375029c45e9b00f2769368c8b48082a965105c95a9b4d23c86a81a24af15107695535a08ea78fa548fc733c84a6ac0df13635a089c4da1297cee1ed2

data/CHANGELOG

@@ -1,6 +1,17 @@
 CHANGELOG
 _________
 
+20260627
+0.23.0: + Namo::Formulary — A formulary is a reusable body of derived dimensions a Namo instance may draw upon.
+
+1. + lib/Namo/Formulary.rb: + Namo::Formulary, an empty marker module. A module includes it to brand itself a formulary; attach raises ArgumentError for an untagged module, so an ordinary module of helpers can't be mistaken for a body of derivations.
+2. ~ lib/Namo/Formulae.rb: + attach(modul), aliased as << — after the marker guard, extends a single memoised inert host (@host ||= Object.new) with the module and stores each of its public_instance_methods(false) as a Method bound to that host, then returns self. One host per Formulae across all attaches, so the bound Methods share a self-free receiver and a formulary method can't shadow Namo's API. No other change: derive, key?, required_parameter_count, keys, merge/dup/reject, and ==/eql?/hash are the 0.22.0 store-only methods, and they handle the formulary methods because the formulary methods are now store entries.
+3. ~ lib/namo.rb: + require of Namo::Formulary; + Namo#attach(modul), aliased as << — raises ArgumentError naming the collision if a formulary method's name collides with a data column (intent/blast-radius: you didn't type the module's names, and it could clear several columns), else forwards to @formulae.attach and returns self. + the class-include channel: initialize calls a private attach_included_formularies that scans self.class.ancestors.reverse and routes each tagged module through attach (same guard, same host; reverse so most-recent-include wins, matching MRO). Collection#initialize calls super, so it participates harmlessly. Collection defines its own <<, so its member-add is unaffected and a plain Namo's << attaches a formulary. Separately and additively, []='s formula branch widens from when Proc to value.respond_to?(:call), so a directly-assigned Method or lambda registers as a formula rather than broadcasting per-row; arrays are unaffected. derived_dimensions, ===/eql?/hash, and requires_arguments? are unchanged from 0.22.0 — formulary methods are store keys, so the existing keys-based forms already count them.
+4. + test/Namo/Formulae_test.rb: + a "formulary tier" describe — attach returns self, rejects an untagged module, and copies the public methods into the store (excluding a private helper); a single shared host across attaches (bound Methods share a receiver); << attaches as attach does; key?, required_parameter_count, and derive resolve the copied methods; most-recent-wins on re-attachment; carry-through through dup/reject/merge.
+5. ~ test/namo_test.rb: + a "formularies" describe (runtime attach) — attach (returns the Namo, rejects untagged); derived_dimensions (copied names, private helper absent, vanilla Namo empty); resolution through values/Row/selection; two-arity windowing and the missing-namo raise; a parameterised method omitted from bulk and raising bare, materialising through a row-scoped wrapper; re-attachment; an instance []= formula shadowing a formulary method; attach raising on a formulary/data-name collision; carry-through through selection, projection, and concatenation; projection materialising-and-dropping a formulary name; === against a vanilla Namo and against the same names via []=; << attaching as attach does. + a "formularies via class include" describe — included methods as derived dimensions (private absent), resolution, most-recent-include wins (MRO), raise at construction on a data collision, and the build-time-vs-after contract (an instance built before a later include sees it only via attach). ~ the #[]= polymorphic dispatch describe gains a Method and a lambda registering as formulae (the array-broadcast regression already present).
+6. ~ README.md: + a "Formularies" subsection under Formulae (attach and the marker, private-hides-helpers, the copy-into-the-store / snapshot model, the raise on a data collision, materialise-and-drop, carry-through, the bare-name/memoisation forward-note); the Polymorphic []= section now says "a callable" (proc, lambda, or Method) rather than "a proc". ~ COMPARISON.md: + a "Formularies" row. ~ ROADMAP.md: + the 0.23.0 release entry; current-state bumped to 0.23.0; the 2.x "module-based formula libraries", "Namo#=== revision", and marker-vs-implicit notes annotated as shipped/decided at 0.23.0, with bare-name bodies remaining 2.x.
+7. ~ Namo::VERSION: /0.22.0/0.23.0/
+
 20260626
 0.22.0: + Formulae#derive — move formula invocation out of Row#[] and into Formulae. [] keeps its meaning (the stored callable, as at 0.21.0); the new derive(name, row, namo, *arguments) resolves a named formula to its value. derive over call: the receiver is the collection, not the callable, so the verb says the collection derives a value via the named rule rather than borrowing Proc#call's "invoke the receiver"; and the result is whatever the proc returns, not necessarily numeric, which a neutral verb leaves open. Indexing a Formulae is storage access, not a Namo operation, so [] returning the callable carries no inconsistency with the dimension-value [] of Namo and Row — different domains, same spelling. Behaviour-preserving at the usage level: row[:revenue], namo[:x] = formula, values, and selections are unchanged.
 

data/README.md

@@ -716,9 +716,65 @@ prices[:sma_close_20] = proc{|row| row[:sma, :close, 20]}
 prices[:date, :sma_close_20]   # materialises per the usual projection rule
 ```
 
+#### Formularies
+
+A *formulary* is a reusable body of derived dimensions — a module whose public instance methods are formulae. A Namo attaches a formulary, and from then on those methods resolve as derived dimensions through the same interface as `[]=` formulae. The methods take `row` (and `namo`, and any further parameters) exactly as a `[]=` formula does:
+
+```ruby
+module OrderFlow
+  include Namo::Formulary
+
+  def signed_volume(row)
+    row[:buys] - row[:sells]
+  end
+
+  def cum_delta(row, namo)
+    namo[date: ..row[:date]].values(:signed_volume).sum
+  end
+
+  private
+
+  def net(row)
+    row[:buys] + row[:sells]
+  end
+end
+
+flows = Namo.new([
+  {date: 1, buys: 60, sells: 40},
+  {date: 2, buys: 80, sells: 120},
+  {date: 3, buys: 75, sells: 75}
+])
+
+flows.attach(OrderFlow)
+flows.values(:signed_volume)   # => [20, -40, 0]
+flows.values(:cum_delta)       # => [20, -20, -20]
+flows.derived_dimensions       # => [:signed_volume, :cum_delta]
+```
+
+`<<` is the operator form of `attach`, so `flows << OrderFlow` reads the same and chains: `flows << OrderFlow << Scoring`.
+
+A module brands itself a formulary by including `Namo::Formulary`. The marker is mandatory — `attach` raises `ArgumentError` for an untagged module, so an ordinary module of helpers can't be mistaken for a body of derivations. Within a formulary, the public methods are the derivations and `private` methods are helpers: `net` above never appears in `derived_dimensions` and never resolves as a dimension. The separation needs no per-method declaration — public or private says it.
+
+Attaching **copies** the formulary's public methods into the Namo's formula collection — each becomes a stored formula, indistinguishable from one assigned through `[]=`. From there they are `[]=` formulae in everything but how they were defined: they resolve through the same path, carry through the same operators, and obey the same exclusivity rule.
+
+The copy is a *snapshot* taken at the moment of attachment, and this is where a formulary departs from ordinary Ruby. A real `include` (or `extend`) is a live link: its methods resolve through the ancestor chain, so a method added to the module later, a redefinition, or a further module mixed in afterwards are all seen by objects that already include it. `attach` forgoes that — it copies the method set once, so later changes to the module are not reflected on an already-attached Namo. Re-attach to pick them up. (A live-link mechanism may come in a later release; it is not in 0.23.0.)
+
+**Two ways to give a Namo a formulary.** `attach` (and `<<`) adds one to an individual Namo at runtime, as above. Alternatively, `include` the formulary into a `Namo` subclass — `class TradingAnalysis < Namo; include OrderFlow; end` — and every instance picks it up when it is built. The rule that separates them is simple: *the class `include` is honoured once, when each instance is constructed; everything after that is `attach`.* Both copy (snapshot), so a formulary `include`d into the class **after** an instance exists won't reach that instance — `attach` to it, or build a fresh one. A one-off plain `Namo` has no class to `include` into per-instance, so it always takes `attach`. Where both apply, ordinary last-write-wins holds: a runtime `attach` (or `[]=`) overrides a class-included formula of the same name on that instance, and the most-recently `include`d formulary wins among the class's own.
+
+Because each method is copied into the store, the rules already governing `[]=` apply:
+
+- **Most-recent wins.** Attaching a second formulary that defines a colliding name overwrites the first, exactly as a second `[]=` would. Equally, `[]=` and `attach` interleave as plain last-write-wins on a shared name — whichever was applied last governs.
+- **Data collisions raise.** A name is data or derived, never both. If a formulary method's name collides with an existing data column, attaching raises an `ArgumentError` naming the collision rather than silently destroying the data. The reason it raises where `[]=` silently clears: `[]=` names one column at the call site, so replacing it is your explicit intent; a formulary names a whole *module*, so a data collision is a name you never typed — and possibly several columns at once — that you most likely didn't mean to destroy. The same raise guards the class-`include` channel, where it fires at construction. Resolve it explicitly first — contract the column away (`namo[-:signed_volume]`) or rename — then attach.
+- **Materialise-and-drop on projection.** Naming a formulary method in a projection snapshots its values into a data column *and drops the formula*, exactly as for a `[]=` formula: `flows[:date, :signed_volume]` returns a Namo reporting `:signed_volume` as data, not derived, with all access paths agreeing on the stored snapshot.
+- **Carry-through.** Selection, the set and composition operators, and a projection that *omits* the name all keep the formula live, computing against the result's own rows — the carry-through is free, because the formulae are ordinary store entries.
+
+Two Namos that expose the same names — one via `[]=`, one via a formulary — are `===`; a Namo with a formulary attached is not `===` to a vanilla Namo of the same data dimensions.
+
+Formulary methods take `row` explicitly and index it (`row[:buys]`), the same as `[]=` formulae. Resolving bare names inside a method body (`buys` for `row[:buys]`) and memoising derived values on a frozen Namo arrive in a later release; until then a formulary method is a plain function of its `row` (and `namo`).
+
 ### Polymorphic `[]=`
 
-`[]=` dispatches on the type of the value assigned. A proc registers a formula, as above. Anything else broadcasts the value to every row:
+`[]=` dispatches on the value assigned. A callable — anything that responds to `call`, so a proc, a lambda, or a `Method` — registers a formula, as above. Anything else broadcasts the value to every row:
 
 ```ruby
 sales[:status] = 'active'
@@ -732,7 +788,7 @@ sales.values(:revenue)
 
 The two branches mirror the polymorphism `[]` already has on the selection side, where a single bracket call dispatches over exact values, arrays, ranges, procs, and regexes. Rather than introduce a separate `broadcast` or `set_all` method for the scalar case, `[]=` reads the same way for both: `sales[:status] = 'active'` says "set status to active across this Namo," and `sales[:revenue] = proc{…}` says "derive revenue from each row."
 
-The two branches enforce **exclusive storage**: a name is either a data dimension or a derived dimension, never both. Assigning a proc clears any data column of that name; assigning anything else clears any formula of that name. The last write wins, and there is no shadowing:
+The two branches enforce **exclusive storage**: a name is either a data dimension or a derived dimension, never both. Assigning a callable clears any data column of that name; assigning anything else clears any formula of that name. The last write wins, and there is no shadowing:
 
 ```ruby
 sales[:x] = 5                       # :x is a broadcast data value
@@ -744,7 +800,7 @@ sales[:x] = 5                       # :x is now a broadcast data value — the f
 
 Exclusivity ties directly to the inspection vocabulary: a name assigned a scalar shows up in `data_dimensions`; a name assigned a proc shows up in `derived_dimensions`; never in both, so it appears in `dimensions` exactly once.
 
-Only a `Proc` takes the formula branch. An array is a value like any other, so it broadcasts as the per-row value rather than registering as a formula:
+Only a callable takes the formula branch. An array doesn't respond to `call`, so it broadcasts as the per-row value rather than registering as a formula:
 
 ```ruby
 sales[:weights] = [1, 2, 3]

data/lib/Namo/Formulae.rb

@@ -13,6 +13,18 @@ class Namo
       @store[name] = callable
     end
 
+    def attach(modul)
+      unless modul.include?(Namo::Formulary)
+        raise ArgumentError, "not a Namo::Formulary: #{modul}"
+      end
+      host.extend(modul)
+      modul.public_instance_methods(false).each do |name|
+        @store[name] = host.method(name)
+      end
+      self
+    end
+    alias_method :<<, :attach
+
     def derive(name, row, namo, *arguments)
       formula = self[name]
       if collection_scoped?(name)
@@ -83,6 +95,10 @@ class Namo
       @store = store
     end
 
+    def host
+      @host ||= Object.new
+    end
+
     def collection_scoped?(name)
       required_parameter_count(name) >= 2
     end

data/lib/Namo/Formulary.rb

@@ -0,0 +1,6 @@
+# Namo/Formulary.rb
+# Namo::Formulary
+
+class Namo
+  module Formulary; end
+end

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.22.0'
+  VERSION = '0.23.0'
 end

data/lib/namo.rb

@@ -2,6 +2,7 @@
 # Namo
 
 require_relative './Namo/NegatedDimension'
+require_relative './Namo/Formulary'
 require_relative './Namo/Formulae'
 require_relative './Namo/Row'
 require_relative './Namo/Collection'
@@ -78,8 +79,7 @@ class Namo
   end
 
   def []=(name, value)
-    case value
-    when Proc
+    if value.respond_to?(:call)
       @data.each{|row| row.delete(name)} if @data.first&.key?(name)
       @formulae[name] = value
     else
@@ -88,6 +88,17 @@ class Namo
     end
   end
 
+  def attach(modul)
+    collisions = modul.public_instance_methods(false) & data_dimensions
+    unless collisions.empty?
+      raise ArgumentError, "formulary methods collide with data dimensions: #{collisions.inspect}"
+    end
+    @formulae.attach(modul)
+    self
+  end
+
+  alias_method :<<, :attach
+
   def +(other)
     raise_unless_namo(other)
     raise_unless_matching_data_dimensions(other)
@@ -238,6 +249,14 @@ class Namo
     @data = positional_data || data
     @formulae = formulae.is_a?(Formulae) ? formulae : Formulae.new(formulae)
     @name = name
+    attach_included_formularies
+  end
+
+  def attach_included_formularies
+    self.class.ancestors.reverse.each do |modul|
+      next if modul.is_a?(Class) || !modul.include?(Namo::Formulary)
+      attach(modul)
+    end
   end
 
   def values_for(dim)

data/test/Namo/Formulae_test.rb

@@ -208,4 +208,146 @@ describe Namo::Formulae do
       _(Namo::Formulae.new.keys).must_equal []
     end
   end
+
+  describe "formulary tier" do
+    let(:delta) do
+      Module.new do
+        include Namo::Formulary
+        def signed_volume(row); row[:buys] - row[:sells]; end
+        def echo_namo(row, namo); namo; end
+        def scaled(row, namo, factor); row[:buys] * factor; end
+        def windowed(row, namo, *rest); rest; end
+        private
+        def helper(row); row[:buys]; end
+      end
+    end
+
+    let(:untagged) do
+      Module.new do
+        def signed_volume(row); 0; end
+      end
+    end
+
+    let(:attached) do
+      Namo::Formulae.new.attach(delta)
+    end
+
+    describe "#attach" do
+      it "returns self" do
+        formulae = Namo::Formulae.new
+        _(formulae.attach(delta)).must_be_same_as formulae
+      end
+
+      it "raises ArgumentError for a module not tagged Namo::Formulary" do
+        _(proc{Namo::Formulae.new.attach(untagged)}).must_raise ArgumentError
+      end
+
+      it "copies the formulary's public methods into the callable store" do
+        _(attached.keys.sort).must_equal [:echo_namo, :scaled, :signed_volume, :windowed]
+      end
+
+      it "excludes a private helper" do
+        _(attached.keys).wont_include :helper
+      end
+
+      it "binds every attached formulary to a single shared host" do
+        other = Module.new do
+          include Namo::Formulary
+          def momentum(row); row[:buys]; end
+        end
+        formulae = Namo::Formulae.new.attach(delta).attach(other)
+        _(formulae[:signed_volume].receiver).must_be_same_as formulae[:momentum].receiver
+      end
+    end
+
+    describe "#<<" do
+      it "attaches a formulary, the same as #attach" do
+        formulae = Namo::Formulae.new
+        formulae << delta
+        _(formulae.keys).must_include :signed_volume
+      end
+
+      it "returns self for chaining" do
+        formulae = Namo::Formulae.new
+        _(formulae << delta).must_be_same_as formulae
+      end
+    end
+
+    describe "#key?" do
+      it "is true for a formulary method name" do
+        _(attached.key?(:signed_volume)).must_equal true
+      end
+
+      it "is false for a private helper" do
+        _(attached.key?(:helper)).must_equal false
+      end
+
+      it "is false for an absent name" do
+        _(attached.key?(:missing)).must_equal false
+      end
+    end
+
+    describe "#required_parameter_count" do
+      it "counts a row-scoped formulary method" do
+        _(attached.required_parameter_count(:signed_volume)).must_equal 1
+      end
+
+      it "counts a two-arity formulary method" do
+        _(attached.required_parameter_count(:echo_namo)).must_equal 2
+      end
+
+      it "counts a parameterised formulary method" do
+        _(attached.required_parameter_count(:scaled)).must_equal 3
+      end
+
+      it "excludes the splat for a variadic formulary method" do
+        _(attached.required_parameter_count(:windowed)).must_equal 2
+      end
+    end
+
+    describe "#derive" do
+      it "resolves a row-scoped formulary method to its value" do
+        _(attached.derive(:signed_volume, {buys: 60, sells: 40}, nil)).must_equal 20
+      end
+
+      it "resolves a two-arity formulary method with the namo context" do
+        namo = Object.new
+        _(attached.derive(:echo_namo, {buys: 60, sells: 40}, namo)).must_be_same_as namo
+      end
+
+      it "raises when a two-arity formulary method has no namo context" do
+        error = _(proc{attached.derive(:echo_namo, {buys: 60, sells: 40}, nil)}).must_raise ArgumentError
+        _(error.message).must_match(/echo_namo/)
+      end
+
+      it "resolves the most-recently attached formulary on a name collision" do
+        alt = Module.new do
+          include Namo::Formulary
+          def signed_volume(row); 999; end
+        end
+        formulae = Namo::Formulae.new.attach(delta).attach(alt)
+        _(formulae.derive(:signed_volume, {buys: 60, sells: 40}, nil)).must_equal 999
+      end
+    end
+
+    describe "carry-through" do
+      it "preserves attached formularies through #dup" do
+        _(attached.dup.keys).must_include :signed_volume
+      end
+
+      it "preserves attached formularies through #reject" do
+        _(attached.reject{|_name, _| false}.keys).must_include :signed_volume
+      end
+
+      it "carries both sides' formularies through #merge" do
+        other_delta = Module.new do
+          include Namo::Formulary
+          def momentum(row); row[:buys]; end
+        end
+        merged = attached.merge(Namo::Formulae.new.attach(other_delta))
+        _(merged.keys).must_include :momentum
+        _(merged.keys).must_include :signed_volume
+      end
+    end
+  end
 end

data/test/namo_test.rb

@@ -639,6 +639,24 @@ describe Namo do
       _(namo.values(:weights)).must_equal [[1, 2, 3], [1, 2, 3]]
     end
 
+    it "registers a formula when assigned a Method (responds to call)" do
+      calculator = Object.new
+      def calculator.revenue(row); row[:price] * row[:quantity]; end
+      namo = Namo.new([{price: 10.0, quantity: 100}, {price: 5.0, quantity: 200}])
+      namo[:revenue] = calculator.method(:revenue)
+      _(namo.derived_dimensions).must_include :revenue
+      _(namo.data_dimensions).wont_include :revenue
+      _(namo.values(:revenue)).must_equal [1000.0, 1000.0]
+    end
+
+    it "registers a formula when assigned a lambda (responds to call)" do
+      namo = Namo.new([{x: 1}, {x: 2}])
+      namo[:doubled] = ->(r){r[:x] * 2}
+      _(namo.derived_dimensions).must_include :doubled
+      _(namo.data_dimensions).wont_include :doubled
+      _(namo.values(:doubled)).must_equal [2, 4]
+    end
+
     it "is last-write-wins: scalar then proc leaves a formula only" do
       namo = Namo.new([{y: 7}])
       namo[:x] = 5
@@ -688,6 +706,247 @@ describe Namo do
     end
   end
 
+  describe "formularies" do
+    let(:flow_data) do
+      [
+        {date: 1, buys: 60, sells: 40},
+        {date: 2, buys: 80, sells: 120},
+        {date: 3, buys: 75, sells: 75},
+      ]
+    end
+
+    let(:delta) do
+      Module.new do
+        include Namo::Formulary
+        def signed_volume(row); row[:buys] - row[:sells]; end
+        def cum_delta(row, namo); namo[date: ..row[:date]].values(:signed_volume).sum; end
+        def scaled_volume(row, namo, factor); (row[:buys] + row[:sells]) * factor; end
+        private
+        def helper(row); row[:buys]; end
+      end
+    end
+
+    let(:untagged) do
+      Module.new do
+        def signed_volume(row); 0; end
+      end
+    end
+
+    let(:flows) do
+      Namo.new(flow_data).attach(delta)
+    end
+
+    describe "#attach" do
+      it "returns the Namo" do
+        namo = Namo.new(flow_data)
+        _(namo.attach(delta)).must_be_same_as namo
+      end
+
+      it "raises ArgumentError for a module not tagged Namo::Formulary" do
+        _(proc{Namo.new(flow_data).attach(untagged)}).must_raise ArgumentError
+      end
+    end
+
+    describe "#<<" do
+      it "attaches a formulary, the same as #attach" do
+        namo = Namo.new(flow_data)
+        namo << delta
+        _(namo.values(:signed_volume)).must_equal [20, -40, 0]
+      end
+
+      it "returns the Namo for chaining" do
+        namo = Namo.new(flow_data)
+        _(namo << delta).must_be_same_as namo
+      end
+    end
+
+    describe "#derived_dimensions" do
+      it "lists the formulary's public methods alongside store keys, unique" do
+        _(flows.derived_dimensions.sort).must_equal [:cum_delta, :scaled_volume, :signed_volume]
+      end
+
+      it "does not surface a private helper" do
+        _(flows.derived_dimensions).wont_include :helper
+      end
+
+      it "is empty for a vanilla Namo — no Namo public API leaks as a dimension" do
+        _(Namo.new(flow_data).derived_dimensions).must_equal []
+      end
+    end
+
+    describe "resolution" do
+      it "resolves a row-scoped formulary method through values" do
+        _(flows.values(:signed_volume)).must_equal [20, -40, 0]
+      end
+
+      it "resolves a row-scoped formulary method through a Row" do
+        _(flows.entries.first[:signed_volume]).must_equal 20
+      end
+
+      it "selects on a formulary-defined dimension" do
+        _(flows[signed_volume: 20].values(:date)).must_equal [1]
+      end
+
+      it "windows a two-arity formulary method over the yielding Namo" do
+        _(flows.values(:cum_delta)).must_equal [20, -20, -20]
+      end
+
+      it "raises the collection-scoped-context error on a Row built without a Namo" do
+        row = Namo::Row.new(flow_data.first, flows.formulae)
+        _(proc{row[:cum_delta]}).must_raise ArgumentError
+      end
+    end
+
+    describe "parameterised formulary method" do
+      it "is omitted from no-arg bulk views" do
+        _(flows.values.keys).wont_include :scaled_volume
+      end
+
+      it "raises when named directly with no argument" do
+        _(proc{flows.values(:scaled_volume)}).must_raise ArgumentError
+      end
+
+      it "materialises through a row-scoped wrapper that supplies the argument" do
+        flows[:double_flow] = ->(r){r[:scaled_volume, 2]}
+        _(flows.values(:double_flow)).must_equal [200, 400, 300]
+      end
+    end
+
+    describe "live re-attachment" do
+      it "resolves to the most-recently attached formulary on a name collision" do
+        alt = Module.new do
+          include Namo::Formulary
+          def signed_volume(row); row[:buys]; end
+        end
+        namo = Namo.new(flow_data).attach(delta).attach(alt)
+        _(namo.values(:signed_volume)).must_equal [60, 80, 75]
+      end
+    end
+
+    describe "precedence" do
+      it "lets an instance []= formula shadow a formulary method of the same name" do
+        flows[:signed_volume] = ->(r){0}
+        _(flows.values(:signed_volume)).must_equal [0, 0, 0]
+      end
+    end
+
+    describe "carry-through" do
+      it "carries the formulary live through selection" do
+        _(flows.select{|row| row[:date] >= 2}.values(:signed_volume)).must_equal [-40, 0]
+      end
+
+      it "carries the formulary live through projection by selection" do
+        _(flows[date: 1..2].values(:signed_volume)).must_equal [20, -40]
+      end
+
+      it "carries the formulary through concatenation" do
+        _((flows + Namo.new(flow_data)).derived_dimensions).must_include :signed_volume
+      end
+    end
+
+    describe "materialising a formulary dimension by projection" do
+      it "lists the name once, as data, not derived" do
+        proj = flows[:date, :signed_volume]
+        _(proj.data_dimensions).must_include :signed_volume
+        _(proj.derived_dimensions).wont_include :signed_volume
+        _(proj.dimensions.count(:signed_volume)).must_equal 1
+      end
+
+      it "reads the snapshot, not a recomputation, on per-Row access" do
+        proj = flows[:date, :signed_volume]
+        _(proj.entries.first[:signed_volume]).must_equal 20
+        _(proj.values(:signed_volume)).must_equal [20, -40, 0]
+      end
+
+      it "raises when a formulary method collides with a data dimension" do
+        widened = Namo.new(flow_data.map{|row| row.merge(signed_volume: 999)})
+        error = _(proc{widened.attach(delta)}).must_raise ArgumentError
+        _(error.message).must_match(/signed_volume/)
+      end
+    end
+
+    describe "#===" do
+      it "is not === to a vanilla Namo of the same data dimensions" do
+        _(flows === Namo.new(flow_data)).must_equal false
+      end
+
+      it "is === to a Namo exposing the same names via []=" do
+        other = Namo.new(flow_data)
+        other[:signed_volume] = ->(r){0}
+        other[:cum_delta] = ->(r, n){0}
+        other[:scaled_volume] = ->(r, n, f){0}
+        _(flows === other).must_equal true
+      end
+    end
+  end
+
+  describe "formularies via class include" do
+    let(:flow_data) do
+      [{buys: 60, sells: 40}]
+    end
+
+    let(:indicators) do
+      Module.new do
+        include Namo::Formulary
+        def signed_volume(row); row[:buys] - row[:sells]; end
+        def label(row); "indicators"; end
+        private
+        def helper(row); row[:buys]; end
+      end
+    end
+
+    let(:scoring) do
+      Module.new do
+        include Namo::Formulary
+        def momentum(row); row[:buys] + row[:sells]; end
+        def label(row); "scoring"; end
+      end
+    end
+
+    let(:analysis_class) do
+      klass = Class.new(Namo)
+      klass.include(indicators)
+      klass.include(scoring)
+      klass
+    end
+
+    it "lists an included formulary's public methods as derived dimensions" do
+      _(analysis_class.new(flow_data).derived_dimensions.sort).must_equal [:label, :momentum, :signed_volume]
+    end
+
+    it "excludes a private helper" do
+      _(analysis_class.new(flow_data).derived_dimensions).wont_include :helper
+    end
+
+    it "resolves an included formulary method" do
+      _(analysis_class.new(flow_data).values(:signed_volume)).must_equal [20]
+    end
+
+    it "lets the most-recently included formulary win on a name collision" do
+      _(analysis_class.new(flow_data).values(:label)).must_equal ["scoring"]
+    end
+
+    it "raises at construction when an included formulary collides with a data dimension" do
+      clash = Module.new do
+        include Namo::Formulary
+        def buys(row); 0; end
+      end
+      klass = Class.new(Namo)
+      klass.include(clash)
+      _(proc{klass.new([{buys: 5}])}).must_raise ArgumentError
+    end
+
+    it "reaches an instance built before a later include only through attach" do
+      klass = Class.new(Namo)
+      instance = klass.new(flow_data)
+      klass.include(scoring)
+      _(instance.derived_dimensions).wont_include :momentum
+      _(klass.new(flow_data).derived_dimensions).must_include :momentum
+      instance.attach(scoring)
+      _(instance.derived_dimensions).must_include :momentum
+    end
+  end
+
   describe "#[]= two-arity formulae" do
     let(:price_data) do
       [

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: namo
 version: !ruby/object:Gem::Version
-  version: 0.22.0
+  version: 0.23.0
 platform: ruby
 authors:
 - thoran
@@ -67,6 +67,7 @@ files:
 - lib/Namo/Collection.rb
 - lib/Namo/Enumerable.rb
 - lib/Namo/Formulae.rb
+- lib/Namo/Formulary.rb
 - lib/Namo/NegatedDimension.rb
 - lib/Namo/Row.rb
 - lib/Namo/VERSION.rb