ucon 2.2.1__tar.gz → 2.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. {ucon-2.2.1 → ucon-2.3.0}/CHANGELOG.md +413 -0
  2. {ucon-2.2.1/ucon.egg-info → ucon-2.3.0}/PKG-INFO +1 -1
  3. ucon-2.3.0/ROADMAP.md +268 -0
  4. {ucon-2.2.1 → ucon-2.3.0}/ucon/__init__.py +8 -0
  5. {ucon-2.2.1 → ucon-2.3.0}/ucon/_cache.py +27 -1
  6. {ucon-2.2.1 → ucon-2.3.0}/ucon/comprehensive.ucon.toml +34 -0
  7. {ucon-2.2.1 → ucon-2.3.0}/ucon/contexts.py +31 -2
  8. {ucon-2.2.1 → ucon-2.3.0}/ucon/conversion.py +325 -38
  9. {ucon-2.2.1 → ucon-2.3.0}/ucon/core/__init__.py +8 -0
  10. {ucon-2.2.1 → ucon-2.3.0}/ucon/core/_types.py +807 -13
  11. ucon-2.3.0/ucon/core/exceptions.py +361 -0
  12. {ucon-2.2.1 → ucon-2.3.0}/ucon/formulas/__init__.py +2 -0
  13. {ucon-2.2.1 → ucon-2.3.0}/ucon/formulas/exceptions.py +44 -1
  14. {ucon-2.2.1 → ucon-2.3.0}/ucon/formulas/registry.py +83 -10
  15. ucon-2.3.0/ucon/maps.py +1060 -0
  16. {ucon-2.2.1 → ucon-2.3.0}/ucon/packages.py +158 -4
  17. {ucon-2.2.1 → ucon-2.3.0}/ucon/parsing/namespaces.py +4 -0
  18. {ucon-2.2.1 → ucon-2.3.0}/ucon/serialization.py +34 -9
  19. {ucon-2.2.1 → ucon-2.3.0}/ucon/units.pyi +1 -0
  20. {ucon-2.2.1 → ucon-2.3.0/ucon.egg-info}/PKG-INFO +1 -1
  21. {ucon-2.2.1 → ucon-2.3.0}/ucon.egg-info/scm_file_list.json +10 -0
  22. ucon-2.3.0/ucon.egg-info/scm_version.json +8 -0
  23. ucon-2.2.1/ROADMAP.md +0 -163
  24. ucon-2.2.1/ucon/core/exceptions.py +0 -150
  25. ucon-2.2.1/ucon/maps.py +0 -561
  26. ucon-2.2.1/ucon.egg-info/scm_version.json +0 -8
  27. {ucon-2.2.1 → ucon-2.3.0}/.github/workflows/downstream.yaml +0 -0
  28. {ucon-2.2.1 → ucon-2.3.0}/.github/workflows/publish.yaml +0 -0
  29. {ucon-2.2.1 → ucon-2.3.0}/.github/workflows/tests.yaml +0 -0
  30. {ucon-2.2.1 → ucon-2.3.0}/.gitignore +0 -0
  31. {ucon-2.2.1 → ucon-2.3.0}/.gitmodules +0 -0
  32. {ucon-2.2.1 → ucon-2.3.0}/LICENSE +0 -0
  33. {ucon-2.2.1 → ucon-2.3.0}/MANIFEST.in +0 -0
  34. {ucon-2.2.1 → ucon-2.3.0}/Makefile +0 -0
  35. {ucon-2.2.1 → ucon-2.3.0}/NOTICE +0 -0
  36. {ucon-2.2.1 → ucon-2.3.0}/README.md +0 -0
  37. {ucon-2.2.1 → ucon-2.3.0}/SECURITY.md +0 -0
  38. {ucon-2.2.1 → ucon-2.3.0}/SUPPORT.md +0 -0
  39. {ucon-2.2.1 → ucon-2.3.0}/mkdocs.yml +0 -0
  40. {ucon-2.2.1 → ucon-2.3.0}/netlify.toml +0 -0
  41. {ucon-2.2.1 → ucon-2.3.0}/pyproject.toml +0 -0
  42. {ucon-2.2.1 → ucon-2.3.0}/requirements.txt +0 -0
  43. {ucon-2.2.1 → ucon-2.3.0}/setup.cfg +0 -0
  44. {ucon-2.2.1 → ucon-2.3.0}/ucon/_active.py +0 -0
  45. {ucon-2.2.1 → ucon-2.3.0}/ucon/_algebra_cache.py +0 -0
  46. {ucon-2.2.1 → ucon-2.3.0}/ucon/_bootstrap.py +0 -0
  47. {ucon-2.2.1 → ucon-2.3.0}/ucon/aspects/__init__.py +0 -0
  48. {ucon-2.2.1 → ucon-2.3.0}/ucon/aspects/exceptions.py +0 -0
  49. {ucon-2.2.1 → ucon-2.3.0}/ucon/aspects/forest.py +0 -0
  50. {ucon-2.2.1 → ucon-2.3.0}/ucon/aspects/resolution.py +0 -0
  51. {ucon-2.2.1 → ucon-2.3.0}/ucon/aspects/types.py +0 -0
  52. {ucon-2.2.1 → ucon-2.3.0}/ucon/basis/__init__.py +0 -0
  53. {ucon-2.2.1 → ucon-2.3.0}/ucon/basis/builtin.py +0 -0
  54. {ucon-2.2.1 → ucon-2.3.0}/ucon/basis/graph.py +0 -0
  55. {ucon-2.2.1 → ucon-2.3.0}/ucon/basis/ops.py +0 -0
  56. {ucon-2.2.1 → ucon-2.3.0}/ucon/basis/transforms.py +0 -0
  57. {ucon-2.2.1 → ucon-2.3.0}/ucon/basis/types.py +0 -0
  58. {ucon-2.2.1 → ucon-2.3.0}/ucon/basis/vector.py +0 -0
  59. {ucon-2.2.1 → ucon-2.3.0}/ucon/checking.py +0 -0
  60. {ucon-2.2.1 → ucon-2.3.0}/ucon/constants.py +0 -0
  61. {ucon-2.2.1 → ucon-2.3.0}/ucon/constants.pyi +0 -0
  62. {ucon-2.2.1 → ucon-2.3.0}/ucon/core/_parsing_graph.py +0 -0
  63. {ucon-2.2.1 → ucon-2.3.0}/ucon/dimension.py +0 -0
  64. {ucon-2.2.1 → ucon-2.3.0}/ucon/dimension.pyi +0 -0
  65. {ucon-2.2.1 → ucon-2.3.0}/ucon/expressions.py +0 -0
  66. {ucon-2.2.1 → ucon-2.3.0}/ucon/formulas/types.py +0 -0
  67. {ucon-2.2.1 → ucon-2.3.0}/ucon/graph.py +0 -0
  68. {ucon-2.2.1 → ucon-2.3.0}/ucon/integrations/__init__.py +0 -0
  69. {ucon-2.2.1 → ucon-2.3.0}/ucon/integrations/numpy.py +0 -0
  70. {ucon-2.2.1 → ucon-2.3.0}/ucon/integrations/pandas.py +0 -0
  71. {ucon-2.2.1 → ucon-2.3.0}/ucon/integrations/polars.py +0 -0
  72. {ucon-2.2.1 → ucon-2.3.0}/ucon/integrations/pydantic.py +0 -0
  73. {ucon-2.2.1 → ucon-2.3.0}/ucon/kinds/__init__.py +0 -0
  74. {ucon-2.2.1 → ucon-2.3.0}/ucon/kinds/exceptions.py +0 -0
  75. {ucon-2.2.1 → ucon-2.3.0}/ucon/kinds/lattice.py +0 -0
  76. {ucon-2.2.1 → ucon-2.3.0}/ucon/kinds/types.py +0 -0
  77. {ucon-2.2.1 → ucon-2.3.0}/ucon/parsing/__init__.py +0 -0
  78. {ucon-2.2.1 → ucon-2.3.0}/ucon/parsing/aspects.py +0 -0
  79. {ucon-2.2.1 → ucon-2.3.0}/ucon/parsing/dimensions.py +0 -0
  80. {ucon-2.2.1 → ucon-2.3.0}/ucon/parsing/formulas.py +0 -0
  81. {ucon-2.2.1 → ucon-2.3.0}/ucon/parsing/kinds.py +0 -0
  82. {ucon-2.2.1 → ucon-2.3.0}/ucon/parsing/lexer.py +0 -0
  83. {ucon-2.2.1 → ucon-2.3.0}/ucon/parsing/quantity.py +0 -0
  84. {ucon-2.2.1 → ucon-2.3.0}/ucon/parsing/units.py +0 -0
  85. {ucon-2.2.1 → ucon-2.3.0}/ucon/quantity.py +0 -0
  86. {ucon-2.2.1 → ucon-2.3.0}/ucon/resolver.py +0 -0
  87. {ucon-2.2.1 → ucon-2.3.0}/ucon/system/__init__.py +0 -0
  88. {ucon-2.2.1 → ucon-2.3.0}/ucon/units.py +0 -0
  89. {ucon-2.2.1 → ucon-2.3.0}/ucon.egg-info/SOURCES.txt +0 -0
  90. {ucon-2.2.1 → ucon-2.3.0}/ucon.egg-info/dependency_links.txt +0 -0
  91. {ucon-2.2.1 → ucon-2.3.0}/ucon.egg-info/requires.txt +0 -0
  92. {ucon-2.2.1 → ucon-2.3.0}/ucon.egg-info/top_level.txt +0 -0
  93. {ucon-2.2.1 → ucon-2.3.0}/uv.lock +0 -0
@@ -7,6 +7,419 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [2.3.0] - 2026-10-20
11
+
12
+ ### Added
13
+
14
+ - **Ordering and the reflected operators on `Number` (#353).** `__lt__`,
15
+ `__le__`, `__gt__` and `__ge__` route through one three-way `_compare` and
16
+ agree with `__eq__` (same `1e-12` window), so `sorted`, `min` and `max` now
17
+ work and `units.meter(1) < units.foot(1)` is no longer a `TypeError`. A
18
+ dimension mismatch, a kind join the lattice refuses, and an aspect conflict
19
+ all refuse ordering exactly as `+` refuses them; the chart stratum does not,
20
+ since all three chart classes are monotone, so `3 dB < 10 dB` and
21
+ `20 °C < 25 °C` are well posed. A pair no algebraic factor relates still
22
+ needs `.to()` first — `celsius(20) < kelvin(300)` raises
23
+ `UnitsNotNormalizable`. `__ne__` is now defined rather than inherited. The
24
+ reflected `__rmul__`, `__radd__`, `__rsub__` and `__rtruediv__` each admit
25
+ exactly what their forward form admits, so `2 * units.meter(3)` answers
26
+ `<6 m>` and `2 / units.meter(4)` a reciprocal length, while `2 + a` and
27
+ `2 - a` stay `TypeError`. `__hash__` and `__floordiv__` stay absent — the
28
+ hash waits on `Number` being frozen (#362, sequenced at 3.0.0 by ADR 009).
29
+
30
+ - **`var`, the volt-ampere reactive (#345).** Completes the W/VA/var
31
+ degeneracy cluster: `reactive_power` was declared but unreachable, no unit
32
+ carrying it. `var` declares `default_kind = "reactive_power"`, resolves as
33
+ `var` / `VAr` / `volt_ampere_reactive`, takes SI prefixes (`kvar`), and
34
+ shares the coherent power `base_form` (`m²·kg·s⁻³`) with `watt` and
35
+ `volt_ampere`. All four cross-kind conversions in the cluster now refuse —
36
+ `W → var`, `var → W`, `var → VA`, `VA → var` — while same-kind arithmetic
37
+ and prefix scaling work. No conversion edge is declared: the refusal belongs
38
+ to the kind stratum, as `watt ↔ volt_ampere` already does. `var` is
39
+ unreachable by the `base_form` BFS oracle, so `make base-forms-check` does
40
+ not cover it.
41
+
42
+ - **`PolynomialMap`: calibration curves become expressible, with a
43
+ single-valued inverse (#331).** Real calibrations — Callendar–Van Dusen for
44
+ a platinum RTD, the NIST ITS-90 thermocouple references, a fitted load-cell
45
+ quadratic — are not compositions of the five existing maps.
46
+ `PolynomialMap(coefficients, domain, rel_uncertainty=0.0)` takes
47
+ coefficients in **ascending** order (`coefficients[i]` multiplies `x**i`),
48
+ matching the TOML `coefficients` key; composition with another polynomial or
49
+ with a linear/affine map folds into one `PolynomialMap`. `inverse()` returns
50
+ a `PolynomialInverseMap` — the single branch monotone on the declared
51
+ `domain`, so uncertainty transports as across any other edge. A polynomial
52
+ that turns inside its domain raises the new `NonMonotoneOnDomain` naming the
53
+ turning points rather than choosing a root; narrowing the domain to one side
54
+ restores the branch, and a critical point *on* a boundary is fine (`x²` over
55
+ `[0, 1]` inverts to the square root). Degree 1 inverts to an `AffineMap`;
56
+ degree 0 is not invertible. Both types round-trip through package TOML
57
+ (`type = "polynomial"`, `type = "polynomial_inverse"`) and the binary cache,
58
+ and `_CACHE_SCHEMA` is bumped to 4 — an older cache carries no tag for
59
+ either type. `Unit.chart` is untouched.
60
+
61
+ - **The KOQ floor: degeneracy-cluster units declare their kind (#327).** Where
62
+ the SI gives two units the same dimension to mark a kind distinction, those
63
+ units now carry a `default_kind`: `gray → absorbed_dose`,
64
+ `sievert → dose_equivalent`, `hertz → periodic_frequency`,
65
+ `becquerel → radioactive_activity`, `watt → real_power`,
66
+ `volt_ampere → apparent_power`. One kind is added, `periodic_frequency`.
67
+ With #322's refusing clause, `1 Gy → Sv`, `1 Bq → Hz` and `1 W → VA` refuse
68
+ across a static edge while a dated/contingent table still licenses a
69
+ re-kind. `joule` and `pascal` are left generic — no sibling SI unit
70
+ distinguishes work from heat or pressure from stress, so a Number stays free
71
+ to carry `kinetic_energy` or `mechanical_stress`; the torque/energy and
72
+ pressure/stress must-fails are the model's declared-kind responsibility
73
+ (ucon-tools#62).
74
+
75
+ - **The arrival rule — `.to()` re-kinds at a `default_kind` unit**
76
+ (#305, #322, #327). The second half of `Unit.default_kind`, whose
77
+ declaration shipped in #306; ADR 011 states the rule:
78
+
79
+ > the target's declared kind wins, **unless it is already an ancestor of the
80
+ > current kind**, in which case the finer kind survives — and when the two
81
+ > kinds are **siblings**, only an edge licensed by a contingent context may
82
+ > re-kind; a static edge **refuses**.
83
+
84
+ Narrowing is unlicensed on the same grounds as siblings: both relabel onto a
85
+ claim the value does not imply, so both refuse across a static edge with the
86
+ new `KindArrivalRefused` (exported from `ucon`). So
87
+ `Number(1, gray, kind=absorbed_dose).to(sievert)` refuses, a dated FX table
88
+ still re-kinds `usd → eur`, and conversion *within* a kind keeps the finer
89
+ label — 8 bits of `payload_size` are 1 byte of it. Across *different*
90
+ dimensions the conversion transformed the stuff (`E = h·f`), so the arrival
91
+ kind is adopted with no license, and converting to a unit that declares no
92
+ kind drops a kind that no longer fits the result's dimension. The new
93
+ `Graph.convert_with_license` returns the licensing context's name alongside
94
+ the map; `convert` is unchanged. Resolution is best-effort — an unknown
95
+ declared name leaves the kind untouched. Aspects are unaffected, and
96
+ `NumberArray` has no kind stratum (#297).
97
+
98
+ - **`ConversionContext.contingent` — dated tables no longer chain (#317).** A
99
+ context edge is either *definitional*, licensed by an exact constant, or
100
+ *contingent* — a dated table that could have been otherwise. The rule: a
101
+ path may draw on **at most one** contingent context. Composing a tariff
102
+ (`joule → USD`) with a rate table (`USD → EUR`) previously returned a euro
103
+ energy price nobody quoted; it now raises the new
104
+ `ContingentCompositionRefused`, which names both tables and is distinct from
105
+ `ConversionNotFound` because a declined path and an absent one are different
106
+ facts. `contingent` defaults to `False`, so nothing shipped changes —
107
+ `spectroscopy` and `boltzmann` are exact by SI and keep chaining.
108
+ Composition *within* one contingent context is permitted, which is what
109
+ ADR 011's star topology relies on: `EUR → GBP` resolves through USD from a
110
+ single table at a single date.
111
+
112
+ - **`[[contexts]]` in package TOML — conversion contexts ship as data
113
+ (#282).** `UnitPackage` had no `contexts` field, so a domain package could
114
+ not distribute a context even though graph-level TOML round-tripped one. A
115
+ package now declares `[[contexts]]` with nested `[[contexts.edges]]`, parsed
116
+ into the new `ContextDef` and exposed as `UnitPackage.contexts` —
117
+ array-of-tables with a `name`, matching every other package section rather
118
+ than graph TOML's keyed `[contexts.<name>]`. Context edges reuse `EdgeDef`,
119
+ so the `factor`/`offset` shorthand, explicit `map` specs, and
120
+ constant-licensed factor expressions (`factor = "k_d"`) all work.
121
+ `Graph.with_package` **registers** each context rather than inserting its
122
+ edges — loading the package makes the conversion available, and it applies
123
+ only while `using_context` has it active. Pre-existing limit, unchanged:
124
+ context edges resolve between plain units, not scaled or composite
125
+ endpoints, so `meter → hertz` resolves under a context, `nm → THz` does not.
126
+
127
+ - **`default_kind` on `Unit` — the first unit→kind association (#305).** A
128
+ unit may declare the `Kind` it measures when nothing says otherwise, via
129
+ `Unit(default_kind="...")` or a `default_kind` key on a `[[units]]` entry. A
130
+ `Number` built with no explicit `kind=` takes the declaration; an explicit
131
+ `kind=` always wins. Names resolve against a lattice at load time (local
132
+ before ambient, as `Constant.kind` already does) and are qualified by the
133
+ `namespace` rewriter, so a package may declare both a kind and the units
134
+ that name it; resolution is best-effort, leaving the Number unkinded rather
135
+ than raising on a name the active lattice does not know. Like `scalable`,
136
+ the field is metadata — excluded from `Unit` equality and hashing.
137
+
138
+ ### Changed
139
+
140
+ - **Unit-declared kinds join unkinded operands permissively; explicit kinds
141
+ stay strict (#325).** A kind attached by `Unit.default_kind` is a default,
142
+ not an assertion. Under strict mode a default-kinded operand meeting an
143
+ unkinded one now inherits the default under `+`/`−` and drops it under
144
+ `×`/`÷`, silently — `1 Hz + 1 (1/s)` is one quantity written two ways, and
145
+ `1 Hz × 3 s` is a compound that declares nothing. A kind the caller attached
146
+ explicitly still raises `KindMismatch`. Provenance is derived, not stored: a
147
+ kind is a default iff it equals what the unit's own declaration resolves to.
148
+ Prerequisite for the KOQ floor's declarations — without it, every mixed
149
+ expression `hertz` appears in would have regressed.
150
+
151
+ ### Fixed
152
+
153
+ - **Scalar `*` and `/` are gated on level-vs-gain, and the `base_form`
154
+ invariants are enforced (#340).** `Number.__mul__` and `__truediv__`
155
+ consulted no chart notion when the other operand was a scalar, so every
156
+ logarithmic and interval unit returned a wrong magnitude in silence —
157
+ `Number(10, units.decibel_watt) * 2` answered `<20 dBW>`, which is 100 W
158
+ where twice 10 W is 13.010 dBW. Scalar multiplication is repeated addition,
159
+ so it now answers to the **additive** rules: point + point and level + level
160
+ refuse with the new `ScalarArithmeticRefused`, while gain + gain admits, so
161
+ `2 × (3 dB)` is still the 6 dB cascade and `10 dB / 2` the geometric half.
162
+ The gate covers `a * 2`, `a / 2`, `2 * a` and `2 / a`; `a ** 2` is untouched
163
+ — repeated *multiplication* is a different rule. Nine shipped units refuse:
164
+ `celsius`, `fahrenheit`, `reaumur`, `decibel_watt`, `decibel_milliwatt`,
165
+ `decibel_volt`, `decibel_spl`, `pH` and `nines`, while `decibel`, `bel`,
166
+ `neper` and `rankine` (#339) keep scaling.
167
+
168
+ Two invariants stop being allowlists. `BaseForm.__post_init__` now enforces
169
+ a positive, finite prefactor and a non-empty tuple of `(Unit, exponent)`
170
+ pairs, where `prefactor=-1`, `nan`, `inf`, `0.0` and `factors=()` were all
171
+ accepted before. And `Unit._set_base_form` guarded only "already set", so
172
+ one call could turn `10 dBW + 1 W` into `<11.0 dBW>` with
173
+ `make base-forms-check` green; it is now refused on any unit whose declared
174
+ edges give it no `(prefactor, factors)` representation.
175
+
176
+ Both guards ask one new read-only query, `Graph.scale_class(unit)`,
177
+ returning `"ratio"`, `"gain"`, `"level"` or `"point"` — #356's rule read in
178
+ reverse, over a unit's whole multiplicative neighbourhood (product-edge
179
+ table included) rather than its own edges. A unit the graph declares no
180
+ edges for reads as a ratio scale, as do unanchored ratio scales such as
181
+ `radian` and `percent`. Verdicts are memoized per graph, cleared by
182
+ `add_edge`. Not closed here: `20 °C + 20 °C` still answers `<40 °C>`, since
183
+ `_require_normalizable` exempts same-unit operands.
184
+
185
+ - **Formula-signature collisions are refused at registration (#347).**
186
+ `FormulaRegistry.register` wrote its kind-identity indexes with
187
+ `setdefault`, so two formulas claiming one input signature with *different*
188
+ output kinds were both admitted and the kind the stratum read came down to
189
+ registration order — invisible to lookup, since the loser was erased before
190
+ any tier ran and the ancestor walk's `AmbiguousFormula` never saw it.
191
+ `register` now refuses the pair up front with the new `CollidingFormula`,
192
+ naming both formulas, the contested signature and the two output kinds, and
193
+ leaves the registry unmodified. One rule at the one ingestion site covers
194
+ the EXACT, COMMUTATIVE and GENERALIZED tiers, and so both `*` and `/`. Two
195
+ formulas that *agree* on `output_kind` remain admissible, first writer wins.
196
+ The DIMENSIONAL tier stays unguarded: it discards kind identity by
197
+ construction and is opt-in per call (`dimension_fallback=True`).
198
+
199
+ - **`==` and `!=` consult the aspect stratum (#353).** The aspect peer of the
200
+ kind hole #352 closed: two `Number(1, units.gray)` values carrying *sibling*
201
+ positions under one `Aspect` root compared `True` while `+`, `*` and `/` all
202
+ raised `AspectRefused`. `_resolve_eq_aspects` resolves on the multiplicative
203
+ rule and reports a refusal as *unequal* rather than raising, so `__eq__`
204
+ stays total. Comparison therefore refuses on conflict only, never on silence
205
+ — `gray(1)#dry == gray(1)` is still `True`. Ordering, which carries no
206
+ total-function obligation, raises `AspectRefused` for the pair instead.
207
+
208
+ - **`/` and `==` consult the kind stratum (#352).** `gray(1) / sievert(1)`
209
+ cancelled both kinds and answered a bare `<1.0>`, and
210
+ `gray(1) == sievert(1)` answered `True` — the claim `must-fail-011` exists
211
+ to block, reachable without ever calling `.to()`. `_resolve_truediv_kind`
212
+ consults the `FormulaRegistry` first, so a formula may name the quotient's
213
+ kind, and refuses with `FormulaNotFound` when the lattice refuses the join;
214
+ `_resolve_eq_kind` reports a refusal as *unequal* rather than raising,
215
+ keeping `__eq__` total and `!=` following by inheritance. So `W == VA`,
216
+ `Hz == Bq` and `Gy == Sv` are now `False` and `Gy / Sv` refuses, while
217
+ same-kind quotients, kinded-over-unkinded quotients, and kinds the lattice
218
+ *can* join stay anonymous ratios (`kind=None`). The operator × stratum
219
+ cross-product is now asserted cell-by-cell in
220
+ `tests/ucon/core/test_operator_stratum_grid.py`, so the next ungated
221
+ operator fails CI; the chart column's admissions are recorded as
222
+ expected-for-now, since chart dispatch lands in v3.2.0.
223
+
224
+ - **The `base_form` oracle no longer propagates across an offset, retiring the
225
+ hand-written allowlist.** `scripts/generate_base_forms.py` walked affine
226
+ edges by slope and ignored the offset, so it would mint `base_form = 1·K`
227
+ for `celsius`; a four-name list (`_NULL_BASE_FORM_NAMES`) suppressed that
228
+ after the fact, which is how `rankine` came to be suppressed in error. The
229
+ BFS now refuses to cross an offset-bearing affine edge exactly as it already
230
+ refuses a log/exp edge, so `celsius`/`fahrenheit`/`reaumur` are absent from
231
+ the expected map on their own and the list is empty. It survives as an empty
232
+ name because its *positive* assertion has no replacement: the oracle reaches
233
+ 144 of 234 units, so inferring the null set from absence would reject
234
+ `tesla`, `weber`, `siemens`, `molar` and ~90 others.
235
+
236
+ - **`rankine` carries a `base_form` (#339).** It is a pure scaling of kelvin —
237
+ `0 °R = 0 K`, factor `5/9` — but was named in
238
+ `generate_base_forms._NULL_BASE_FORM_NAMES` beside the three
239
+ conventional-zero scales. Rankine is the absolute Fahrenheit-degree scale;
240
+ only the degree *size* is Fahrenheit's. Removing the name makes
241
+ `make base-forms-check` demand the value the generator's own BFS oracle
242
+ already derives, and the stored prefactor follows the v2.1.6/2.1.7
243
+ convention — compose exactly in `Fraction`, convert to float once — so the
244
+ regression test asserts equality with `float(Fraction(5, 9))` rather than a
245
+ tolerance. Two consequences: `units.rankine(20) + units.kelvin(5)` no longer
246
+ raises `UnitsNotNormalizable`, and `canonical_magnitude` / `to_base()` now
247
+ convert (`100/9 K`) instead of returning the raw quantity.
248
+
249
+ - **`contingent` now has a TOML key, so a packaged dated table arrives dated
250
+ (#329).** `ConversionContext.contingent` (#320) had no serialized
251
+ representation, so a context shipped in a package always loaded as
252
+ **definitional** and the composition guard never fired on it: a package
253
+ declaring a hub tariff (`joule → USD`) and euro reference rates
254
+ (`USD → EUR`), both `contingent = true`, resolved `1 GJ → EUR` silently. The
255
+ flag now survives `ContextDef` and `[[contexts]]` parsing,
256
+ `ContextDef.materialize`, `from_toml`, `to_toml` and the binary cache, and
257
+ `_CACHE_SCHEMA` is bumped to 3 — a stale cache missing the key would restore
258
+ `False` and reintroduce the defect. The default is unchanged: a context is
259
+ definitional unless it says otherwise.
260
+
261
+ ### Documentation
262
+
263
+ - **`[Unreleased]` consolidated; the v2.3.0 roadmap row reads `Complete`.**
264
+ Nine interleaved section headers reduce to one each; #352 (#360) and #347
265
+ (#363) are marked shipped, and `__hash__` is stated as not in this release.
266
+
267
+ - **`ROADMAP.md` recast around the UnitSafe gate and re-scoped; ADR 013
268
+ proposed.** The roadmap is now ordered by what the UnitSafe benchmark
269
+ exercises rather than by principle, with a *The UnitSafe gate* section
270
+ recording what the benchmark does and does not reach here, and a *Where the
271
+ chart defects land* table replacing "angle becomes a real dimension" — angle
272
+ stays a quantity of dimension one, with `plane_angle` and `solid_angle` as
273
+ kinds. Thirteen issues surfaced working the chart stratum and the KOQ floor
274
+ (#339–#348, #352–#354) reduce to four root causes, the largest being the
275
+ pseudo-dimension tags; eight open issues are its consequences (#307, #318,
276
+ #321, #336, #341, #344, #346, #348).
277
+ [ADR 013](docs/internal/decisions/013-the-vector-is-the-only-carrier.md)
278
+ (*The vector is the only carrier*, Proposed) supplies the retirement v3.0.0
279
+ had named without content — dimensional identity in the basis vector, tags
280
+ absorbed or dissolved rather than deleted to `none`, currency a basis
281
+ component, `count` and the angle family as kinds on unity, linear ratios as
282
+ `Scale`, kinds composing through a normal form. It supersedes ADRs 005, 011
283
+ and 012, each cross-referenced, and the intended `%` API is specified by
284
+ example in
285
+ [proposals/percent-on-unity](docs/internal/proposals/percent-on-unity.md).
286
+
287
+ Where the releases now sit. **v2.3.0** is *stratum wiring and invariant
288
+ enforcement* — the three routes by which the kind stratum could be bypassed
289
+ (#340, #352, #353) and the invariants that were allowlists (#340, #347) —
290
+ with `rankine` (#339) and `var` (#345) landed against it. **v2.3.1** is
291
+ *Unity and the dimensionless fold* (#307, #318). The deprecation ladder,
292
+ 3.0.0's only true prerequisite, moves forward to v2.4.0/v2.5.0. The KOQ
293
+ catalog floor **splits**: the angle clusters and the product-signature
294
+ `default_kind` mechanism become v2.4.0 (#342, #343, #344's angle half,
295
+ #348's kind half), and the half that needs the merged fiber becomes v3.1.0
296
+ (#341, #346, the remaining dimensionless kinds, `sr = rad²`). The Turnstile
297
+ moves to v3.2.0. Array parity (#297, #298) is the one row found *not* to be
298
+ a prerequisite and is left unsequenced; **#292 currency is** one — no
299
+ `currency` dimension or unit exists today and the SI basis still carries
300
+ `information` in slot 8 — as is part of the KOQ floor, since `xdom-018`,
301
+ `xdom-020` and `pr-028` refuse today *only* because the tags differ.
302
+
303
+ - **`Unit.chart` withdrawn: the catalog already declares the chart class**
304
+ (#336, with #339, #340 and #341 filed alongside). The proposal under
305
+ [`proposals/declared-unit-chart`](docs/internal/proposals/declared-unit-chart.md)
306
+ is withdrawn and **no field ships** — no TOML key, no `to_toml` emission, no
307
+ `_CACHE_SCHEMA` bump, no dataclass field, no hand-written declarations. The
308
+ class is derivable from the declared edge vocabulary: a unit's numerals are
309
+ a logarithm iff it is the source of an `exp` edge or the target of a `log`
310
+ edge, and origin classes are the components under pure-scaling edges; add
311
+ one physical fact — thermodynamic temperature has an absolute zero, realised
312
+ by `kelvin` — and the census of all 234 units falls out as **222 ratio / 3
313
+ interval / 9 logarithmic** with zero disagreements. The proposed fourth
314
+ `transformed` class is **declined**: addition on the `nines` chart has
315
+ exactly one meaning, the parallel-redundancy law, so `nines` is
316
+ `logarithmic`, and `PolynomialMap` is a cross-dimensional edge rather than a
317
+ numeral scheme. `logarithmic` needs no parameters either — `reference` is
318
+ already a populated field on `LogMap`/`ExpMap`, and the field-vs-power
319
+ distinction is already carried by `scale`.
320
+
321
+ [ADR 010](docs/internal/decisions/010-chart-nomenclature.md) and
322
+ [ADR 009](docs/internal/decisions/009-turnstile.md) §4 are **amended in
323
+ place** per the house convention: ADR 010's naming Decision stands, but the
324
+ one Consequences bullet forbidding the class to be read from a `Map`'s
325
+ algebraic form is withdrawn (both original bans — never from `base_form`,
326
+ never from an arbitrary sibling edge — stand), its Context claim that v2.2.0
327
+ shipped a declared field is marked counterfactual, and 009 §4's two `[live]`
328
+ cases are withdrawn as failing on re-test. **The 2.2.2 re-key reverses**:
329
+ the 62 same-fiber pairs over 34 units it would have unblocked are *correct*
330
+ refusals with a misleading message, since `base_form` is load-bearing for
331
+ the arithmetic and not only for the meaningfulness check — admitting
332
+ `50 % + 1 fraction` would yield `51 %` where the answer is `150 %`. Those
333
+ pairs are unblocked by #283, ADR 013's retirement and #339, not by relaxing
334
+ the gate. `ROADMAP.md` is brought into line.
335
+
336
+ - **ADR 012 — what "dimensionless" means.** The v3.0.0 pseudo-dimension
337
+ retirement is named in the roadmap as "degree et al. become first-class", a
338
+ phrase that admits two readings with opposite consequences. ADR 012 records
339
+ the decision required — *does a named dimensionless unit remain a
340
+ distinguishable symbol in the unit algebra, or is it unity?* — with both
341
+ options costed, plus a third that resolves per family, since `radian²` has a
342
+ correct target (steradian) while `count²` has none. Proposed, not accepted.
343
+ Three open issues are symptoms of the same gap: `Dimension(none)` factors
344
+ are dropped from `UnitProduct` at construction while pseudo-dimensions
345
+ survive (#318), `parse_unit("1")` yields `ratio` where a formula wants
346
+ `none` (#307), and pseudo-dimensional units cannot normalize so comparison
347
+ refuses across them (#313). The ADR separates three families that
348
+ "dimensionless" bundles — exact-factor (`percent`, `degree`, `steradian`),
349
+ no-relation (owned by `⊤_d` at the kind stratum) and non-multiplicative
350
+ (`decibel`, owned by the chart stratum) — of which today's
351
+ `Dimension(ratio)` holds the first and third at once. It also records a
352
+ sequencing hazard: `Dimension(count)` ships seven units and no count kinds,
353
+ so giving them a canonical scale before populating that lattice would turn
354
+ today's refusal of `flop/s + Hz` into a silent admission. Money is assessed
355
+ as `Dimension(count)`, which currency will ship on **without a compatibility
356
+ claim across v3.0.0**; ADR 011 gains a pointer, since it chose
357
+ "dimensionless" for currency before the factor-dropping behaviour was known
358
+ — the first thing #292 must settle.
359
+
360
+ ## [2.2.2] - 2026-09-18
361
+
362
+ ### Fixed
363
+
364
+ - **Comparison and additive arithmetic refuse units they cannot normalize
365
+ instead of ignoring them.** (#313) `_canonical_magnitude` falls back to
366
+ the raw quantity when a unit has no `base_form`, so `__eq__`, `__add__`
367
+ and `__sub__` treated `1` of such a unit as `1` of every other unit in
368
+ its dimension. Three families were affected, wrong in both directions:
369
+
370
+ | expression | before | now |
371
+ |---|---|---|
372
+ | `Number(1, kelvin) == Number(1, celsius)` | `True` | refuses |
373
+ | `Number(0, celsius) == Number(273.15, kelvin)` | `False` | refuses |
374
+ | `Number(180, degree) - Number(pi, radian)` | `176.86 deg` | refuses |
375
+ | `Number(20, decibel) == Number(1, neper)` | `False` | refuses |
376
+
377
+ A new `UnitsNotNormalizable` names both units, the operation, and the
378
+ conversion that resolves it. The relationships exist in the
379
+ `ConversionGraph` — `Number(0, celsius).to(kelvin)` has always returned
380
+ `273.15 K` — but these paths are pure functions of `(quantity, unit)`
381
+ and deliberately consult no graph, so the honest answer is a refusal
382
+ rather than a number. Converting first succeeds as before.
383
+
384
+ Same-unit operands are untouched: `0 °C == 0 °C` and
385
+ `90 deg - 90 deg` behave exactly as they did. Cross-dimension
386
+ comparison still returns `False` rather than raising. A `UnitProduct`
387
+ is refused when any single factor is unnormalizable.
388
+
389
+ This supersedes the behavior 2.2.1 documented, where affine operands
390
+ combined unscaled on the grounds that arithmetic then agreed with
391
+ `__eq__`. They did agree, and both were wrong.
392
+
393
+ Angle units are *not* given a `base_form` to fix their third of this:
394
+ `BaseForm.factors` is contracted to reference only canonical SI base
395
+ units, and angle is a pseudo-dimension with no SI base expansion, so a
396
+ radian-based factorization would violate the type's invariant. Making
397
+ angle, ratio, and count comparable on their own terms needs a separate
398
+ within-dimension canonical scale, which is design work rather than a
399
+ point release.
400
+
401
+ ### Documentation
402
+
403
+ - **Roadmap recast around the chart defects.** `ROADMAP.md` marked v2.2.0
404
+ planned after it had shipped, and had no home for the correctness work
405
+ that followed. It now records a **v2.2.x scale correctness train**
406
+ (symmetrical with v2.1.x), moves currency to its own v2.4.0 ahead of
407
+ array parity at v2.5.0, and adds a *Where the chart defects land*
408
+ section.
409
+
410
+ That section exists because #309 and #313 are not standalone bugs: ADR
411
+ 009 predicted both, and the Turnstile evidence record (internal) documents
412
+ `1 rad + 180 deg → <181 rad>` as a shipped defect before it was
413
+ reported from outside. The v2.2.x refusals are a waypoint — 3.1.0's
414
+ chart stratum is meant to *compute* some of what 2.2.2 refuses — and
415
+ the table says which release does which so the interim is not mistaken
416
+ for the destination.
417
+
418
+ Also notes that #282 is the last open Turnstile prerequisite, putting
419
+ v2.3.0 on the critical path for v3.1.0, and that
420
+ the internal release-plan trajectory table is superseded from
421
+ 2.2.0 onward.
422
+
10
423
  ## [2.2.1] - 2026-09-18
11
424
 
12
425
  ### Changed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ucon
3
- Version: 2.2.1
3
+ Version: 2.3.0
4
4
  Summary: A tool for dimensional analysis: a 'Unit CONverter'
5
5
  Author-email: "Emmanuel I. Obi" <withtwoemms@gmail.com>
6
6
  Maintainer-email: "Emmanuel I. Obi" <withtwoemms@gmail.com>