namo 0.13.2 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 480baeb4c1da195bc5e9800df21267467dd784a4ef6b4fc41cd1997925c36432
-  data.tar.gz: d1794682a82a35578e87734569808b61171ceb95f2d0548e761b42052ea5223b
+  metadata.gz: 7d2d5b27fc7c414edd9d13ac80d87bc6f99c87b2f94a42b8f192c3e5a4f08daa
+  data.tar.gz: 91ff974cb3c20802cf0afea77563211a1d29abda66bf9960ed18611fbaf09410
 SHA512:
-  metadata.gz: 203c4416d177b726d3f8bec5bebf5225f9bb28cbf2ca3fbae1365f8f0d4062ce95018233e4342ec29b33f2bf753849acc512f1ff017f0925eec629caece73781
-  data.tar.gz: a9ca4f20b7319825652588fe780e59601744447c38cddbfe0d2ce2c624200d249ce1ff43113a5d543737ab5789890392a48ff2fcf3dca52c3d5f25c999838bee
+  metadata.gz: f309aa497bde5bd05083f844f8d123257917da3e74abe07e4e18a8aff3dd362ab0e2c2b4b6df0791cb3a1b55ea53f9f7914a89eda74c2d158c0d7e5cf1e6b358
+  data.tar.gz: 62040149299672f673de4216cc7123e78e0135902d5a5ad3c948e74e7d2906b184b9ac6a6e84238f000d85a63b3ccc0b6dc894c3cdb74a65fb6ec1d7df0d6e33

data/CHANGELOG

@@ -1,6 +1,72 @@
 CHANGELOG
 _________
 
+20260612
+0.15.0: + two-arity formulae — procs with arity 2 receive (row, namo) for cross-row computation.
+
+1. ~ lib/Namo/Row.rb: Row's constructor gains an optional third parameter, namo (default nil),
+   stored in @namo — the Namo that yielded the Row; the two-argument form keeps working.
+   Row#[] dispatches on formula arity: exactly 2 calls formula.call(self, @namo), raising
+   ArgumentError via the new private raise_unless_namo_context when @namo is nil; every
+   other arity (0, 1, negative) keeps the existing formula.call(self) unchanged.
+2. ~ lib/Namo/Enumerable.rb: every Row construction (each, select and its aliases, reject,
+   sort_by, first, last, take_while, drop_while, uniq's block form, partition) passes self
+   as the Row's namo, so two-arity formulae resolve during enumeration and predicate
+   evaluation, with the yielding Namo as the window.
+3. ~ lib/namo.rb: values_for's derived branch and the * and ** block paths pass self as the
+   Row's namo — values/coordinates/to_h resolve two-arity dimensions, and composition-block
+   rows can resolve self's two-arity formulae (extension of the 0.14.0 block contract; the
+   (Row, Namo) -> Namo contract and result-formulae rule are unchanged).
+4. ~ test/Namo/Row_test.rb: + constructor third-argument and backward-compatibility tests,
+   arity-dispatch tests (1, 2, 0, negative), the nil-namo ArgumentError, and match? on a
+   two-arity derived dimension.
+5. ~ test/namo_test.rb: + "#[]= two-arity formulae" describe — SMA cross-row resolution via
+   values/coordinates/to_h, selection and subset-predicate resolution, first/last Rows,
+   yielding-Namo (filtered-window) semantics, liveness, operator carry-through, composition-
+   block resolution, mixed-arity chains, and the empty-Namo case.
+6. ~ README.md: + Cross-row formulae subsection under Formulae, with the SMA example, the
+   yielding-Namo semantic, and the no-context error.
+7. ~ ROADMAP.md: Promote 0.15.0 to shipped; Current state -> 0.15.0; Summary folds in
+   two-arity formulae; the example's window.length corrected to window.count (Namo has
+   no length); "Live computation objects" phrasing updated. + upcoming 0.16.0 section,
+   Data/formula exclusivity — projection drops the formulae it materialises, * and **
+   raise on a data/formula name collision — with parameterised formulae renumbered to
+   0.17.0, Namo::Collection to 0.18.0, and group_by to 0.19.0; next phase -> 0.16.0.
+8. ~ COMPARISON.md: Two-arity formulae -> shipped (0.15.0) with the same window.count
+   correction; Parameterised formulae repointed to planned (0.17.0). Date bumped.
+9. ~ Namo::VERSION: /0.14.0/0.15.0/
+
+20260608
+0.14.0: + blocks on the composition operators (*, **) for custom match refinement.
+
+1. ~ lib/namo.rb: Namo#* takes an optional block. Without a block, behaviour is unchanged.
+   With a block, the right rows matched on the shared data dimensions are passed as a Namo
+   (candidates, carrying other's formulae) alongside the left Row (carrying self's
+   formulae); the block returns a Namo of the rows to pair, each merged into the left row.
+   An empty returned Namo drops the left row (inner-join semantics). Result formulae are
+   other.formulae.merge(@formulae) as before — the block does not affect result formulae.
+   The shared-dimension precondition still applies with a block present.
+2. ~ lib/namo.rb: Namo#** takes an optional block, same contract, with candidates being all
+   of other's rows (no shared-dimension pre-filter). The disjoint-dimensions precondition
+   still applies with a block present.
+3. ~ test/namo_test.rb: + "with a block" context under #* (single-match one-row return, empty-return
+   drop, multi-row return, selection on other's derived dimension, reference to self's
+   derived dimension, result-formulae parity with no-block, derived-not-stored-but-resolves,
+   subclass type, preconditions still raise) and under #** (selector filtering one-to-many,
+   empty-return drop, full-candidates reproduces no-block, selection on other's derived
+   dimension, result-formulae parity, disjoint precondition still raises, subclass type).
+   Existing no-block #* and #** tests unchanged and green.
+4. ~ README.md: + block subsections under Composition and Cartesian product, with the
+   price/quarterly matching and orders/tiers worked examples and the (row, candidates) ->
+   Namo contract.
+5. ~ ROADMAP.md: Promote 0.14.0 to shipped (composition blocks only); Current state -> 0.14.0;
+   Summary folds in composition blocks; next phase -> 0.15.0. + the governing principle
+   (a block form is warranted iff the operation gives consideration to a dimension in
+   isolation), tied to the orthogonality/efficiency rationale for why set-operator/`/`
+   blocks were not added. The now-redundant upcoming 0.14.0 section removed.
+6. ~ COMPARISON.md: "Conditional join with block" -> shipped (0.14.0).
+7. ~ Namo::VERSION: /0.13.2/0.14.0/
+
 20260608
 0.13.2: Narrow the planned 0.14.0 block-form scope to the composition operators and document the rationale.
 

data/README.md

@@ -355,6 +355,36 @@ Inner-join semantics: unmatched rows from either side are dropped. Output dimens
 
 The two Namos must have at least one shared data dimension. No overlap raises an `ArgumentError` — the asymmetry with `**` is deliberate, and falling through to a Cartesian product would silently turn a logic error into a large pile of nonsense rows. Formulae merge from both sides; the left-hand side wins on conflict.
 
+#### Conditional join
+
+`*` takes an optional block that decides which matched rows to pair with each left row. Without a block, every shared-dimension match pairs, as above. With one, the block is handed the current left row and the right rows already matched on the shared dimensions, and returns the subset to pair — the refinement plain `*` can't express, because it pairs every match.
+
+The canonical case is matching each daily price to a single quarterly report — the most recent one dated on or before it. Plain `*` pairs *every* matching quarter; the block narrows that to the one the matching rule picks.
+
+```ruby
+prices = Namo.new([
+  {symbol: 'BHP', date: '2025-02-15', close: 42.5},
+  {symbol: 'BHP', date: '2025-05-20', close: 44.0}
+])
+
+quarterly = Namo.new([
+  {symbol: 'BHP', quarter_end: '2024-12-31', eps: 1.0},
+  {symbol: 'BHP', quarter_end: '2025-03-31', eps: 1.2}
+])
+
+prices.*(quarterly) do |row, candidates|
+  candidates[quarter_end: ->(qe){qe <= row[:date]}].sort_by{|f| f[:quarter_end]}.last(1)
+end
+# => #<Namo [
+#   {symbol: 'BHP', date: '2025-02-15', close: 42.5, quarter_end: '2024-12-31', eps: 1.0},
+#   {symbol: 'BHP', date: '2025-05-20', close: 44.0, quarter_end: '2025-03-31', eps: 1.2}
+# ]>
+```
+
+`row` is the `Row` for the current left row, carrying self's formulae, so `row[:date]` and any self formula resolve inside the block. `candidates` is a Namo of the shared-dimension matches, carrying other's formulae, so the block can select on other's derived dimensions too. The block returns a Namo of the rows to pair: one row for the single-match rule above, though it may return zero, one, or many — it's a selector, not a reducer. An empty returned Namo pairs nothing, so that left row is dropped, preserving inner-join semantics. The block can also be passed as a named proc, `prices.*(quarterly, &most_recent_quarter)`.
+
+The block changes only which rows pair. Formulae carry through exactly as in the no-block form — other's merged under self's, self winning on conflict — and the rows the block returns contribute data only.
+
 ### Cartesian product
 
 `**` is the Cartesian product. Every row from the left paired with every row from the right:
@@ -378,6 +408,35 @@ The two Namos must have **no** shared data dimensions — the precondition is th
 
 The visual relationship is intentional: `*` is the filtered version, `**` is the explosive version — more sigil, more output.
 
+#### Conditional product
+
+`**` takes an optional block on the same contract. Where `*`'s block receives the rows pre-matched on the shared dimensions, `**`'s receives *all* of other's rows — there are no shared dimensions to match on — and returns the subset to pair with each left row.
+
+This expresses a conditional product: pair each order with only the shipping tiers that can carry it.
+
+```ruby
+orders = Namo.new([
+  {order: 'A', weight: 5},
+  {order: 'B', weight: 15}
+])
+
+tiers = Namo.new([
+  {tier: 'light', max_weight: 10},
+  {tier: 'heavy', max_weight: 20}
+])
+
+orders.**(tiers) do |row, candidates|
+  candidates[max_weight: ->(w){w >= row[:weight]}]
+end
+# => #<Namo [
+#   {order: 'A', weight: 5, tier: 'light', max_weight: 10},
+#   {order: 'A', weight: 5, tier: 'heavy', max_weight: 20},
+#   {order: 'B', weight: 15, tier: 'heavy', max_weight: 20}
+# ]>
+```
+
+The contract matches `*`'s: `row` carries self's formulae, `candidates` carries other's, the block returns a Namo of rows to pair, and an empty return drops the left row. A block that returns its `candidates` unchanged reproduces the no-block product exactly — `**` is its own block form with the identity selector, just as `*` is `**` with the shared-dimension match applied first.
+
 ### Decomposition
 
 `/` removes from the left Namo the dimensions that are also in the right, then dedupes the projected rows. It's the inverse of `*` and `**`:
@@ -585,6 +644,34 @@ sales[product: 'Widget'][:revenue, :quarter]
 
 Formulae carry through selection — a filtered Namo instance remembers its formulae.
 
+#### Cross-row formulae
+
+A formula's arity selects its calling convention. A proc with **one** parameter receives the row, as above. A proc with **two** parameters receives `(row, namo)`, where `namo` is the Namo the row belongs to — so the formula can reach beyond the current row to the rest of the collection. That's what cross-row computation needs: moving windows, ranks, running totals, anything whose value depends on the row's neighbours.
+
+A simple moving average reads the surrounding rows through `namo`:
+
+```ruby
+prices = Namo.new([
+  {symbol: 'AAA', date: 1, close: 10.0},
+  {symbol: 'AAA', date: 2, close: 20.0},
+  {symbol: 'AAA', date: 3, close: 30.0}
+])
+
+prices[:sma] = proc{|row, namo|
+  window = namo[symbol: row[:symbol], date: ->(d){d <= row[:date]}]
+  window.values(:close).sum / window.count.to_f
+}
+
+prices.values(:sma)
+# => [10.0, 15.0, 20.0]
+```
+
+`namo` is the Namo that yielded the row, live — so the window always reflects the current state of the object you ask through. A filtered Namo's rows window over the filtered rows; an operator result's rows window over the result. Appending a row changes every cross-row value on the next access, with no caching.
+
+One-arity formulae are unchanged, and the two forms mix freely — a one-arity formula can reference a two-arity one, and a two-arity formula can reference a one-arity one, by name.
+
+Resolving a two-arity formula needs a Namo to window over. A `Row` constructed directly, without one, raises an `ArgumentError` naming the formula rather than letting the missing context surface as an unrelated error.
+
 ### Polymorphic `[]=`
 
 `[]=` dispatches on the type of the value assigned. A proc registers a formula, as above. Anything else broadcasts the value to every row:

data/lib/Namo/Enumerable.rb

@@ -7,28 +7,28 @@ class Namo
 
     def each(&block)
       return enum_for(:each) unless block_given?
-      @data.each{|row_data| block.call(Row.new(row_data, @formulae))}
+      @data.each{|row_data| block.call(Row.new(row_data, @formulae, self))}
     end
 
     def select(&block)
-      self.class.new(@data.select{|row| block.call(Row.new(row, @formulae))}, formulae: @formulae.dup)
+      self.class.new(@data.select{|row| block.call(Row.new(row, @formulae, self))}, formulae: @formulae.dup)
     end
     alias_method :filter, :select
     alias_method :find_all, :select
 
     def reject(&block)
-      self.class.new(@data.reject{|row| block.call(Row.new(row, @formulae))}, formulae: @formulae.dup)
+      self.class.new(@data.reject{|row| block.call(Row.new(row, @formulae, self))}, formulae: @formulae.dup)
     end
 
     def sort_by(&block)
-      self.class.new(@data.sort_by{|row| block.call(Row.new(row, @formulae))}, formulae: @formulae.dup)
+      self.class.new(@data.sort_by{|row| block.call(Row.new(row, @formulae, self))}, formulae: @formulae.dup)
     end
 
     def first(n = nil)
       if n
         self.class.new(@data.first(n), formulae: @formulae.dup)
       else
-        @data.first ? Row.new(@data.first, @formulae) : nil
+        @data.first ? Row.new(@data.first, @formulae, self) : nil
       end
     end
 
@@ -36,7 +36,7 @@ class Namo
       if n
         self.class.new(@data.last(n), formulae: @formulae.dup)
       else
-        @data.last ? Row.new(@data.last, @formulae) : nil
+        @data.last ? Row.new(@data.last, @formulae, self) : nil
       end
     end
 
@@ -49,20 +49,20 @@ class Namo
     end
 
     def take_while(&block)
-      self.class.new(@data.take_while{|row| block.call(Row.new(row, @formulae))}, formulae: @formulae.dup)
+      self.class.new(@data.take_while{|row| block.call(Row.new(row, @formulae, self))}, formulae: @formulae.dup)
     end
 
     def drop_while(&block)
-      self.class.new(@data.drop_while{|row| block.call(Row.new(row, @formulae))}, formulae: @formulae.dup)
+      self.class.new(@data.drop_while{|row| block.call(Row.new(row, @formulae, self))}, formulae: @formulae.dup)
     end
 
     def uniq(&block)
-      rows = block ? @data.uniq{|row| block.call(Row.new(row, @formulae))} : @data.uniq
+      rows = block ? @data.uniq{|row| block.call(Row.new(row, @formulae, self))} : @data.uniq
       self.class.new(rows, formulae: @formulae.dup)
     end
 
     def partition(&block)
-      matches, non_matches = @data.partition{|row| block.call(Row.new(row, @formulae))}
+      matches, non_matches = @data.partition{|row| block.call(Row.new(row, @formulae, self))}
       [
         self.class.new(matches, formulae: @formulae.dup),
         self.class.new(non_matches, formulae: @formulae.dup),

data/lib/Namo/Row.rb

@@ -5,7 +5,13 @@ class Namo
   class Row
     def [](name)
       if @formulae.key?(name)
-        @formulae[name].call(self)
+        case @formulae[name].arity
+        when 2
+          raise_unless_namo_context(name)
+          @formulae[name].call(self, @namo)
+        else
+          @formulae[name].call(self)
+        end
       else
         @row[name]
       end
@@ -44,9 +50,16 @@ class Namo
 
     private
 
-    def initialize(row, formulae)
+    def initialize(row, formulae, namo = nil)
       @row = row
       @formulae = formulae
+      @namo = namo
+    end
+
+    def raise_unless_namo_context(name)
+      unless @namo
+        raise ArgumentError, "two-arity formula #{name.inspect} requires a Namo context, but this Row has none"
+      end
     end
   end
 end

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.13.2'
+  VERSION = '0.15.0'
 end

data/lib/namo.rb

@@ -115,28 +115,35 @@ class Namo
     self.class.new((@data - other.data) + (other.data - @data), formulae: other.formulae.merge(@formulae))
   end
 
-  def *(other)
+  def *(other, &block)
     raise_unless_namo(other)
     raise_unless_shared_data_dimensions(other)
     shared = data_dimensions & other.data_dimensions
     combined_data = []
     @data.each do |left_row|
-      other.data.each do |right_row|
-        if shared.all?{|dim| left_row[dim] == right_row[dim]}
-          combined_data << left_row.merge(right_row)
-        end
+      matched = other.data.select{|right_row| shared.all?{|dim| left_row[dim] == right_row[dim]}}
+      if block
+        candidates = other.class.new(matched, formulae: other.formulae.dup)
+        chosen = block.call(Row.new(left_row, @formulae, self), candidates)
+        chosen.data.each{|right_row| combined_data << left_row.merge(right_row)}
+      else
+        matched.each{|right_row| combined_data << left_row.merge(right_row)}
       end
     end
     self.class.new(combined_data, formulae: other.formulae.merge(@formulae))
   end
 
-  def **(other)
+  def **(other, &block)
     raise_unless_namo(other)
     raise_unless_disjoint_data_dimensions(other)
     combined_data = []
     @data.each do |left_row|
-      other.data.each do |right_row|
-        combined_data << left_row.merge(right_row)
+      if block
+        candidates = other.class.new(other.data, formulae: other.formulae.dup)
+        chosen = block.call(Row.new(left_row, @formulae, self), candidates)
+        chosen.data.each{|right_row| combined_data << left_row.merge(right_row)}
+      else
+        other.data.each{|right_row| combined_data << left_row.merge(right_row)}
       end
     end
     self.class.new(combined_data, formulae: other.formulae.merge(@formulae))
@@ -222,11 +229,17 @@ class Namo
 
   private
 
+  def initialize(positional_data = nil, data: [], formulae: {}, name: nil)
+    @data = positional_data || data
+    @formulae = formulae
+    @name = name
+  end
+
   def values_for(dim)
     if data_dimensions.include?(dim)
       @data.map{|row_data| row_data[dim]}
     else
-      @data.map{|row_data| Row.new(row_data, @formulae)[dim]}
+      @data.map{|row_data| Row.new(row_data, @formulae, self)[dim]}
     end
   end
 
@@ -253,10 +266,4 @@ class Namo
       raise ArgumentError, "dimensions in common, need no common dimensions: #{data_dimensions} vs #{other.data_dimensions}"
     end
   end
-
-  def initialize(positional_data = nil, data: [], formulae: {}, name: nil)
-    @data = positional_data || data
-    @formulae = formulae
-    @name = name
-  end
 end

data/test/Namo/Row_test.rb

@@ -40,6 +40,60 @@ describe Namo::Row do
     end
   end
 
+  describe "constructor" do
+    it "constructs from the two-argument form (namo defaults nil)" do
+      _(Namo::Row.new(row_data, formulae)).must_be_kind_of Namo::Row
+    end
+
+    it "accepts a third namo argument" do
+      namo = Namo.new([row_data])
+      _(Namo::Row.new(row_data, formulae, namo)).must_be_kind_of Namo::Row
+    end
+  end
+
+  describe "#[] arity dispatch" do
+    it "calls an arity-1 formula with the Row only" do
+      seen = nil
+      formulae[:dim] = ->(r){seen = r; 1}
+      row[:dim]
+      _(seen).must_be_same_as row
+    end
+
+    it "calls an arity-2 formula with the Row and the yielding Namo" do
+      namo = Namo.new([row_data])
+      row = Namo::Row.new(row_data, formulae, namo)
+      seen_row = nil
+      seen_namo = nil
+      formulae[:dim] = ->(r, n){seen_row = r; seen_namo = n; 1}
+      row[:dim]
+      _(seen_row).must_be_same_as row
+      _(seen_namo.equal?(namo)).must_equal true
+    end
+
+    it "takes the one-arity path for an arity-0 proc" do
+      formulae[:dim] = proc{42}
+      _(row[:dim]).must_equal 42
+    end
+
+    it "takes the one-arity path for a negative-arity proc" do
+      seen_rest = nil
+      formulae[:dim] = proc{|r, *rest| seen_rest = rest; 1}
+      row[:dim]
+      _(seen_rest).must_equal []
+    end
+
+    it "raises ArgumentError naming the formula when an arity-2 formula has no Namo context" do
+      formulae[:sma] = ->(r, n){n.count}
+      error = _(proc{row[:sma]}).must_raise ArgumentError
+      _(error.message).must_match(/sma/)
+    end
+
+    it "resolves an arity-1 formula on a Row with no Namo context" do
+      formulae[:revenue] = ->(r){r[:price] * r[:quantity]}
+      _(row[:revenue]).must_equal 1000.0
+    end
+  end
+
   describe "#match?" do
     it "matches a single value" do
       _(row.match?(product: 'Widget')).must_equal true
@@ -61,6 +115,14 @@ describe Namo::Row do
       _(row.match?(product: 'Widget', quarter: 'Q2')).must_equal false
     end
 
+    it "resolves a two-arity derived dimension when the Row carries a Namo" do
+      namo = Namo.new([row_data])
+      formulae[:row_count] = ->(r, n){n.count}
+      row = Namo::Row.new(row_data, formulae, namo)
+      _(row.match?(row_count: 1)).must_equal true
+      _(row.match?(row_count: 2)).must_equal false
+    end
+
     describe "Proc predicates" do
       it "matches when the proc returns true" do
         _(row.match?(price: ->(v){v < 15.0})).must_equal true

data/test/namo_test.rb

@@ -647,6 +647,126 @@ describe Namo do
     end
   end
 
+  describe "#[]= two-arity formulae" do
+    let(:price_data) do
+      [
+        {symbol: 'AAA', date: 1, close: 10.0},
+        {symbol: 'AAA', date: 2, close: 20.0},
+        {symbol: 'AAA', date: 3, close: 30.0},
+      ]
+    end
+
+    let(:prices) do
+      Namo.new(price_data)
+    end
+
+    # A simple moving average: the mean close over the rows of the same symbol
+    # up to and including the current row's date, computed against the Namo the
+    # row belongs to.
+    let(:sma) do
+      ->(row, namo){
+        window = namo[symbol: row[:symbol], date: ->(d){d <= row[:date]}]
+        window.values(:close).sum / window.count.to_f
+      }
+    end
+
+    it "resolves a cross-row SMA via values" do
+      prices[:sma] = sma
+      _(prices.values(:sma)).must_equal [10.0, 15.0, 20.0]
+    end
+
+    it "resolves through coordinates" do
+      prices[:sma] = sma
+      _(prices.coordinates(:sma)).must_equal [10.0, 15.0, 20.0]
+    end
+
+    it "resolves through the no-arg to_h" do
+      prices[:sma] = sma
+      _(prices.to_h[:sma]).must_equal [10.0, 15.0, 20.0]
+    end
+
+    it "selects on the two-arity dimension" do
+      prices[:sma] = sma
+      _(prices[sma: ->(v){v > 12.0}].values(:date)).must_equal [2, 3]
+    end
+
+    it "resolves a two-arity dimension in a subset-method predicate" do
+      prices[:sma] = sma
+      result = prices.select{|row| row[:sma] > 12.0}
+      _(result).must_be_kind_of Namo
+      _(result.values(:date)).must_equal [2, 3]
+    end
+
+    it "resolves the two-arity formula on the no-arg first Row" do
+      prices[:sma] = sma
+      _(prices.first[:sma]).must_equal 10.0
+    end
+
+    it "resolves the two-arity formula on the no-arg last Row" do
+      prices[:sma] = sma
+      _(prices.last[:sma]).must_equal 20.0
+    end
+
+    it "windows over the yielding Namo — a filtered Namo computes over the filtered rows only" do
+      prices[:sma] = sma
+      filtered = prices.select{|row| row[:date] >= 2}
+      # On the full Namo the date-2 SMA averages dates 1 and 2 (15.0); on the
+      # filtered Namo it sees only date 2, so the value differs.
+      _(prices.values(:sma)).must_equal [10.0, 15.0, 20.0]
+      _(filtered.values(:sma)).must_equal [20.0, 25.0]
+    end
+
+    it "is live: appending a row changes the two-arity result on next access" do
+      prices[:sma] = sma
+      _(prices.last[:sma]).must_equal 20.0
+      prices.data << {symbol: 'AAA', date: 4, close: 40.0}
+      _(prices.last[:sma]).must_equal 25.0
+    end
+
+    it "carries a two-arity formula through a set-operator result, windowing over the combined rows" do
+      a = Namo.new([{symbol: 'AAA', date: 1}, {symbol: 'AAA', date: 2}])
+      b = Namo.new([{symbol: 'AAA', date: 3}])
+      a[:peers] = ->(row, namo){namo.count}
+      _((a + b).values(:peers)).must_equal [3, 3, 3]
+    end
+
+    it "carries a merged two-arity formula through a composition result, windowing over the joined rows" do
+      left = Namo.new([{symbol: 'AAA', date: 1}, {symbol: 'AAA', date: 2}])
+      right = Namo.new([{symbol: 'AAA', sector: 'tech'}])
+      left[:peers] = ->(row, namo){namo.count}
+      result = left * right
+      _(result.values(:peers)).must_equal [2, 2]
+    end
+
+    it "resolves a two-arity formula of self inside a composition block" do
+      left = Namo.new([{symbol: 'AAA', date: 1}, {symbol: 'AAA', date: 2}])
+      right = Namo.new([{symbol: 'AAA', sector: 'tech'}])
+      left[:peers] = ->(row, namo){namo.count}
+      seen = nil
+      left.*(right){|row, candidates| seen = row[:peers]; candidates}
+      _(seen).must_equal 2
+    end
+
+    it "lets a one-arity formula reference a two-arity formula by name" do
+      prices[:sma] = sma
+      prices[:double_sma] = ->(row){row[:sma] * 2}
+      _(prices.values(:double_sma)).must_equal [20.0, 30.0, 40.0]
+    end
+
+    it "lets a two-arity formula reference a one-arity formula by name" do
+      prices[:tenth] = ->(row){row[:close] / 10.0}
+      prices[:tenth_plus_count] = ->(row, namo){row[:tenth] + namo.count}
+      _(prices.values(:tenth_plus_count)).must_equal [4.0, 5.0, 6.0]
+    end
+
+    it "returns [] for a two-arity dimension on an empty Namo without invoking the formula" do
+      invoked = false
+      empty = Namo.new([], formulae: {sma: ->(row, namo){invoked = true; 0}})
+      _(empty.values(:sma)).must_equal []
+      _(invoked).must_equal false
+    end
+  end
+
   describe "#each" do
     it "yields Row objects" do
       rows = []
@@ -1450,6 +1570,126 @@ describe Namo do
       b = Namo.new([{symbol: 'BHP', pe: 14.5}])
       _((a * b).class).must_equal subclass
     end
+
+    context "with a block" do
+      let(:prices) do
+        Namo.new([
+          {symbol: 'BHP', date: '2025-02-15', close: 42.5},
+          {symbol: 'BHP', date: '2025-05-20', close: 44.0}
+        ])
+      end
+
+      let(:quarterly) do
+        Namo.new([
+          {symbol: 'BHP', quarter_end: '2024-12-31', eps: 1.0},
+          {symbol: 'BHP', quarter_end: '2025-03-31', eps: 1.2}
+        ])
+      end
+
+      let(:most_recent_quarter) do
+        proc do |row, candidates|
+          candidates[quarter_end: ->(qe){qe <= row[:date]}].sort_by{|f| f[:quarter_end]}.last(1)
+        end
+      end
+
+      it "pairs each left row with the single match the block returns" do
+        result = prices.*(quarterly, &most_recent_quarter)
+        _(result.to_a).must_equal [
+          {symbol: 'BHP', date: '2025-02-15', close: 42.5, quarter_end: '2024-12-31', eps: 1.0},
+          {symbol: 'BHP', date: '2025-05-20', close: 44.0, quarter_end: '2025-03-31', eps: 1.2}
+        ]
+      end
+
+      it "drops a left row whose block returns an empty Namo" do
+        early = Namo.new([
+          {symbol: 'BHP', date: '2024-06-01', close: 40.0},
+          {symbol: 'BHP', date: '2025-05-20', close: 44.0}
+        ])
+        result = early.*(quarterly, &most_recent_quarter)
+        _(result.to_a).must_equal [
+          {symbol: 'BHP', date: '2025-05-20', close: 44.0, quarter_end: '2025-03-31', eps: 1.2}
+        ]
+      end
+
+      it "pairs each row when the block returns a multi-row Namo (selector, not reducer)" do
+        left = Namo.new([{symbol: 'BHP', date: '2025-05-20', close: 44.0}])
+        result = left.*(quarterly){|row, candidates| candidates}
+        _(result.to_a).must_equal [
+          {symbol: 'BHP', date: '2025-05-20', close: 44.0, quarter_end: '2024-12-31', eps: 1.0},
+          {symbol: 'BHP', date: '2025-05-20', close: 44.0, quarter_end: '2025-03-31', eps: 1.2}
+        ]
+      end
+
+      it "selects on a derived dimension of other inside the block" do
+        prices = Namo.new([
+          {symbol: 'BHP', close: 42.5},
+          {symbol: 'RIO', close: 118.3}
+        ])
+        funds = Namo.new([
+          {symbol: 'BHP', price: 42.5, eps: 3.0},
+          {symbol: 'RIO', price: 118.3, eps: 13.0}
+        ])
+        funds[:pe] = proc{|f| f[:price] / f[:eps]}
+        result = prices.*(funds){|row, candidates| candidates[pe: ->(v){v && v < 10}]}
+        _(result.values(:symbol)).must_equal ['RIO']
+        _(result.values(:close)).must_equal [118.3]
+      end
+
+      it "resolves a derived dimension of self referenced in the block" do
+        dated = Namo.new([{symbol: 'BHP', date: '2025-05-20', close: 44.0}])
+        dated[:cutoff] = proc{|r| r[:date]}
+        result = dated.*(quarterly){|row, candidates| candidates[quarter_end: ->(qe){qe <= row[:cutoff]}].sort_by{|f| f[:quarter_end]}.last(1)}
+        _(result.to_a).must_equal [
+          {symbol: 'BHP', date: '2025-05-20', close: 44.0, quarter_end: '2025-03-31', eps: 1.2}
+        ]
+      end
+
+      it "produces the same result formulae as the no-block form" do
+        ohlcv = Namo.new([
+          {symbol: 'BHP', close: 42.5},
+          {symbol: 'RIO', close: 118.3}
+        ])
+        fundamentals = Namo.new([
+          {symbol: 'BHP', pe: 14.5},
+          {symbol: 'RIO', pe: 9.2}
+        ])
+        ohlcv[:label] = proc{|r| "#{r[:symbol]}-self"}
+        fundamentals[:flag] = proc{|r| "pe=#{r[:pe]}"}
+        blocked = ohlcv.*(fundamentals){|row, candidates| candidates}
+        plain = ohlcv * fundamentals
+        _(blocked.derived_dimensions).must_equal plain.derived_dimensions
+        _(blocked.values(:label)).must_equal plain.values(:label)
+        _(blocked.values(:flag)).must_equal plain.values(:flag)
+      end
+
+      it "leaves other's derived dimension unstored but resolvable on the result" do
+        prices = Namo.new([{symbol: 'BHP', close: 42.5}])
+        funds = Namo.new([{symbol: 'BHP', price: 42.5, eps: 3.0}])
+        funds[:pe] = proc{|f| f[:price] / f[:eps]}
+        result = prices.*(funds){|row, candidates| candidates}
+        _(result.data_dimensions).wont_include :pe
+        _(result.derived_dimensions).must_include :pe
+        _(result.values(:pe)).must_equal [42.5 / 3.0]
+      end
+
+      it "returns an instance of self's class" do
+        subclass = Class.new(Namo)
+        a = subclass.new([{symbol: 'BHP', close: 42.5}])
+        b = Namo.new([{symbol: 'BHP', pe: 14.5}])
+        result = a.*(b){|row, candidates| candidates}
+        _(result.class).must_equal subclass
+      end
+
+      it "still raises ArgumentError on no shared dimensions" do
+        a = Namo.new([{symbol: 'BHP'}])
+        b = Namo.new([{quarter: 'Q1'}])
+        _ { a.*(b){|row, candidates| candidates} }.must_raise ArgumentError
+      end
+
+      it "still raises TypeError on a non-Namo operand" do
+        _ { ohlcv.*([{symbol: 'BHP'}]){|row, candidates| candidates} }.must_raise TypeError
+      end
+    end
   end
 
   describe "#**" do
@@ -1529,6 +1769,90 @@ describe Namo do
       b = Namo.new([{quarter: 'Q1'}])
       _((a ** b).class).must_equal subclass
     end
+
+    context "with a block" do
+      let(:orders) do
+        Namo.new([
+          {order: 'A', weight: 5},
+          {order: 'B', weight: 15}
+        ])
+      end
+
+      let(:tiers) do
+        Namo.new([
+          {tier: 'light', max_weight: 10},
+          {tier: 'heavy', max_weight: 20}
+        ])
+      end
+
+      it "filters pairings by the selector block (one-to-many)" do
+        result = orders.**(tiers){|row, candidates| candidates[max_weight: ->(w){w >= row[:weight]}]}
+        _(result.to_a).must_equal [
+          {order: 'A', weight: 5, tier: 'light', max_weight: 10},
+          {order: 'A', weight: 5, tier: 'heavy', max_weight: 20},
+          {order: 'B', weight: 15, tier: 'heavy', max_weight: 20}
+        ]
+      end
+
+      it "drops a left row whose block returns an empty Namo" do
+        with_unservable = Namo.new([
+          {order: 'C', weight: 50},
+          {order: 'A', weight: 5}
+        ])
+        result = with_unservable.**(tiers){|row, candidates| candidates[max_weight: ->(w){w >= row[:weight]}]}
+        _(result.to_a).must_equal [
+          {order: 'A', weight: 5, tier: 'light', max_weight: 10},
+          {order: 'A', weight: 5, tier: 'heavy', max_weight: 20}
+        ]
+      end
+
+      it "reproduces the no-block product when the block returns all candidates" do
+        blocked = products.**(quarters){|row, candidates| candidates}
+        plain = products ** quarters
+        _(blocked.to_a).must_equal plain.to_a
+      end
+
+      it "selects on a derived dimension of other inside the block" do
+        weighted_tiers = Namo.new([
+          {tier: 'light', max_weight: 10},
+          {tier: 'heavy', max_weight: 20}
+        ])
+        weighted_tiers[:premium] = proc{|t| t[:max_weight] > 15}
+        result = orders.**(weighted_tiers){|row, candidates| candidates[premium: ->(v){v}]}
+        _(result.to_a).must_equal [
+          {order: 'A', weight: 5, tier: 'heavy', max_weight: 20},
+          {order: 'B', weight: 15, tier: 'heavy', max_weight: 20}
+        ]
+      end
+
+      it "produces the same result formulae as the no-block form" do
+        products[:plabel] = proc{|r| "p=#{r[:product]}"}
+        quarters[:qlabel] = proc{|r| "q=#{r[:quarter]}"}
+        blocked = products.**(quarters){|row, candidates| candidates}
+        plain = products ** quarters
+        _(blocked.derived_dimensions).must_equal plain.derived_dimensions
+        _(blocked.values(:plabel)).must_equal plain.values(:plabel)
+        _(blocked.values(:qlabel)).must_equal plain.values(:qlabel)
+      end
+
+      it "returns an instance of self's class" do
+        subclass = Class.new(Namo)
+        a = subclass.new([{product: 'Widget'}])
+        b = Namo.new([{quarter: 'Q1'}])
+        result = a.**(b){|row, candidates| candidates}
+        _(result.class).must_equal subclass
+      end
+
+      it "still raises ArgumentError when a dimension is shared" do
+        a = Namo.new([{symbol: 'BHP', close: 42.5}])
+        b = Namo.new([{symbol: 'RIO', pe: 14.5}])
+        _ { a.**(b){|row, candidates| candidates} }.must_raise ArgumentError
+      end
+
+      it "still raises TypeError on a non-Namo operand" do
+        _ { products.**([{quarter: 'Q1'}]){|row, candidates| candidates} }.must_raise TypeError
+      end
+    end
   end
 
   describe "#/" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: namo
 version: !ruby/object:Gem::Version
-  version: 0.13.2
+  version: 0.15.0
 platform: ruby
 authors:
 - thoran
@@ -93,7 +93,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.12
+rubygems_version: 4.0.14
 specification_version: 4
 summary: Named dimensional data for Ruby.
 test_files: []