namo 0.22.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6342f1cab3b5811a97d92be8ef7ba34a81191bd97a6ee2c606f8adc7d9a0d47
-  data.tar.gz: ce7db23d2907e33a80d1e263b4b9987645a6c1c47979b7f3311bf519d8f9e738
+  metadata.gz: 9e1ecaf29846a7876a59dae0d82c6c9d4e1fddd84b0c6a101941214ed6544517
+  data.tar.gz: 4245b13c3485a504ab5c365803de282cb508579b2ca9aec0799df0f1ce653d68
 SHA512:
-  metadata.gz: 5c6c26eda0a637af215eef9cab0fe369769af3e945b3a1cf980788bd34be97abeefb3cf29fb208012556c5df9e46c212c9476dc222b0f3917404c7db3003f21a
-  data.tar.gz: f71fd3ed7b8e8068b55fbb8379cd361c91c84ca1cb4fe823ff72af9fe1c9b8e1247468fb9fd818aa865cac709aa2d22e63f2c866030cacee22bf25c5930e7758
+  metadata.gz: 41156dc96b98f59f8ff0dcf0d78f3b80ed895f402e11af9a53ba2e6cdb13d8bf39f1a38f48f2457bfe8bcf9082d146b73dafa4663e068816b2339d6888fd25af
+  data.tar.gz: e9c1f033e17fd2b10ffab984ea6349b7641de8abf0f04f23f85c893793242abd9e795847244855ad18b8c3f74b5876cce16dd212b2d1d2a6d327998657c9a4dc

data/CHANGELOG

@@ -1,6 +1,30 @@
 CHANGELOG
 _________
 
+20260629
+0.24.0: ~ Namo#<<, Namo::Collection#<< — widen from a formulary-only alias into a polymorphic "append a constituent" operator.
+
+A base Namo's constituents are formularies and rows: << dispatches a Module to attach (0.23.0 behaviour, unchanged), a Hash to a data-row append, and a Row to a row append of its underlying hash. It does not take a bare callable (formula registration stays with []=) or a whole Namo (combining is +'s job) — both raise. Collection#<< is reconciled to the same verb over its own constituents: a Namo is a member, a Module attaches, and a loose Hash/Row raises (a Collection's rows are derived from its members, so a loose row has no durable home). This Hash/Row divergence — a base Namo appends the row, a Collection refuses it — is deliberate, not an oversight.
+
+1. ~ lib/namo.rb: ~ Namo#<< — replace the alias_method :<<, :attach with a dispatching << that routes Module→attach, Row→add_row(row.to_h), Hash→add_row(row), else→TypeError. attach stays Module-only and unchanged, so the 0.23.0 collision-guard and formulary semantics carry over verbatim and a Module's << still reaches it. + private add_row(row), appending to @data and returning self (so << chains). A whole Namo falls to the else and raises (it is not a Module/Row/Hash) — combining is +. Row-append is a data mutation that does not pass through []=, so it does not trigger formula-eviction; a row carrying a formula-named key surfaces live through the formula on access, per existing precedence (not guarded — the exclusivity invariant is []='s).
+2. ~ lib/Namo/Collection.rb: ~ Collection#<< — keep the splat + flatten (a member or an array of them), but dispatch each constituent: Namo→add_member, Module→attach (inherited from Namo — a Collection carries formulae over its detail view), Hash/Row→ArgumentError redirecting to member-add, else→TypeError. + private add_member(member), the prior reject-by-name + append body extracted verbatim. The @data = detail.data rebuild after the loop is preserved, so member-adds re-materialise detail as before and a Module-only << rebuilds harmlessly. Module routes to the inherited Namo#attach; member-add behaviour is byte-identical to 0.23.0 for the Namo/array cases.
+3. ~ test/namo_test.rb: ~ the formularies "#<<" describe gains the row arms — a Hash appends as a data row (and returns the Namo), a Row appends its underlying hash, a whole Namo raises TypeError (+'s job), a bare callable raises TypeError ([]='s job), and a mixed chain interleaves rows and a formulary. The two 0.23.0 Module-arm tests are unchanged.
+4. ~ test/Namo/Collection_test.rb: ~ the "#<<" describe gains a formulary attach whose row-scoped method resolves over the detail rows, a collection-scoped method (the namo_collection convention) reaching members, a loose Hash and a loose Row each raising ArgumentError with the member-redirect message, and a chain mixing member-adds with a formulary attach. The 0.23.0 member-add tests are unchanged.
+5. ~ README.md: ~ the Formularies << note — << now appends a constituent (Module, Hash, or Row) to a base Namo, chains, and raises on a bare callable or a whole Namo; the bare-Hash-is-always-a-row and row-append-does-not-evict notes added. ~ the Collection "<< and unnamed members" section — Collection#<< dispatches member/Module/raise, with the deliberate Hash/Row divergence spelled out. + a "Collection formulae" subsection — the namo_collection convention (an ordinary two-arity formulary method reaching a collection view in its body), no marker and no second store.
+6. ~ ROADMAP.md: + the 0.24.0 release entry; current-state bumped to 0.24.0; pivot/reshaping recorded as a decision (long-form aggregation is in-grain future work, widening-to-a-grid is presentational and belongs at an output edge, not the algebra), and collection formulae noted as needing no new mechanism.
+7. ~ Namo::VERSION: /0.23.0/0.24.0/
+
+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]
+```
+
+`<<` appends a *constituent*. For a base Namo the constituents are formularies and rows: a **module** attaches (the operator form of `attach`, so `flows << OrderFlow` reads the same as `flows.attach(OrderFlow)`); a **Hash** appends as a data row; a **Row** (one drawn from another Namo) appends its underlying hash as a row. It returns the Namo, so the arms chain freely: `flows << OrderFlow << {date: 4, buys: 10, sells: 5} << Scoring`. Two things `<<` deliberately does not take: a bare callable (formula *registration* stays with `[]=`, which dispatches callable-vs-scalar and enforces data/formula exclusivity) and a whole Namo (combining collections is `+`'s job) — both raise. A bare Hash is therefore always a row, never a body of formulae. Appending a row is a data mutation that does not pass through `[]=`, so it does not trigger formula-eviction; a row carrying a formula-named key is your data, surfacing live through the formula on access per the usual precedence.
+
+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]
@@ -1017,6 +1073,8 @@ gt << SubAssembly.new(name: :powertrain, data: [...])   # replaces the existing
 gt << [front_suspension, rear_suspension]               # adds each
 ```
 
+On a Collection `<<` dispatches to the *constituent* appropriate to a collection: a **member** (a Namo, or an array of them) is added as above; a **module** attaches a formulary (a Collection is a Namo, so it carries formulae over its detail view — see below); a loose **Hash or Row raises** an `ArgumentError` that redirects to member-add. This is the one place `Namo#<<` and `Collection#<<` deliberately diverge: a base Namo appends a loose row, a Collection refuses it — a Collection's rows are *derived* from its members, so a loose row has no durable home (the next member-add rebuilds the data view and would erase it). The honest response is to refuse and point at member-add. A whole Namo arriving at a Collection is unambiguously a member, never a row-merge, because `<<` has no whole-Namo arm (that is `+`).
+
 There is no insertion-time guard against unnamed members. An unnamed member is simply appended (no name to collide on) and is unfindable by `find` — the honest consequence of having no name, not an error. `find(name)` returns the member with that name, or `nil`:
 
 ```ruby
@@ -1026,6 +1084,23 @@ gt.find(:missing)    # => nil
 
 (`find(name)` is member lookup; it shadows `Enumerable#find` on Collections. Predicate search over rows remains available as `detect`.)
 
+#### Collection formulae
+
+A formulary attached to a Collection resolves over its detail rows like any other — a Collection is a Namo, and its data view is the materialised detail. A *collection formula* needs no new mechanism: it is an ordinary two-arity formulary method whose `namo` argument is the Collection, reaching for a collection view (`summary`, `detail`, `members`) in its body. It resolves through the same `derive` path as every other formula; member-awareness lives in the method body, not in any marker or second store. By convention, name that argument `namo_collection` to signal it expects a Collection — a plain Namo lacking `members`/`summary` will `NoMethodError`, which is honest self-enforcement, no guard needed.
+
+```ruby
+module FleetMetrics
+  include Namo::Formulary
+
+  def member_count(row, namo_collection)
+    namo_collection.members.size
+  end
+end
+
+gt << FleetMetrics
+gt.values(:member_count)   # => one entry per detail row, each the member count
+```
+
 #### View lifetime and liveness
 
 Materialisation is pure-live: the Collection rebuilds its data view from the current members on every `<<`, with no memoisation. So a mutation is reflected immediately — add a member, then summarise or detail, and the new member is included.

data/lib/Namo/Collection.rb

@@ -5,10 +5,15 @@ class Namo
   class Collection < Namo
     attr_reader :members
 
-    def <<(*members)
-      members.flatten.each do |member|
-        @members.reject!{|existing| existing.name == member.name} unless member.name.nil?
-        @members << member
+    def <<(*constituents)
+      constituents.flatten.each do |constituent|
+        case constituent
+        when Namo then add_member(constituent)
+        when Module then attach(constituent)
+        when Hash, Row
+          raise ArgumentError, "a Collection's rows come from its members; add a member (a named Namo), not a loose row"
+        else raise TypeError, "can't append #{constituent.class} to a Collection"
+        end
       end
       @data = detail.data
       self
@@ -48,5 +53,10 @@ class Namo
       @members = []
       super
     end
+
+    def add_member(member)
+      @members.reject!{|existing| existing.name == member.name} unless member.name.nil?
+      @members << member
+    end
   end
 end

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.24.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,24 @@ 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
+
+  def <<(constituent)
+    case constituent
+    when Module then attach(constituent)
+    when Row then add_row(constituent.to_h)
+    when Hash then add_row(constituent)
+    else raise TypeError, "can't append #{constituent.class} to a Namo; expected a Module (formulary), a Hash, or a Row"
+    end
+  end
+
   def +(other)
     raise_unless_namo(other)
     raise_unless_matching_data_dimensions(other)
@@ -238,6 +256,19 @@ class Namo
     @data = positional_data || data
     @formulae = formulae.is_a?(Formulae) ? formulae : Formulae.new(formulae)
     @name = name
+    attach_included_formularies
+  end
+
+  def add_row(row)
+    @data << row
+    self
+  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/Collection_test.rb

@@ -45,6 +45,20 @@ describe Namo::Collection do
     Namo::Collection.new.tap{|c| c << [powertrain, chassis, body]}
   end
 
+  let(:component_pricing) do
+    Module.new do
+      include Namo::Formulary
+      def cost_per_kg(row); row[:cost] / row[:weight]; end
+    end
+  end
+
+  let(:fleet_metrics) do
+    Module.new do
+      include Namo::Formulary
+      def member_count(row, namo_collection); namo_collection.members.size; end
+    end
+  end
+
   describe "construction" do
     it "starts with empty members" do
       _(Namo::Collection.new.members).must_equal []
@@ -101,6 +115,34 @@ describe Namo::Collection do
       collection = Namo::Collection.new
       _(collection << powertrain).must_be_same_as collection
     end
+
+    it "attaches a formulary whose row-scoped method resolves over the detail rows" do
+      collection << component_pricing
+      _(collection.values(:cost_per_kg)).must_equal [250, 250, 200, 250]
+    end
+
+    it "attaches a formulary whose collection-scoped method reaches members" do
+      collection << fleet_metrics
+      _(collection.values(:member_count)).must_equal [3, 3, 3, 3]
+    end
+
+    it "raises an ArgumentError on a loose Hash, redirecting to member-add" do
+      error = _(proc{collection << {component: 'bolt', weight: 1, cost: 5}}).must_raise ArgumentError
+      _(error.message).must_match(/member/)
+    end
+
+    it "raises an ArgumentError on a loose Row, redirecting to member-add" do
+      row = Namo.new([{component: 'bolt', weight: 1, cost: 5}]).entries.first
+      error = _(proc{collection << row}).must_raise ArgumentError
+      _(error.message).must_match(/member/)
+    end
+
+    it "chains member-adds and a formulary attach" do
+      collection = Namo::Collection.new
+      collection << powertrain << chassis << component_pricing
+      _(collection.members.size).must_equal 2
+      _(collection.values(:cost_per_kg)).must_equal [250, 250, 200]
+    end
   end
 
   describe "#find" do

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,283 @@ 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
+
+      it "appends a Hash as a data row" do
+        namo = Namo.new(flow_data)
+        namo << {date: 4, buys: 10, sells: 5}
+        _(namo.values(:date)).must_equal [1, 2, 3, 4]
+        _(namo.values(:buys)).must_equal [60, 80, 75, 10]
+      end
+
+      it "returns the Namo when appending a row" do
+        namo = Namo.new(flow_data)
+        _(namo << {date: 4, buys: 10, sells: 5}).must_be_same_as namo
+      end
+
+      it "appends a Row's underlying hash as a data row" do
+        namo = Namo.new(flow_data)
+        row = Namo.new([{date: 4, buys: 10, sells: 5}]).entries.first
+        namo << row
+        _(namo.values(:date)).must_equal [1, 2, 3, 4]
+      end
+
+      it "raises a TypeError on a whole Namo, which is +'s job" do
+        namo = Namo.new(flow_data)
+        _(proc{namo << Namo.new(flow_data)}).must_raise TypeError
+      end
+
+      it "raises a TypeError on a bare callable, which is []='s job" do
+        namo = Namo.new(flow_data)
+        _(proc{namo << ->(row){row[:buys]}}).must_raise TypeError
+      end
+
+      it "chains mixed arms: rows and a formulary" do
+        namo = Namo.new(flow_data)
+        namo << {date: 4, buys: 10, sells: 5} << delta << {date: 5, buys: 0, sells: 0}
+        _(namo.values(:date)).must_equal [1, 2, 3, 4, 5]
+        _(namo.values(:signed_volume)).must_equal [20, -40, 0, 5, 0]
+      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.24.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