namo 0.32.4 → 0.32.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fdd20fc3b0502a069ad6bf5781b183a00e1955b6b204e76a0c14551d54a7ea28
-  data.tar.gz: 6963897982afa093c48cde988071fa7bbc0c756cbf46e05ebd776ca695ed1008
+  metadata.gz: fca34f0fc6464ae1bbb80a5df45f40b63c496369b7cfbc6b32090e26bf0938f3
+  data.tar.gz: f156784556a7fcd2a28cef6f44178e0c4b115617cd5e64f173cfb42ca768fb53
 SHA512:
-  metadata.gz: f9eb25cbc7db9c7af7f9f12e88be7893c972cdd4f76a3d4bf5133a6423ea41cbf27378d9a4e9e890dc09a2c38e73b1b76e4cd7218dcd08bba6bed0d49a0f440c
-  data.tar.gz: 1683cd38dfaf86011f61f2d527ba05c15c2c79eaec8cc65d4e40bd02287bca3ff80d0ebd8f8d5f91f3e5f2b4ffcb7077958a5c50af42b39db6aa05f853873f87
+  metadata.gz: e47d75b0e5a23a4f131de7d8d3865dc27ad74ef91a2e87cb7c8d36a2c127784a11cf1b767978ec54b6fabf48c99f25f9a09839e229d3abd36f3851d801549257
+  data.tar.gz: c1f4a2ae0e3946c4c02e1f4d643b18666214224b58602ffd9185410f7e66ea949d96a1521582f98b095b9cf7b703f665014e8e42f43ed7ef65a4647da3b8efc5

data/CHANGELOG

@@ -1,5 +1,17 @@
 # CHANGELOG
 
+## 20261003
+
+0.32.5: Documentation clean up.
+
+1. ~ README.md: + what Symbol#-@ costs, and why `/` dedupes.
+2. ~ COMPARISON.md: decomposition is relational projection, dedup and all.
+3. ~ ROADMAP.md: + the 0.9.0 memoir's 2026-10 note and the "How the demonstration ships" section.
+4. ~ lib/namo.rb: the inspected_rows comment corrected.
+5. ~ namo.gemspec: the gem name heads the file list.
+6. ~ CHANGELOG: the 0.21.0, 0.22.0 and 0.23.0 entries aligned with the commit message for each.
+7. ~ Namo::VERSION: /0.32.4/0.32.5/
+
 ## 20260828
 
 0.32.4: ~ README.md: + Console, the command the gem has shipped since 0.32.0 going unmentioned until now.
@@ -10,7 +22,6 @@
 4. ~ CHANGELOG: the 20260828 releases gather under one heading, as 20260824 and 20260826 gather theirs. Four releases in a day had taken a heading each.
 5. ~ Namo::VERSION: /0.32.3/0.32.4/
 
-
 0.32.3: ~ install.sh: + ruby-install, for a machine with no package manager at all; the handover is to a clone's own bin/namo where the script was run from one.
 
 1. ~ install.sh: + install_ruby_install, + ruby_from_ruby_install. Where no package manager is found and Homebrew is declined, ruby-install is offered — fetched from its latest release rather than a pinned version, built with make as root, and used to build Ruby. It is the last thing tried and the only route here which builds Ruby rather than fetching it.
@@ -21,7 +32,6 @@
 6. ~ install.sh: + repository, and hand_over takes the clone it was given. install_namo is the bootstrap for the handover and nothing else — a way to have a namo command to run — so a script run from a checkout hands over to that checkout's bin/namo and leaves the gem to `namo setup`, which installs it as its own first act. A checkout with the gem not yet installed now works as it stands, and the gem is named once rather than by both scripts in turn. 0.32.1 had taken the path lookup out for being unconditional, which failed piped from curl where the working directory is not a checkout; it is guarded now on $0 being a readable file beside both bin/namo and the gemspec, none of which holds for the shell's own name, so the curl route finds nothing and installs the gem as it did.
 7. ~ Namo::VERSION: /0.32.2/0.32.3/
 
-
 0.32.2: ~ install.sh: the one command ends with namo runnable from anywhere.
 
 1. ~ install.sh: + add_to_path, + gem_bin_directory, + shell_configuration_file. gem puts the command in a directory which is on the PATH on some machines and not on others — Homebrew's ruby puts it somewhere which is not — so the run ended by naming the directory and stopping. It now offers to add it to the shell's configuration file, and adds it to the PATH of the run itself so that `namo setup` happens rather than being left as a further instruction.
@@ -30,7 +40,6 @@
 4. ~ install.sh: + apt-get, dnf, pacman and zypper alongside Homebrew and MacPorts, so the script reaches a Ruby on Linux rather than offering to install Homebrew on a machine which has apt. + install_with_sudo, every package manager but Homebrew installing as root, so the password is asked for by name rather than arriving unannounced.
 5. ~ Namo::VERSION: /0.32.1/0.32.2/
 
-
 0.32.1: ~ install.sh: it runs the same piped from curl as from a clone, and forces no package manager; ~ README.md: + the one-line install.
 
 1. ~ install.sh: the handover is to `namo setup` on the PATH rather than to bin/namo beside the script. It had found bin/namo by its own path, so piped from curl it looked in the working directory and failed there. It now finds nothing by its path and so runs from anywhere. The check is for the namo command rather than for the gem, that being what the next step needs: an older namo installs no executable.

data/README.md

@@ -214,6 +214,8 @@ The `-:price` syntax uses unary minus on Symbol to produce a negated dimension.
 sales[:product, -:price]  # => ArgumentError
 ```
 
+`-:price` is not a local trick: unary minus is defined on Symbol itself (`lib/Symbol.rb`), so once `namo` is loaded, every Symbol in the process has a `-@` it did not have before. Nothing in Ruby or its standard library reads a negated Symbol as anything — the ground was empty — so a collision would take another library claiming the same operator for its own purpose, and contraction is the part of Namo which yields if one does.
+
 Selection and contraction can be chained:
 
 ```ruby
@@ -497,7 +499,7 @@ combined / fundamentals
 
 The intersection of dimensions — here `:symbol` and `:pe` — is removed. Everything else stays. The projected rows are deduplicated, so `/` answers "what's left when these dimensions are factored out?" rather than "what rows survive a column drop?". Formulae carry through from the left-hand side.
 
-`/` has no precondition. When the two Namos share no dimensions, the intersection is empty, nothing is removed, and `self / other` returns a Namo equal to self:
+`/` has no precondition. When the two Namos share no dimensions, the intersection is empty, nothing is removed, and `self / other` returns a Namo equal to self (multiplicity aside — the deduplication above still applies, so "equal" here means equal on duplicate-free rows):
 
 ```ruby
 shipments = Namo.new([{order_id: 1, weight: 10}])
@@ -507,7 +509,7 @@ shipments / weather
 # => #<Namo [{order_id: 1, weight: 10}]> — equal to shipments
 ```
 
-The round-trip identity holds for the `**` case exactly:
+The round-trip identity holds for the `**` case exactly — again on duplicate-free rows, for the reason given below:
 
 ```ruby
 a = Namo.new([{symbol: 'BHP'}, {symbol: 'RIO'}])
@@ -525,7 +527,7 @@ b = Namo.new([{symbol: 'BHP', pe: 14.5}, {symbol: 'RIO', pe: 9.2}])
 
 (a * b) / b
 # => #<Namo [{close: 42.5}, {close: 118.3}]>
-# Equal to a[-:symbol]. :symbol was shared and is lost.
+# Equal to a[-:symbol] on duplicate-free rows. :symbol was shared and is lost.
 ```
 
 The asymmetry is inherent: `/` operates only on the two values it receives and can't distinguish "shared dimension that belonged to both" from "exclusive dimension that belonged only to the right". Removing the intersection is the only rule expressible from the operands alone, and it gives clean recovery from `**` and well-defined (if lossy) recovery from `*`.
@@ -534,14 +536,20 @@ The asymmetry is inherent: `/` operates only on the two values it receives and c
 
 `*` and `**` raise when their preconditions are violated — combining unrelated Namos has no natural answer, and silently producing arbitrary output would turn a logic error into a large pile of nonsense rows. `/` is different: it's a projecting operator, not a combining one, and projecting away nothing returns the original. The no-precondition rule isn't a fallback; it's the structurally correct result.
 
-This earns `/` three properties a strict version would lose:
+This earns `/` three properties a strict version would lose, each stated for duplicate-free rows (the projection deduplicates; see below):
 
 - **Identity test.** `combined / other == combined` exactly when the two have no shared dimensions — answers "are these Namos dimensionally independent?" without explicit introspection. Same shape as `a & b == a` answering subset from 0.6.0.
 - **Idempotence.** `(c / b) / b == c / b`. Once `b`'s dimensions are removed, removing them again does nothing.
-- **Pipeline composition.** A processing step that applies `/ separator` can run over any Namo regardless of whether the separator's dimensions apply. Uninvolved Namos pass through unchanged; involved Namos get stripped. The pipeline doesn't need to special-case applicability.
+- **Pipeline composition.** A processing step that applies `/ separator` can run over any Namo regardless of whether the separator's dimensions apply. Uninvolved Namos pass through stripped of nothing but duplicate rows; involved Namos get their shared dimensions stripped. The pipeline doesn't need to special-case applicability.
 
 This is the same pattern that makes `Array#-` useful with arrays that aren't subsets: `[1, 2, 3] - [9] == [1, 2, 3]`, not an error. The no-op-on-non-applicable behaviour lets the operator compose into pipelines that don't know in advance whether the operation applies.
 
+#### Why `/` dedupes
+
+`/` is the one operator outside the set family (`&`, `|`, `^`) and the explicitly collapsing verbs (`uniq`, `coordinates`) that drops multiplicities — everywhere else duplicate rows are data. The collapse is definitional, and is in fact what makes `/` the inverse of the composers at all: `**` with a multi-row right operand manufactures multiplicities on the left operand's rows, so any projection that kept them could never satisfy `(a ** b) / b == a`. Inversion is only a function once duplicates are collapsed.
+
+Projection with multiplicities intact is one line of existing operators: `namo[*other.data_dimensions.map{|d| -d}]` — contraction over the other operand's dimensions. `[]`, contraction, and everything else in the row algebra are bag-faithful, so nothing essential goes unspellable; what `/` alone adds over the contraction spelling is operand-keying plus the collapse, which is to say, its role as the composition algebra's decomposer.
+
 ### Equality
 
 Comparison on Namos is **multiset-theoretic on rows**: the comparison operators — `==`, `eql?`, `===`, `<`, `<=`, `>`, `>=` — ignore row order, so two Namos holding the same rows in a different order compare equal, while row multiplicities count (they *are* data). That stance is shared across the equality, pattern-match, and subset/superset operators documented below. Row order is otherwise preserved: `to_h` and `values` depend on it for columnar alignment, and `each`, `first`, `last`, `take`, `drop`, and `+` all observe it. It is the comparison operators alone that treat the sequence of rows as a multiset.

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.32.4'
+  VERSION = '0.32.5'
 end

data/lib/namo.rb

@@ -306,9 +306,10 @@ class Namo
     @name.nil? ? '' : " #{@name.inspect}"
   end
 
-  # The rows as they are stored, never the derived values: inspect is called
-  # for every result in a console, and evaluating a formula there would cost a
-  # pass over the data per access and raise whatever the formula raises.
+  # inspect is called for every result in a console, so evaluating the derived
+  # dimensions is bounded to the rows shown — INSPECTED_ROWS of them, one
+  # evaluation each — and a formula which raises renders no value rather than
+  # raising out of inspect.  The cost is constant however large the data.
   def inspected_rows(rendered)
     return ' []' if @data.empty?
     shown = rendered.map{|row, derived| "  #{row.merge(derived).inspect}"}.join(",\n")

data/namo.gemspec

@@ -27,13 +27,13 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.files = [
+    'namo.gemspec',
     Dir['bin/*'],
     Dir['lib/**/*.rb'],
     Dir['test/**/*.rb'],
     'CHANGELOG',
     'Gemfile',
     'LICENSE',
-    'namo.gemspec',
     'Rakefile',
     'README.md',
   ].flatten

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: namo
 version: !ruby/object:Gem::Version
-  version: 0.32.4
+  version: 0.32.5
 platform: ruby
 authors:
 - thoran
@@ -105,7 +105,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.19
+rubygems_version: 4.0.21
 specification_version: 4
 summary: Named dimensional data for Ruby.
 test_files: []