namo 0.25.1 → 0.26.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd20f662edb4f305d6c74b5a100c536c20ad57ce31f7044498f76eebe2fbbf68
-  data.tar.gz: e242043273cac5866c8dda07aec202c69954d36072f8092b50bb817b6ca24bb8
+  metadata.gz: 40ae1191c5889356a1f8442673b3f44588521aa07f3f379fe58c9afa85b574c8
+  data.tar.gz: c38c7996e0a31e6050adcd9162dbbd6bde3b1c8b12cbaf0b1ab6a7848eeffb78
 SHA512:
-  metadata.gz: 581cbeae8e0eeca1fb35db857d2acad566ecd21dc8d967e921161620b6a994e26293b17026e806c0c754851fe8da175bf3e260afe98e8f2899853fcb1e20fda3
-  data.tar.gz: cdc1687745394bf2931469daf7823d0c724436aea4a0c4657505f39beae1afe8a6224406682f9d630672a12fc6554b9872044ee8d72d93acfd03d7459bb32282
+  metadata.gz: 3bf0fb1cf44efc3096388e5adda7503802003e3b49a6539404cefed47ea03af1ca2414089e2599d0d7e0e1676f1a674f3bfadc80131ca4c88401d8c87d38b4c7
+  data.tar.gz: f8ea345eee0bca6cf22ea50f470874becce72795649a0e28bba8df3027c70511634accf961f61aa0647177214e18ad139bb24a5870a534ec9e0de096023b67bc

data/CHANGELOG

@@ -1,5 +1,29 @@
 # 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.
+
+detach becomes the sanctioned formula-removal idiom, displacing the namo.formulae.delete(:name) reach-through. It is by-name with no provenance (the store is a snapshot): the Module arm removes whatever currently holds each of the module's method names. There is no detach! (removing a formula can't collide with data, so no guard to force through) and no removal operator (<< appends; per the 0.14.0 principle, no >>).
+
+1. + Namo::Formulae#detach(constituent) — dispatches a Symbol to @store.delete(constituent); a Module to deleting each of its public_instance_methods(false) names, after the same Namo::Formulary marker guard attach uses (an untagged module raises ArgumentError); anything else raises TypeError naming the class, in the << else-arm's style. Returns self. Placed directly after attach/<<. Formulae#delete is unchanged — it stays the store-level primitive detach sits on.
+2. + Namo#detach(constituent) — forwards to @formulae.detach and returns self, placed with the attach family (after attach!, before <<). No guard at the Namo level: there is no data-side interaction, so the Formulae worker owns the dispatch and the raises. Collection inherits detach harmlessly.
+3. ~ test/Namo/Formulae_test.rb: + a "#detach" describe in the formulary tier — both arms return self; the Symbol arm removes the named formula and no-ops on an absent name; the Module arm removes exactly the formulary's method names, leaves a []= name it doesn't contribute, and deletes a []= overwrite occupying a formulary-method name (the by-name/no-provenance pin); ArgumentError on an untagged module; TypeError on a String and a Hash naming the class; chaining removes both. ~ test/namo_test.rb: + a "#detach" describe under formularies — returns the Namo; removes a []= formula from the queryable namespace (derived_dimensions drops it, values returns one nil per row); leaves other formulae resolving; the Module arm empties derived_dimensions; a data dimension is a no-op (the column survives); an absent name no-ops returning the Namo; TypeError on a non-Symbol non-Module and ArgumentError on an untagged module; the #dimensions "reflects mutation" test migrates sales.formulae.delete(:revenue) to sales.detach(:revenue). ~ test/Namo/Collection_test.rb: + a "#detach" describe pinning that a Collection inherits detach — a formulary attached to the collection detaches, so the detail rows no longer resolve its name.
+4. ~ README.md: + a "Removing a formula" note under Formulae (detach removes a formula, returns the Namo, chains, no-ops on an absent name; complements contraction across the data/derived and algebra/mutation splits; never touches @data); + a detach(Module) note in the Formularies section (the reverse of attach, by-name with no provenance, raises on an untagged module, the attach/attach!/detach family, no << removal counterpart, no detach!).
+5. ~ ROADMAP.md: + the 0.26.0 release entry recording the settled decisions (by-name/no-provenance, marker required, loose-on-absent, derived-side-only, no-bang, no-operator, single-argument/chaining, untouched-host-ancestry); current-state bumped to 0.26.0; detach folded into the Summary's formulary vocabulary and the 1.0.0 feature list.
+6. ~ Namo::VERSION: /0.25.1/0.26.0/
+
 ## 20260703
 
 0.25.1: Fix documentation and reformat CHANGELOG to use Markdown headers.

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 `[]=`:
@@ -716,6 +724,12 @@ prices[:sma_close_20] = proc{|row| row[:sma, :close, 20]}
 prices[:date, :sma_close_20]   # materialises per the usual projection rule
 ```
 
+#### Removing a formula
+
+`detach(:name)` removes a formula, returns the Namo, and chains — `sales.detach(:revenue).detach(:cost)`. Detaching a name that isn't there is a quiet no-op, so a cleanup step composes over any Namo without first checking whether the formula is present. It is the sanctioned way to drop a derived dimension, sitting over the store-level primitive `formulae.delete`.
+
+`detach` and contraction are complements across two axes. Contraction (`sales[-:price]`) is non-mutating — it returns a *new* Namo with a *data* dimension removed and the formulae carried. `detach` mutates the receiver and removes a *derived* dimension. So the pair spans both the data/derived split and the algebra/mutation split: contraction is algebra over data, `detach` is mutation of the derived side. `detach` never touches `@data` — naming a data dimension is a no-op and the column survives; removing a data dimension is contraction's job.
+
 #### 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:
@@ -751,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.)
@@ -764,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.
 
@@ -772,6 +788,8 @@ Because each method is copied into the store, the rules already governing `[]=`
 
 Note that there is no counterpart in `[]=`'s scalar-over-formula eviction and is worth naming: a formulary method that reads a column its own name evicts will **recurse** on access. The eviction removes the datum, and exclusive storage leaves no shadowed value behind the formula, so `Row#[]` re-enters the formula rather than falling back to data — a `def close(row); row[:close] * ...; end` attached with `attach!` over a `:close` data column has no `:close` data left to read. `[]=` rarely bites this way because you write the proc at the call site, beside the name it replaces; a formulary is authored elsewhere, so a method reading its own evicted column is easy to attach without noticing. Self-reference is unguarded here as everywhere in the formula mechanism — keep a formulary's inputs and outputs under distinct names, or `attach` (not `attach!`) and contract deliberately.
 
+`detach(OrderFlow)` is the reverse of `attach`: it removes the formulary's public method names from the store, so `flows.attach(OrderFlow)` then `flows.detach(OrderFlow)` leaves the formulae as they started. It works by name and keeps no provenance — the store is a snapshot, so `detach` removes *whatever currently holds each name*, including a `[]=` formula that later overwrote a formulary method of the same name. Like the `attach` side, the marker is required: `detach` raises `ArgumentError` for an untagged module, so you can only detach what could have been attached. The mutating family is `attach` / `attach!` / `detach`; `<<` has no removal counterpart (it *appends* constituents — a removal operator would be cuteness over clarity), and there is no `detach!` because removing a formula can't collide with data, so there is no guard for a bang to force through.
+
 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`).

data/lib/Namo/Formulae.rb

@@ -14,17 +14,25 @@ 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
 
+    def detach(constituent)
+      case constituent
+      when Symbol
+        @store.delete(constituent)
+      when Module
+        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)"
+      end
+      self
+    end
+
     def derive(name, row, namo, *arguments)
       formula = self[name]
       if collection_scoped?(name)
@@ -99,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.25.1'
+  VERSION = '0.26.1'
 end

data/lib/namo.rb

@@ -103,6 +103,11 @@ class Namo
     self
   end
 
+  def detach(constituent)
+    @formulae.detach(constituent)
+    self
+  end
+
   def <<(constituent)
     case constituent
     when Module then attach(constituent)

data/test/Namo/Collection_test.rb

@@ -145,6 +145,15 @@ describe Namo::Collection do
     end
   end
 
+  describe "#detach" do
+    it "detaches a formulary attached to the collection, so the detail rows no longer resolve its name" do
+      collection << component_pricing
+      _(collection.values(:cost_per_kg)).must_equal [250, 250, 200, 250]
+      collection.detach(component_pricing)
+      _(collection.derived_dimensions).wont_include :cost_per_kg
+    end
+  end
+
   describe "#find" do
     it "returns the member with the given name" do
       _(collection.find(:chassis)).must_be_same_as chassis

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,73 @@ 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
+      it "returns self for a Symbol" do
+        _(attached.detach(:signed_volume)).must_be_same_as attached
+      end
+
+      it "returns self for a Module" do
+        _(attached.detach(delta)).must_be_same_as attached
+      end
+
+      it "removes the named formula, leaving the others" do
+        attached.detach(:signed_volume)
+        _(attached.key?(:signed_volume)).must_equal false
+        _(attached.key?(:echo_namo)).must_equal true
+      end
+
+      it "is a no-op on an absent name, still returning self" do
+        _(attached.detach(:missing)).must_be_same_as attached
+        _(attached.key?(:signed_volume)).must_equal true
+      end
+
+      it "removes exactly the formulary's public method names via the Module arm" do
+        attached.detach(delta)
+        _(attached.keys).must_equal []
+      end
+
+      it "leaves a []= formula not among the formulary's methods when detaching the module" do
+        attached[:extra] = proc{|r| 0}
+        attached.detach(delta)
+        _(attached.key?(:extra)).must_equal true
+      end
+
+      it "deletes a []= overwrite occupying a formulary-method name" do
+        attached[:signed_volume] = proc{|r| 0}
+        attached.detach(delta)
+        _(attached.key?(:signed_volume)).must_equal false
+      end
+
+      it "raises ArgumentError for an untagged module" do
+        _(proc{attached.detach(untagged)}).must_raise ArgumentError
+      end
+
+      it "raises TypeError for a String, naming the class" do
+        error = _(proc{attached.detach("signed_volume")}).must_raise TypeError
+        _(error.message).must_match(/String/)
+      end
+
+      it "raises TypeError for a Hash, naming the class" do
+        error = _(proc{attached.detach({})}).must_raise TypeError
+        _(error.message).must_match(/Hash/)
+      end
+
+      it "chains, removing both named formulae" do
+        formulae[:cost] = cost
+        formulae.detach(:revenue).detach(:cost)
+        _(formulae.keys).must_equal []
+      end
     end
 
     describe "carry-through" 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
     [
@@ -165,7 +172,7 @@ describe Namo do
     it "reflects mutation on the next call" do
       sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
       _(sales.dimensions).must_include :revenue
-      sales.formulae.delete(:revenue)
+      sales.detach(:revenue)
       _(sales.dimensions).wont_include :revenue
     end
   end
@@ -978,6 +985,86 @@ describe Namo do
         _(flows === other).must_equal true
       end
     end
+
+    describe "#detach" do
+      it "returns the Namo" do
+        _(flows.detach(:signed_volume)).must_be_same_as flows
+      end
+
+      it "removes a formula from the queryable namespace" do
+        namo = Namo.new(flow_data)
+        namo[:revenue] = proc{|r| r[:buys]}
+        namo.detach(:revenue)
+        _(namo.derived_dimensions).wont_include :revenue
+        _(namo.values(:revenue)).must_equal [nil, nil, nil]
+      end
+
+      it "leaves other formulae resolving" do
+        namo = Namo.new(flow_data)
+        namo[:revenue] = proc{|r| r[:buys]}
+        namo[:tally] = proc{|r| r[:sells]}
+        namo.detach(:revenue)
+        _(namo.values(:tally)).must_equal [40, 120, 75]
+      end
+
+      it "removes an attached formulary's methods via the Module arm" do
+        flows.detach(delta)
+        _(flows.derived_dimensions).must_equal []
+      end
+
+      it "never exposed the formulary's private helper" do
+        _(flows.derived_dimensions).wont_include :helper
+      end
+
+      it "never touches data — a data dimension is a no-op" do
+        flows.detach(:date)
+        _(flows.data_dimensions).must_include :date
+        _(flows.values(:date)).must_equal [1, 2, 3]
+      end
+
+      it "is a no-op on an absent name, returning the Namo" do
+        _(flows.detach(:missing)).must_be_same_as flows
+        _(flows.values(:signed_volume)).must_equal [20, -40, 0]
+      end
+
+      it "raises TypeError on a non-Symbol non-Module" do
+        _(proc{flows.detach("signed_volume")}).must_raise TypeError
+      end
+
+      it "raises ArgumentError on an untagged module" 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.25.1
+  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: []