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.
- {ucon-2.2.2 → ucon-2.3.0}/CHANGELOG.md +350 -0
- {ucon-2.2.2/ucon.egg-info → ucon-2.3.0}/PKG-INFO +1 -1
- {ucon-2.2.2 → ucon-2.3.0}/ROADMAP.md +93 -19
- {ucon-2.2.2 → ucon-2.3.0}/ucon/__init__.py +6 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/_cache.py +27 -1
- {ucon-2.2.2 → ucon-2.3.0}/ucon/comprehensive.ucon.toml +34 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/contexts.py +31 -2
- {ucon-2.2.2 → ucon-2.3.0}/ucon/conversion.py +325 -38
- {ucon-2.2.2 → ucon-2.3.0}/ucon/core/__init__.py +6 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/core/_types.py +734 -13
- {ucon-2.2.2 → ucon-2.3.0}/ucon/core/exceptions.py +150 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/formulas/__init__.py +2 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/formulas/exceptions.py +44 -1
- {ucon-2.2.2 → ucon-2.3.0}/ucon/formulas/registry.py +83 -10
- ucon-2.3.0/ucon/maps.py +1060 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/packages.py +158 -4
- {ucon-2.2.2 → ucon-2.3.0}/ucon/parsing/namespaces.py +4 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/serialization.py +34 -9
- {ucon-2.2.2 → ucon-2.3.0}/ucon/units.pyi +1 -0
- {ucon-2.2.2 → ucon-2.3.0/ucon.egg-info}/PKG-INFO +1 -1
- {ucon-2.2.2 → ucon-2.3.0}/ucon.egg-info/scm_file_list.json +10 -0
- ucon-2.3.0/ucon.egg-info/scm_version.json +8 -0
- ucon-2.2.2/ucon/maps.py +0 -561
- ucon-2.2.2/ucon.egg-info/scm_version.json +0 -8
- {ucon-2.2.2 → ucon-2.3.0}/.github/workflows/downstream.yaml +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/.github/workflows/publish.yaml +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/.github/workflows/tests.yaml +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/.gitignore +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/.gitmodules +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/LICENSE +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/MANIFEST.in +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/Makefile +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/NOTICE +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/README.md +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/SECURITY.md +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/SUPPORT.md +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/mkdocs.yml +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/netlify.toml +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/pyproject.toml +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/requirements.txt +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/setup.cfg +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/_active.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/_algebra_cache.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/_bootstrap.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/aspects/__init__.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/aspects/exceptions.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/aspects/forest.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/aspects/resolution.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/aspects/types.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/basis/__init__.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/basis/builtin.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/basis/graph.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/basis/ops.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/basis/transforms.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/basis/types.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/basis/vector.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/checking.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/constants.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/constants.pyi +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/core/_parsing_graph.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/dimension.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/dimension.pyi +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/expressions.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/formulas/types.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/graph.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/integrations/__init__.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/integrations/numpy.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/integrations/pandas.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/integrations/polars.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/integrations/pydantic.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/kinds/__init__.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/kinds/exceptions.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/kinds/lattice.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/kinds/types.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/parsing/__init__.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/parsing/aspects.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/parsing/dimensions.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/parsing/formulas.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/parsing/kinds.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/parsing/lexer.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/parsing/quantity.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/parsing/units.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/quantity.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/resolver.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/system/__init__.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon/units.py +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon.egg-info/SOURCES.txt +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon.egg-info/dependency_links.txt +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon.egg-info/requires.txt +0 -0
- {ucon-2.2.2 → ucon-2.3.0}/ucon.egg-info/top_level.txt +0 -0
- {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
|
|
@@ -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,
|
|
49
|
-
| v2.3.0 | **
|
|
50
|
-
| v2.
|
|
51
|
-
| v2.
|
|
52
|
-
|
|
|
53
|
-
|
|
|
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
|
|
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.
|
|
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
|
-
|
|
|
74
|
-
|
|
|
75
|
-
|
|
|
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
|
|
79
|
-
shortcut this would violate the type rather than fix it — the
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
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',
|