namo 0.26.0 → 0.26.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 326ba6ba610149b0998452136812f313617014d5e68fc066d5c81ace134ad8eb
-  data.tar.gz: ddd93f8e3866169c6bc6835c5720375fbfd53860b2e036f1540dcb567414b61c
+  metadata.gz: 40ae1191c5889356a1f8442673b3f44588521aa07f3f379fe58c9afa85b574c8
+  data.tar.gz: c38c7996e0a31e6050adcd9162dbbd6bde3b1c8b12cbaf0b1ab6a7848eeffb78
 SHA512:
-  metadata.gz: 9402c8b7193dd068d624b883f9e2b7492942cf67dcf0c3d697e85bb77c2615deb205538cf86c5b341e567e25990241235b88bd5bfa0582b0cace025c65a7fa10
-  data.tar.gz: 40af6d9dd32c57b4a60e038887fbc4c73c7a6412e25854688b9ff8ddc5ee35c6419d30fcb76ce6e0ee5cdcf491c757a3ebcd1f81ec584ad41243413300b8c40f
+  metadata.gz: 3bf0fb1cf44efc3096388e5adda7503802003e3b49a6539404cefed47ea03af1ca2414089e2599d0d7e0e1676f1a674f3bfadc80131ca4c88401d8c87d38b4c7
+  data.tar.gz: f8ea345eee0bca6cf22ea50f470874becce72795649a0e28bba8df3027c70511634accf961f61aa0647177214e18ad139bb24a5870a534ec9e0de096023b67bc

data/CHANGELOG

@@ -1,5 +1,16 @@
 # CHANGELOG
 
+## 20260710
+
+0.26.1: Refactor Namo::Formulae#attach through a private #bind, and document mutability and the corrected collision-resolution idioms.
+
+1. ~ lib/Namo/Formulae.rb — attach binds each of a formulary's public method names through a new private bind(name, modul): marker guard, host.extend(modul), then self[name] = modul.instance_method(name).bind(host). attach and detach share one private raise_unless_formulary marker guard. bind stays private — attach is its only caller.
+2. ~ README.md: + a "Mutability" section (Namos are mutable; an unfrozen Namo is not a reliable Hash key or Set member since hash tracks data and formula names; the deliberate attr_accessor :data back door and the sanctioned namo << row append idiom); + a private-helper support note under Formularies (a public formulary method resolves its private helpers through the shared host; a same-named helper in a later-attached formulary shadows the earlier one); ~ the collision-resolution passages — correct a prescribed rename operation Namo does not have to the shipped idioms (detach, formula-plus-projection, re-key before ingestion, attach!).
+3. ~ ROADMAP.md: + a note in the deep-freeze open question — the attr_accessor :data back door means a generation counter cannot observe all mutation, deciding the 2.x caching mechanism in deep freeze's favour.
+4. ~ test/Namo/Formulae_test.rb, test/namo_test.rb: identity assertions on stored callables migrate to behavioural ones; + a "private support methods" describe (a public formulary method resolving through its private helper; shared-host same-named-helper shadowing).
+5. ~ docs/: regenerate the print-ready PDFs.
+6. ~ Namo::VERSION: /0.26.0/0.26.1/
+
 ## 20260704
 
 0.26.0: + Namo#detach, Namo::Formulae#detach — remove a formula by name or a formulary's methods by module, completing the attach/attach!/detach family.

data/README.md

@@ -599,6 +599,14 @@ one < two
 
 The dimensions must match; different dimensions raise an `ArgumentError`. Comparing against a non-Namo raises a `TypeError`.
 
+### Mutability
+
+Namos are mutable. Rows append (`<<`), formulae register and remove (`[]=`, `attach`, `detach`), and every view recomputes from current state on the next access — mutability is what the live computation model runs on.
+
+The consequence for the equality machinery above: because `hash` is computed from data and formula names, mutation shifts it, so an *unfrozen* Namo is not a reliable Hash key or Set member — a lookup can miss the entry the Namo was stored under. Freeze marks the transition: mutate during exploration, `freeze` before using a Namo for hash-keyed lookup or sharing it across threads. Enforcement — a deep freeze that propagates to `@data` and `@formulae` — arrives with the 2.x performance phase, where freeze also gates caching; until then `freeze` is Ruby's shallow default and the lifecycle discipline is the user's.
+
+One back door is deliberate: `data` is a public accessor, so `namo.data << row` and whole-array replacement are possible. This is the same trust the constructor extends — Namo takes your array of hashes without copying or validating it — kept open for the surrounding system that owns the data feed. The sanctioned append idiom remains `namo << row`, which guards against data/formula name collisions where the accessor bypasses every guard.
+
 ### Formulae
 
 Define computed dimensions using `[]=`:
@@ -757,10 +765,12 @@ 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 whose keys collide with an existing formula name **raises** an `ArgumentError` naming the collision — a name is data or derived, never both. The guard is symmetric with `attach`'s: `[]=` names one column at the call site, so its scalar form evicts a same-named formula as your explicit intent, but a row is a bulk append you didn't name column-by-column, so the safe response is to refuse rather than let data and a formula of the same name disagree on access. Contract or rename first, then append.
+`<<` 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 whose keys collide with an existing formula name **raises** an `ArgumentError` naming the collision — a name is data or derived, never both. The guard is symmetric with `attach`'s: `[]=` names one column at the call site, so its scalar form evicts a same-named formula as your explicit intent, but a row is a bulk append you didn't name column-by-column, so the safe response is to refuse rather than let data and a formula of the same name disagree on access. Detach the formula (`namo.detach(:signed_volume)`) or re-key the incoming row first, then append.
 
 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.
 
+Private helpers remain fully *usable* in their support role: `attach` extends the whole module onto the internal host, so a public formulary method calling a helper resolves it through ordinary method lookup — only the store, and therefore the dimension namespace, is restricted to the public tier. One caveat of the single shared host: attached formularies share one method-resolution scope, so if two formularies define a *same-named* private helper, the most recently attached one wins — even for calls made from the earlier formulary's own methods. Give helpers distinctive names, or re-attach the formulary whose helper should prevail.
+
 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.)
@@ -770,7 +780,7 @@ The copy is a *snapshot* taken at the moment of attachment, and this is where a
 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.
+- **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, then attach: contract the column away (`namo[-:signed_volume]`); or move it to a new name by formula-plus-projection — register the new name as a formula reading the old (`namo[:raw_signed_volume] = proc{|r| r[:signed_volume]}`) and project the kept dimensions plus the new name, which materialises it as a data column and drops the formula; or re-key the rows before ingestion. `attach!` is the fourth resolution — consenting to the eviction instead.
 - **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.
 

data/lib/Namo/Formulae.rb

@@ -14,13 +14,8 @@ class Namo
     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
+      raise_unless_formulary(modul)
+      modul.public_instance_methods(false).each{|name| bind(name, modul)}
       self
     end
     alias_method :<<, :attach
@@ -30,9 +25,7 @@ class Namo
       when Symbol
         @store.delete(constituent)
       when Module
-        unless constituent.include?(Namo::Formulary)
-          raise ArgumentError, "not a Namo::Formulary: #{constituent}"
-        end
+        raise_unless_formulary(constituent)
         constituent.public_instance_methods(false).each{|name| @store.delete(name)}
       else
         raise TypeError, "can't detach #{constituent.class} from a Formulae; expected a Symbol or a Module (formulary)"
@@ -114,6 +107,19 @@ class Namo
       @host ||= Object.new
     end
 
+    def bind(name, modul)
+      raise_unless_formulary(modul)
+      host.extend(modul)
+      self[name] = modul.instance_method(name).bind(host)
+      self
+    end
+
+    def raise_unless_formulary(modul)
+      unless modul.include?(Namo::Formulary)
+        raise ArgumentError, "not a Namo::Formulary: #{modul}"
+      end
+    end
+
     def collection_scoped?(name)
       required_parameter_count(name) >= 2
     end

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.26.0'
+  VERSION = '0.26.1'
 end

data/test/Namo/Formulae_test.rb

@@ -111,7 +111,8 @@ describe Namo::Formulae do
     it "yields name/callable pairs" do
       yielded = {}
       formulae.each{|name, callable| yielded[name] = callable}
-      _(yielded).must_equal({revenue: revenue})
+      _(yielded.keys).must_equal [:revenue]
+      _(yielded[:revenue].call({price: 10.0, quantity: 100})).must_equal 1000.0
     end
 
     it "returns an enumerator with no block" do
@@ -136,7 +137,7 @@ describe Namo::Formulae do
     it "lets the argument win on a name conflict" do
       other = proc{|r| 0}
       merged = formulae.merge(Namo::Formulae.new({revenue: other}))
-      _(merged[:revenue]).must_be_same_as other
+      _(merged[:revenue].call({price: 10.0, quantity: 100})).must_equal 0
     end
 
     it "does not mutate the receiver" do
@@ -177,7 +178,9 @@ describe Namo::Formulae do
 
     it "supports select returning name/callable pairs" do
       formulae[:cost] = cost
-      _(formulae.select{|name, _| name == :cost}).must_equal [[:cost, cost]]
+      selected = formulae.select{|name, _| name == :cost}
+      _(selected.map(&:first)).must_equal [:cost]
+      _(selected.first.last.call({quantity: 100})).must_equal 400.0
     end
   end
 
@@ -207,6 +210,12 @@ describe Namo::Formulae do
     it "defaults to an empty store" do
       _(Namo::Formulae.new.keys).must_equal []
     end
+
+    it "stores a seeded callable as given, resolvable thereafter" do
+      formulae = Namo::Formulae.new({revenue: revenue})
+      _(formulae[:revenue]).must_be_same_as revenue
+      _(formulae.derive(:revenue, {price: 10.0, quantity: 100}, nil)).must_equal 1000.0
+    end
   end
 
   describe "formulary tier" do
@@ -258,6 +267,20 @@ describe Namo::Formulae do
         formulae = Namo::Formulae.new.attach(delta).attach(other)
         _(formulae[:signed_volume].receiver).must_be_same_as formulae[:momentum].receiver
       end
+
+      it "stores a formulary's methods as Methods owned by the module, bound to the shared host" do
+        _(attached[:signed_volume]).must_be_kind_of Method
+        _(attached[:signed_volume].owner).must_be_same_as delta
+        _(attached.derive(:signed_volume, {buys: 60, sells: 40}, nil)).must_equal 20
+      end
+
+      it "lets a []= overwrite take effect after an anonymous formulary attached the name" do
+        formulae = Namo::Formulae.new
+        formulae[:signed_volume] = proc{|r| 1}
+        formulae.attach(delta)
+        formulae[:signed_volume] = proc{|r| 0}
+        _(formulae.derive(:signed_volume, {buys: 60, sells: 40}, nil)).must_equal 0
+      end
     end
 
     describe "#<<" do
@@ -328,6 +351,15 @@ describe Namo::Formulae do
         formulae = Namo::Formulae.new.attach(delta).attach(alt)
         _(formulae.derive(:signed_volume, {buys: 60, sells: 40}, nil)).must_equal 999
       end
+
+      it "brings a shadowed formulary's definition back when it is re-attached (binds the module's own method, not the shared host's ancestry order)" do
+        alt = Module.new do
+          include Namo::Formulary
+          def signed_volume(row); 999; end
+        end
+        formulae = Namo::Formulae.new.attach(delta).attach(alt).attach(delta)
+        _(formulae.derive(:signed_volume, {buys: 60, sells: 40}, nil)).must_equal 20
+      end
     end
 
     describe "#detach" do

data/test/namo_test.rb

@@ -3,6 +3,13 @@ require 'minitest-spec-context'
 
 require_relative '../lib/namo'
 
+module SupportedFlow
+  include Namo::Formulary
+  def net_volume(row); gross(row) - row[:sells] * 2; end
+  private
+  def gross(row); row[:buys] + row[:sells]; end
+end
+
 describe Namo do
   let(:sample_data) do
     [
@@ -1028,6 +1035,36 @@ describe Namo do
         _(proc{flows.detach(untagged)}).must_raise ArgumentError
       end
     end
+
+    describe "private support methods" do
+      it "resolves a public formulary method through its private helper" do
+        namo = Namo.new(flow_data).attach(SupportedFlow)
+        _(namo.values(:net_volume)).must_equal [20, -40, 0]
+        _(namo.derived_dimensions).must_equal [:net_volume]
+      end
+
+      it "resolves an anonymous formulary's public method through its private helper (carrier-collected, host-resolved)" do
+        anonymous = Module.new do
+          include Namo::Formulary
+          def net_volume(row); gross(row) - row[:sells] * 2; end
+          private
+          def gross(row); row[:buys] + row[:sells]; end
+        end
+        namo = Namo.new(flow_data).attach(anonymous)
+        _(namo.values(:net_volume)).must_equal [20, -40, 0]
+      end
+
+      it "lets a later-attached formulary's same-named private helper shadow the earlier one (single shared host)" do
+        shadower = Module.new do
+          include Namo::Formulary
+          def momentum(row); 0; end
+          private
+          def gross(row); 0; end
+        end
+        namo = Namo.new(flow_data).attach(SupportedFlow).attach(shadower)
+        _(namo.values(:net_volume)).must_equal [-80, -240, -150]
+      end
+    end
   end
 
   describe "formularies via class include" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: namo
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.26.1
 platform: ruby
 authors:
 - thoran
@@ -98,7 +98,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.15
 specification_version: 4
 summary: Named dimensional data for Ruby.
 test_files: []