ucon 2.2.2__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 (91) hide show
  1. {ucon-2.2.2 → ucon-2.3.0}/CHANGELOG.md +350 -0
  2. {ucon-2.2.2/ucon.egg-info → ucon-2.3.0}/PKG-INFO +1 -1
  3. {ucon-2.2.2 → ucon-2.3.0}/ROADMAP.md +93 -19
  4. {ucon-2.2.2 → ucon-2.3.0}/ucon/__init__.py +6 -0
  5. {ucon-2.2.2 → ucon-2.3.0}/ucon/_cache.py +27 -1
  6. {ucon-2.2.2 → ucon-2.3.0}/ucon/comprehensive.ucon.toml +34 -0
  7. {ucon-2.2.2 → ucon-2.3.0}/ucon/contexts.py +31 -2
  8. {ucon-2.2.2 → ucon-2.3.0}/ucon/conversion.py +325 -38
  9. {ucon-2.2.2 → ucon-2.3.0}/ucon/core/__init__.py +6 -0
  10. {ucon-2.2.2 → ucon-2.3.0}/ucon/core/_types.py +734 -13
  11. {ucon-2.2.2 → ucon-2.3.0}/ucon/core/exceptions.py +150 -0
  12. {ucon-2.2.2 → ucon-2.3.0}/ucon/formulas/__init__.py +2 -0
  13. {ucon-2.2.2 → ucon-2.3.0}/ucon/formulas/exceptions.py +44 -1
  14. {ucon-2.2.2 → ucon-2.3.0}/ucon/formulas/registry.py +83 -10
  15. ucon-2.3.0/ucon/maps.py +1060 -0
  16. {ucon-2.2.2 → ucon-2.3.0}/ucon/packages.py +158 -4
  17. {ucon-2.2.2 → ucon-2.3.0}/ucon/parsing/namespaces.py +4 -0
  18. {ucon-2.2.2 → ucon-2.3.0}/ucon/serialization.py +34 -9
  19. {ucon-2.2.2 → ucon-2.3.0}/ucon/units.pyi +1 -0
  20. {ucon-2.2.2 → ucon-2.3.0/ucon.egg-info}/PKG-INFO +1 -1
  21. {ucon-2.2.2 → 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.2/ucon/maps.py +0 -561
  24. ucon-2.2.2/ucon.egg-info/scm_version.json +0 -8
  25. {ucon-2.2.2 → ucon-2.3.0}/.github/workflows/downstream.yaml +0 -0
  26. {ucon-2.2.2 → ucon-2.3.0}/.github/workflows/publish.yaml +0 -0
  27. {ucon-2.2.2 → ucon-2.3.0}/.github/workflows/tests.yaml +0 -0
  28. {ucon-2.2.2 → ucon-2.3.0}/.gitignore +0 -0
  29. {ucon-2.2.2 → ucon-2.3.0}/.gitmodules +0 -0
  30. {ucon-2.2.2 → ucon-2.3.0}/LICENSE +0 -0
  31. {ucon-2.2.2 → ucon-2.3.0}/MANIFEST.in +0 -0
  32. {ucon-2.2.2 → ucon-2.3.0}/Makefile +0 -0
  33. {ucon-2.2.2 → ucon-2.3.0}/NOTICE +0 -0
  34. {ucon-2.2.2 → ucon-2.3.0}/README.md +0 -0
  35. {ucon-2.2.2 → ucon-2.3.0}/SECURITY.md +0 -0
  36. {ucon-2.2.2 → ucon-2.3.0}/SUPPORT.md +0 -0
  37. {ucon-2.2.2 → ucon-2.3.0}/mkdocs.yml +0 -0
  38. {ucon-2.2.2 → ucon-2.3.0}/netlify.toml +0 -0
  39. {ucon-2.2.2 → ucon-2.3.0}/pyproject.toml +0 -0
  40. {ucon-2.2.2 → ucon-2.3.0}/requirements.txt +0 -0
  41. {ucon-2.2.2 → ucon-2.3.0}/setup.cfg +0 -0
  42. {ucon-2.2.2 → ucon-2.3.0}/ucon/_active.py +0 -0
  43. {ucon-2.2.2 → ucon-2.3.0}/ucon/_algebra_cache.py +0 -0
  44. {ucon-2.2.2 → ucon-2.3.0}/ucon/_bootstrap.py +0 -0
  45. {ucon-2.2.2 → ucon-2.3.0}/ucon/aspects/__init__.py +0 -0
  46. {ucon-2.2.2 → ucon-2.3.0}/ucon/aspects/exceptions.py +0 -0
  47. {ucon-2.2.2 → ucon-2.3.0}/ucon/aspects/forest.py +0 -0
  48. {ucon-2.2.2 → ucon-2.3.0}/ucon/aspects/resolution.py +0 -0
  49. {ucon-2.2.2 → ucon-2.3.0}/ucon/aspects/types.py +0 -0
  50. {ucon-2.2.2 → ucon-2.3.0}/ucon/basis/__init__.py +0 -0
  51. {ucon-2.2.2 → ucon-2.3.0}/ucon/basis/builtin.py +0 -0
  52. {ucon-2.2.2 → ucon-2.3.0}/ucon/basis/graph.py +0 -0
  53. {ucon-2.2.2 → ucon-2.3.0}/ucon/basis/ops.py +0 -0
  54. {ucon-2.2.2 → ucon-2.3.0}/ucon/basis/transforms.py +0 -0
  55. {ucon-2.2.2 → ucon-2.3.0}/ucon/basis/types.py +0 -0
  56. {ucon-2.2.2 → ucon-2.3.0}/ucon/basis/vector.py +0 -0
  57. {ucon-2.2.2 → ucon-2.3.0}/ucon/checking.py +0 -0
  58. {ucon-2.2.2 → ucon-2.3.0}/ucon/constants.py +0 -0
  59. {ucon-2.2.2 → ucon-2.3.0}/ucon/constants.pyi +0 -0
  60. {ucon-2.2.2 → ucon-2.3.0}/ucon/core/_parsing_graph.py +0 -0
  61. {ucon-2.2.2 → ucon-2.3.0}/ucon/dimension.py +0 -0
  62. {ucon-2.2.2 → ucon-2.3.0}/ucon/dimension.pyi +0 -0
  63. {ucon-2.2.2 → ucon-2.3.0}/ucon/expressions.py +0 -0
  64. {ucon-2.2.2 → ucon-2.3.0}/ucon/formulas/types.py +0 -0
  65. {ucon-2.2.2 → ucon-2.3.0}/ucon/graph.py +0 -0
  66. {ucon-2.2.2 → ucon-2.3.0}/ucon/integrations/__init__.py +0 -0
  67. {ucon-2.2.2 → ucon-2.3.0}/ucon/integrations/numpy.py +0 -0
  68. {ucon-2.2.2 → ucon-2.3.0}/ucon/integrations/pandas.py +0 -0
  69. {ucon-2.2.2 → ucon-2.3.0}/ucon/integrations/polars.py +0 -0
  70. {ucon-2.2.2 → ucon-2.3.0}/ucon/integrations/pydantic.py +0 -0
  71. {ucon-2.2.2 → ucon-2.3.0}/ucon/kinds/__init__.py +0 -0
  72. {ucon-2.2.2 → ucon-2.3.0}/ucon/kinds/exceptions.py +0 -0
  73. {ucon-2.2.2 → ucon-2.3.0}/ucon/kinds/lattice.py +0 -0
  74. {ucon-2.2.2 → ucon-2.3.0}/ucon/kinds/types.py +0 -0
  75. {ucon-2.2.2 → ucon-2.3.0}/ucon/parsing/__init__.py +0 -0
  76. {ucon-2.2.2 → ucon-2.3.0}/ucon/parsing/aspects.py +0 -0
  77. {ucon-2.2.2 → ucon-2.3.0}/ucon/parsing/dimensions.py +0 -0
  78. {ucon-2.2.2 → ucon-2.3.0}/ucon/parsing/formulas.py +0 -0
  79. {ucon-2.2.2 → ucon-2.3.0}/ucon/parsing/kinds.py +0 -0
  80. {ucon-2.2.2 → ucon-2.3.0}/ucon/parsing/lexer.py +0 -0
  81. {ucon-2.2.2 → ucon-2.3.0}/ucon/parsing/quantity.py +0 -0
  82. {ucon-2.2.2 → ucon-2.3.0}/ucon/parsing/units.py +0 -0
  83. {ucon-2.2.2 → ucon-2.3.0}/ucon/quantity.py +0 -0
  84. {ucon-2.2.2 → ucon-2.3.0}/ucon/resolver.py +0 -0
  85. {ucon-2.2.2 → ucon-2.3.0}/ucon/system/__init__.py +0 -0
  86. {ucon-2.2.2 → ucon-2.3.0}/ucon/units.py +0 -0
  87. {ucon-2.2.2 → ucon-2.3.0}/ucon.egg-info/SOURCES.txt +0 -0
  88. {ucon-2.2.2 → ucon-2.3.0}/ucon.egg-info/dependency_links.txt +0 -0
  89. {ucon-2.2.2 → ucon-2.3.0}/ucon.egg-info/requires.txt +0 -0
  90. {ucon-2.2.2 → ucon-2.3.0}/ucon.egg-info/top_level.txt +0 -0
  91. {ucon-2.2.2 → ucon-2.3.0}/uv.lock +0 -0
@@ -7,6 +7,356 @@ 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
+
10
360
  ## [2.2.2] - 2026-09-18
11
361
 
12
362
  ### Fixed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ucon
3
- Version: 2.2.2
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>
@@ -45,12 +45,17 @@ This roadmap tracks **major milestones** on the path to v2. For incremental upda
45
45
  | **v2.0.0** | **`UnitSystem` algebra, global retirement, and `Number.kind` wiring.** Closes the value-type loop: pure-function operations `extend` / `restrict` / `merge` / `with_*`, first-class relations `subsystem_of` / `compatible_with` / `diff` / `shared_units` / `shared_dimensions`, explicit cross-system value movement (`system.adopt`, `Bridge(A, B)` with `rename` + `basis_transform`), and retirement of the module-global registries (`_REGISTRY`, `_DIMENSION_ATTRS`, default `ConversionGraph`) in favour of the default `UnitSystem` value. Promotes the v1.9.x KOQ surface to first-class: `Number` accepts `kind=`, arithmetic dispatches through the active `FormulaRegistry`, and the `ActiveContext` substrate (single ContextVar payload bundling `system + formulas + kinds + strict`, extended `use(...)` with field-wise inheritance) makes scope explicit. `strict=True` by default raises `UnitDefinitionMismatch` on identity-mismatched source units. Removes the deprecated `UnitSystem` alias for `BaseUnits` and the `_DIM_*_CACHE` shims. Marshal-based graph cache (~15-25x import speedup). | Complete |
46
46
  | v2.1.x | **Correctness train** — six per-issue patch releases (2.1.2–2.1.7) closing the 2026-09 audit: exact customary prefactors derived from statutory seeds, constant symbols in package edge factors, path resolution through composite edge endpoints, typed `DisjointKinds` refusals, idempotent kind re-add, exact SI `base_form`s for mechanical CGS units. Per-issue detail in [`CHANGELOG.md`](CHANGELOG.md). | Complete |
47
47
  | **v2.2.0** | **Aspect stratum** — per [decisions/008](docs/internal/decisions/008-aspect-stratum.md): one `Aspect` type (peer of `Kind`), flat additive `Number.aspects`, family-wise resolution, carry rule, D3 namespacing; the never-exported flat `AspectSet` model is removed outright; pseudo-dimension deprecations begin (`PendingDeprecationWarning`). | Complete |
48
- | v2.2.x | **Scale correctness train** — a second per-issue patch train, unplanned but symmetrical with v2.1.x, closing the ψ (scale) defects [ADR 009](docs/internal/decisions/009-turnstile.md) predicted: additive operands converted before combining (2.2.1, #309), unnormalizable pairs refused rather than combined unscaled (2.2.2, #313), plus catalog papercuts (#307, #308). Interim by construction — see *Where the chart defects land*. | In progress |
49
- | v2.3.0 | **Package infrastructure** — `[[contexts]]` in TOML (#282), `PolynomialMap` with branch inverses, declared `Unit.chart` ([decisions/010](docs/internal/decisions/010-chart-nomenclature.md)), `default_kind` (#305). Carries the last open Turnstile prerequisite and unblocks currency. | Planned |
50
- | v2.4.0 | **Native currency** — currency as kinds plus rate contexts (#292), consuming 2.3.0's `[[contexts]]` and `default_kind`. The first real consumer of `default_kind`, which is why #306 lands with this rather than ahead of it. | Planned |
51
- | v2.5.0 | **Array stratum parity** — `NumberArray` receives the kind and aspect strata (#297, #298): array-level `kind` and `aspects` fields mirroring the shared-`unit` design, scalar-resolver reuse (one resolution per array op), extraction stamping so `arr[i]` satisfies every `Number` invariant, integrations round-trip. | Planned |
52
- | v3.0.0 | **Lean structural major** — pseudo-dimension retirement (TOML schema), `Number` frozen, `Unit`/`UnitProduct` identity unification, deprecation removals. The breaks, and only the breaks. | Planned |
53
- | v3.1.0 | **The Turnstile** — per [decisions/009](docs/internal/decisions/009-turnstile.md): four-stratum arithmetic dispatch (dimension, chart, kind, aspect), derived point/displacement, cyclic/ordinal kind flags, lazy warrants via `explain()`. New refusals on previously-wrong paths are fixes. | Planned |
48
+ | v2.2.x | **Scale correctness train** — a second per-issue patch train, symmetrical with v2.1.x, closing the ψ (scale) defects [ADR 009](docs/internal/decisions/009-turnstile.md) predicted: additive operands converted before combining (2.2.1, #309), unnormalizable pairs refused rather than combined unscaled (2.2.2, #313). Interim by construction — see *Where the chart defects land*. | Complete |
49
+ | v2.3.0 | **Stratum wiring and invariant enforcement** — the three routes by which the kind stratum can be bypassed, closed; the invariants that were allowlists, enforced. Shipped: `[[contexts]]` (#316 ✓), `default_kind` (#306 ✓), `contingent` + its TOML key (#320 ✓), the arrival rule **with its refusing clause** (#322 ✓), unit-declared kinds join `None` permissively (#326 ✓), `PolynomialMap` with domain-restricted branch inverses (#332 ✓), six degeneracy-cluster `default_kind`s (#328 ✓), `rankine`'s `base_form` (#339 ✓), `var` completing the W/VA/var cluster (#345 ✓), the comparison protocol's deliverable half — ordering, explicit `__ne__`, the reflected operators, and `==` consulting the aspect stratum (#353 ✓, partial), scalar `*`/`/` gated on level-vs-gain, `BaseForm` validated to its own documented invariants, and `_set_base_form` guarded so the 2.2.2 proxy is sound by construction rather than by a four-name list (#340 ✓). `==` and `/` consult the kind stratum, so `gray(1) == sievert(1)` stops answering `True` and `Gy / Sv` stops cancelling to `1.0` where `.to()` and `+` refuse (#352 ✓), formula collisions refused at registration, one rule covering `*` and `/` together (#347 ✓). **Not in this release:** `__hash__`, the remaining half of #353 — blocked rather than deferred, since `Number` is a mutable dataclass and the hash waits on freezing it (#362, 3.0.0). **Re-scoped 2026-10-18:** the declared `Unit.chart` field is withdrawn ([decisions/010 §Amendment](docs/internal/decisions/010-chart-nomenclature.md#amendment-2026-10-18)) and the *catalog* half of the KOQ floor splits across v2.4.0 and v3.1.0 by whether it needs the dimensionless fiber before or after 3.0.0 reshapes it. Everything retained here is independent of that fiber. *UnitSafe: low directly; it closes the bypass routes the floor's refusals rely on.* | Complete |
50
+ | v2.3.1 | **Unity and the dimensionless fold** — canonical `one` resolving from `"1"` (#307); `UnitProduct` keeps named dimension-one factors and folds only an anonymous scaled unity into the magnitude at the `Number` boundary (#318: today `10 kg × 50 (centi·1)` answers 5 kg, 500 kg, or 500 000 g depending on the accessor); `canonical_scale` enters `UnitProduct` identity; exact `Exponent` arithmetic in `Scale` (`centi × centi` is 10⁻⁴, not `milli`); `Fraction` exponents; division dispatches kinds through its own table, not multiplication's (`Gy / w_R` is not a dose equivalent); `**` never yields an unkinded result. **Not** the `%`/`ppm` parser flip — that rides v3.0.0 with the unit retirement; the intended `%` API is specified by example in [proposals/percent-on-unity](docs/internal/proposals/percent-on-unity.md). Ships with ucon-tools switching its `compute` placeholder from `ea` to `one`. *UnitSafe: high — the `ea` residue sits on every multiply step.* | Planned |
51
+ | v2.4.0 | **The pre-retirement KOQ floor** — the clusters 3.0.0 *regresses without*. `xdom-018` (`rad → sr`), `xdom-020` (`rad/s → Hz`) and `pr-028` (`W/m² → W/sr`) refuse today **only because the pseudo-dimension tags differ**; the retirement removes the tags, so `plane_angle`, `solid_angle` and `angular_velocity` must be declared kinds first, and `radian`/`steradian` must carry them (#344, #348). `rad/s` and `W/sr` are `UnitProduct`s, so this needs `default_kind` on product-unit **signatures** — the same mechanism the torque/energy and pressure clusters require, carrying the fiber's **generic** kind so linear work passes and moments refuse (#342, #343 — 14 further must-fails, the largest single lever). Plus the first rung of the v3 deprecation ladder (`PendingDeprecationWarning`). *UnitSafe: high — and it is the difference between the retirement holding the line and dropping three must-fails.* | Planned |
52
+ | v2.5.0 | **Deprecation rung two and `Scale` members** — `DeprecationWarning` on the linear-ratio units (→ `Scale` on unity), the logarithmic ratio units (→ the logarithmic chart), `fraction`, and the pseudo-dimension tags; mechanism is `Number.__post_init__` plus module `__getattr__` (precedent: `constants.py`). `Scale` gains 10⁻⁴ (`‱`) and `atto`; rendering table for scales on unity. *UnitSafe: low — two problems answer `%`/`ppm`.* | Planned |
53
+ | v2.6.0 | **Native currency as a basis component** (#292) — **a 3.0.0 prerequisite, not a feature queued in front of it:** no `currency` dimension or unit exists today and the SI basis still carries `information` in slot 8, so 3.0.0's "`currency` folds into slot 9 … and the shim transform retires" has nothing to fold until this lands. `[bases.SI-currency]` with both embedding transforms, `resolve()` returning canonical `NONE` for any zero vector, #323 (a loaded package's basis graph reaches dimension arithmetic; `extend` included; append-only embeddings registered ambiently), self-referential `base_form` on currency units and the denomination signature check at the chart stratum (so cents work *and* `USD/MWh + EUR/MWh` still refuses), `ContingentCollision`, star-topology validation, a loadable `fx` package, acceptance re-measured with the lattice active. Supersedes the kinds-plus-contexts route; this **is** the v3 design, only the encoding folds at v3.0.0. *UnitSafe: none — zero currency problems; may slip without touching the gate.* | Planned |
54
+ | v2.7.0 | **Last 2.x minor** — `DeprecationWarning` for anything that entered the ladder at v2.5.0; nothing new. | Planned |
55
+ | v3.0.0 | **Lean structural major** — the pseudo-dimension retirement per [decisions/013](docs/internal/decisions/013-the-vector-is-the-only-carrier.md): tags absorbed or dissolved, never deleted to `none`; `currency` folds into slot 9 of the renamed system basis (it has not been SI since `information`) and the shim transform retires; `ratio` empties into `Scale`; `count` is a kind on unity; `angle`/`solid_angle` are kinds on unity. The `%`/`ppm`/`bp` parser flip lands here with the unit retirement ([proposals/percent-on-unity](docs/internal/proposals/percent-on-unity.md)). `from_toml` upgrades 8-component packages in place; migration script; `FORMAT_VERSION` 2.0. The 2.2.2 normalizability check is **kept** until v3.1.0. **Gated on v2.3.0's refusing clause and angle/frequency `default_kind`s** — without them `xdom-020` and the `angle/solid_angle` must-fail, which refuse today only by the tag, regress. Plus `Number` frozen, `Unit`/`UnitProduct` identity unification, deprecation removals. | Planned |
56
+ | v3.1.0 | **The post-retirement KOQ floor** — the half that needs the merged fiber and could not be done sooner. `lumen.base_form = cd·sr`, unwritable while `steradian` is pseudo-dimensional because `BaseForm.factors` may reference only canonical base units and the BFS oracle skips pseudo-dimensional units (#346); the two log edges that target a quantity other than the one they chart — `nines` hiding `x ↦ 1 − x`, and `pH` as a level on `Dimension(concentration)` where ISO 80000-9 item 9-37 makes it dimension one (#341); the ten dimensionless kinds beyond the angle set, now that `Dimension(none)` and `Dimension(ratio)` are one fiber rather than two (#344); `sr = rad²` made representable, which needs both the tags gone and composing kinds (#348). *UnitSafe: moderate — catalog correctness more than score.* | Planned |
57
+ | v3.2.0 | **The Turnstile and the kind algebra** — per [decisions/009](docs/internal/decisions/009-turnstile.md): four-stratum arithmetic dispatch, derived point/displacement, cyclic/ordinal kind flags, lazy warrants via `explain()`. Plus [decisions/013](docs/internal/decisions/013-the-vector-is-the-only-carrier.md) §4: kinds compose — a normal-form `DerivedKind` (formula outputs expanded to their inputs; equality of normal forms; shortest registered name for display), anonymous factors for unkinded operands, cancellation to registered kinds, a `**` dispatch row, ⊤_d as the anonymous kind of its fiber; load-time confluence validation. Logarithmic-chart dispatch (`dBm + dB` admits, `dBm + dBm` refuses). Retires the normalizability check — which requires the arithmetic to route through the conversion graph, since `_canonical_magnitude` is contracted not to; dropping the check alone would corrupt magnitudes rather than free them. *UnitSafe: none as harnessed — `compute` does not run ucon arithmetic.* | Planned |
58
+ | *unsequenced* | **Array parity and quantity ergonomics** — `NumberArray` receives the kind and aspect strata (#297, #298) and routes `sum`/`mean`/`std` through them (barycenter mean on interval charts; `sum` of points refuses); `kelvin` declared as `celsius`'s displacement unit so `20 °C + 5 K → 25 °C`; `Number.__neg__`, `__abs__`, `__round__`/`quantize`, `Decimal` operands; opt-in `as_of` provenance aspect stamped by contingent contexts. The **only** row checked against 3.0.0 and found not to be a prerequisite: the benchmark's `compute` is a float path, so the array strata are unexercised either way. Left unsequenced rather than renumbered — where it lands is a product call. *UnitSafe: low.* | Unsequenced |
54
59
 
55
60
  ---
56
61
 
@@ -62,27 +67,96 @@ was reported from outside, recording the shipped behavior as
62
67
  `1 rad + 180 deg → <181 rad>` and `1 Gy + 1 Sv → <2 Gy>`.
63
68
 
64
69
  The Turnstile is the fix, and it rides after the 3.0.0 breaks. That is several
65
- releases out, so the v2.2.x train converts silence into either a correct answer
70
+ releases out, so the v2.2.x train converted silence into either a correct answer
66
71
  or a loud refusal in the meantime. **The interim work is a waypoint, not the
67
- destination** — some of what 2.2.2 refuses, 3.1.0 is meant to compute:
72
+ destination** — some of what 2.2.2 refuses, 3.2.0 is meant to compute. Earlier
73
+ drafts of this table also described some of its refusals as *accidental*, to be
74
+ removed by re-keying the check. That is withdrawn: the refusals are correct and
75
+ the message is what misleads, so they are cleared by supplying the missing
76
+ `base_form`s, not by relaxing the gate. The two rows below record it.
68
77
 
69
78
  | Step | Release | What changes |
70
79
  |---|---|---|
71
80
  | Ratio-chart operands converted before combining | 2.2.1 | `1 V - 1000 mV` returns `0 V`, not `-999 V` (#309) |
72
81
  | Unnormalizable pairs refused, not combined unscaled | 2.2.2 | `1 K == 1 °C` raises instead of reporting `True` (#313) |
73
- | Refusal keys on a principled marker | 2.3.0 | the `base_form is None` proxy gives way to declared `Unit.chart`; `base_form` is a statement about SI factorization, not about chart class |
74
- | Angle becomes a real dimension | 3.0.0 | pseudo-dimension retirement; `degree` and `radian` gain a canonical scale they cannot have while angle is pseudo-dimensional |
75
- | Chart-crossing arithmetic returns a value | 3.1.0 | the chart stratum supplies factors and offsets, so `1 rad + 180 deg` converts rather than refusing |
82
+ | Same-dimension KOQ pairs refuse in `.to()` | 2.3.0 → 2.4.0 → 3.1.0 | `1 Gy[absorbed_dose] → Sv` **refuses** instead of relabeling to `dose_equivalent`; likewise `N·m → J`, `W → VA`, `Bq → Hz`, `Pa → J/m³`, `rad → sr`. The arrival rule gains its refusing clause and every degeneracy cluster ships `default_kind`. 27 of UnitSafe's 62 KOQ must-fails convert freely today. |
83
+ | Refusal keys on a principled marker | **withdrawn** | The plan was for the `base_form is None` proxy to give way to a declared `Unit.chart`. It cannot: `_canonical_magnitude` is contracted not to consult any graph and falls back to the raw quantity, so admitting `50 % + 1 fraction` yields `51 %` where the answer is `150 %`, and `20 °R + 5 K` yields `25` where it is `16.111 K`. `base_form` is load-bearing for the *arithmetic*, not only for the meaningfulness check. The two predicates are independent and both stay: chart answers "is this meaningful?", `base_form` answers "is this computable without the graph?" |
84
+ | Unity folds; named dimensionless units persist | 2.3.1 | `10 kg × 50 % → 5 kg` (today `<500 g·%>`, unconvertible); `rad/s` and `request/s` keep their symbols; the `ea` residue on every multiply step disappears once the placeholder is `one` (#307, #318; [proposals/percent-on-unity](docs/internal/proposals/percent-on-unity.md)) |
85
+ | Angle stays a quantity of dimension one | 3.0.0 | SI Brochure §2.3.4 is right: `m·rad = m`, `rad/s` is T⁻¹. `plane_angle` and `solid_angle` are **kinds** on unity; `degree → radian` is an ordinary edge. The earlier plan to promote angle is withdrawn — it fails the independence test and would have made arc length a cross-dimension error. |
86
+ | Over-refusals given base_forms, not relaxed gates | 3.0.0 | **62** same-fiber pairs over **34** units refuse today only because a `base_form` is missing — not five, as earlier drafts said. They are *correct* refusals with a misleading message (see *Refusal keys on a principled marker*), so the fix is to supply the `base_form`, never to relax the gate: 27 units are non-SI-basis (#283), 21 pseudo-dimensional (ADR 013's retirement, 3.0.0), 1 is `rankine` (#339), 1 is the unnamed unity unit, and 12 are genuinely non-ratio and must keep refusing. Three refusals are re-owned deliberately instead — `flop/s + Hz` (kinds, 2.3.0), `100 USD + 50 EUR` and `USD/MWh + EUR/MWh` (denomination signature, 2.6.0) — and two become admits: `kg·% + kg → 6 kg` and `m·rad + m → 4 m` (2.3.1). |
87
+ | Chart-crossing arithmetic returns a value | 3.2.0 | the chart stratum supplies factors and offsets, so `1 rad + 180 deg` converts rather than refusing; `20 °C + 5 °C` refuses as `point + point`; `20 °C + 5 K` admits |
76
88
 
77
89
  Two consequences worth stating plainly. `BaseForm.factors` is contracted to
78
- reference only canonical SI base units, so giving angle units a `base_form` to
79
- shortcut this would violate the type rather than fix it — the BFS oracle skips
80
- pseudo-dimensions for that reason. And #282 is the last open Turnstile
81
- prerequisite (#279 and #280 are closed), which puts v2.3.0 on the critical path
82
- for v3.1.0 despite reading as routine package work.
83
-
84
- ---
85
-
90
+ reference only canonical base units of its basis, so giving angle units a
91
+ `base_form` to shortcut this would violate the type rather than fix it — the
92
+ BFS oracle skips them for that reason — via `dim.is_pseudo`, which covers the
93
+ angle, ratio and count families (21 units); its separate empty-`base_expansion`
94
+ branch catches exactly one more, the unnamed unity unit. The angle family's
95
+ exact factors live on graph edges and its identity on kinds. And the open Turnstile
96
+ prerequisites are now #322's refusing clause and the retirement itself (#282
97
+ closed as #316) — declared `Unit.chart` is no longer among them, per
98
+ [010 §Amendment](docs/internal/decisions/010-chart-nomenclature.md#amendment-2026-10-18) — so v2.3.0 no longer carries the
99
+ chart stratum at all.
100
+
101
+ **Dependency audit, 2026-10-18.** Thirteen issues (#339–#348, #352–#354) reduce
102
+ to four root causes, the largest being the pseudo-dimension tags: eight open
103
+ issues are their consequences (#307, #318, #321, #336, #341, #344, #346, #348).
104
+ The retirement therefore unblocks the most — but it cannot simply move earlier,
105
+ because checking its prerequisites showed two of them were mis-read as features
106
+ queued in front of it:
107
+
108
+ - **#292 currency is a prerequisite.** No `currency` dimension or unit exists
109
+ today and the SI basis still carries `information` in slot 8, so 3.0.0's
110
+ "`currency` folds into slot 9 … and the shim transform retires" has nothing to
111
+ fold until v2.6.0 lands.
112
+ - **Part of the KOQ floor is a prerequisite.** `xdom-018`, `xdom-020` and
113
+ `pr-028` refuse today *only* because the pseudo-dimension tags differ; the
114
+ retirement removes the tags, so the angle kinds and the product-signature
115
+ `default_kind` mechanism must precede it or three must-fails regress. That half
116
+ is now v2.4.0; the half that genuinely needs the merged fiber is v3.1.0.
117
+
118
+ Array parity (#297, #298) was the only row checked and found *not* to be a
119
+ prerequisite, so it is the only one unsequenced. The retirement is late because
120
+ it is genuinely gated, not because it was queued badly.
121
+
122
+ ## The UnitSafe gate
123
+
124
+ ucon's downstream goal is the [UnitSafe](https://github.com/withtwoemms/ucon-tools/tree/main/benchmarks/unitsafe)
125
+ benchmark: 500 problems scored on numerical, unit-string, and kind-of-quantity
126
+ accuracy, with 124 must-fail items — 62 dimension mismatches and 62 pairs that
127
+ **share a dimension and differ in kind**. The treatment is a language model
128
+ driving [ucon-tools](https://github.com/withtwoemms/ucon-tools); its `compute`
129
+ tool multiplies floats and tracks kinds as metadata, so the benchmark exercises
130
+ ucon's catalog, `.to()`, and unit rendering — not its arithmetic dispatch.
131
+
132
+ What that makes gate-critical in this repository, in order:
133
+
134
+ 1. **The KOQ floor** (mechanism v2.3.0 ✓, angle clusters v2.4.0, remainder
135
+ v3.1.0) — the arrival rule's refusing clause shipped in #322 and six clusters
136
+ declare `default_kind`; the rest split by whether they precede or follow the
137
+ retirement. Measured end to end through
138
+ ucon-tools against the shipped catalog: the legitimate weighted
139
+ conversion `0.5 Gy × 20 Sv/Gy` is **refused** when its factor is kinded
140
+ (the lattice join is consulted, the `radiation_weighting` formula is not)
141
+ and **mislabeled** `10 Sv [absorbed_dose]` when it is not; the must-fail
142
+ direct `2 Gy → Sv` returns the same label. The tool cannot tell them
143
+ apart. The fix is split across both repositories and ships together.
144
+ 2. **Unity** (v2.3.1) — `one` as a real, parseable identity, and named
145
+ dimension-one units that survive products. The `ea` placeholder leaking
146
+ into every multiply-by-scalar result is the single largest unit-string
147
+ failure class.
148
+ 3. **Catalog correctness** — `lumen.base_form` (today `1 lm → 1 cd`
149
+ converts), `Np ↔ dB` (off by 2 against SI Brochure Table 8, #336),
150
+ `rankine`'s suppressed `base_form` (#339), and the two log edges that target
151
+ a quantity other than the one they chart (#341: `nines` hides `x ↦ 1 − x`;
152
+ `pH` is a level on `Dimension(concentration)`, where ISO 80000-9 item 9-37
153
+ makes it dimension one).
154
+
155
+ What is **not** on the gate: currency (zero problems), the logarithmic chart
156
+ (zero), count placement (no count-vs-count items), and the kind algebra of
157
+ 3.2.0 (unexercised by a float-path `compute`). Those remain library
158
+ correctness work and are sequenced accordingly. The larger lever for the score
159
+ is on the ucon-tools side — see its roadmap's v0.14.0 and v0.15.0.
86
160
  ## v1.9.x — Kind-of-Quantity Preview Line
87
161
 
88
162
  **Theme:** Land the kind subsystem as a complete, standalone data model before binding it to arithmetic.
@@ -73,15 +73,18 @@ from ucon.core import (
73
73
  DimensionConstraint,
74
74
  DimensionNotCovered,
75
75
  KindConstraint,
76
+ KindArrivalRefused,
76
77
  KindDimensionMismatch,
77
78
  KindMismatch,
78
79
  NonScalableError,
79
80
  Number,
80
81
  Ratio,
81
82
  RebasedUnit,
83
+ ScalarArithmeticRefused,
82
84
  Scale,
83
85
  Unit,
84
86
  UnitDefinitionMismatch,
87
+ ContingentCompositionRefused,
85
88
  UnitsNotNormalizable,
86
89
  UnitFactor,
87
90
  UnitProduct,
@@ -214,6 +217,7 @@ __all__ = [
214
217
  'EdgeDef',
215
218
  'Exponent',
216
219
  'KindConstraint',
220
+ 'KindArrivalRefused',
217
221
  'KindDimensionMismatch',
218
222
  'KindMismatch',
219
223
  'NonScalableError',
@@ -222,10 +226,12 @@ __all__ = [
222
226
  'ParseError',
223
227
  'Ratio',
224
228
  'RebasedUnit',
229
+ 'ScalarArithmeticRefused',
225
230
  'Scale',
226
231
  'Unit',
227
232
  'UnitDef',
228
233
  'UnitDefinitionMismatch',
234
+ 'ContingentCompositionRefused',
229
235
  'UnitsNotNormalizable',
230
236
  'UnitFactor',
231
237
  'UnitPackage',