ucon 2.3.0__tar.gz → 2.4.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 (90) hide show
  1. {ucon-2.3.0 → ucon-2.4.0}/CHANGELOG.md +241 -0
  2. {ucon-2.3.0/ucon.egg-info → ucon-2.4.0}/PKG-INFO +1 -1
  3. {ucon-2.3.0 → ucon-2.4.0}/ROADMAP.md +5 -5
  4. {ucon-2.3.0 → ucon-2.4.0}/ucon/__init__.py +4 -0
  5. {ucon-2.3.0 → ucon-2.4.0}/ucon/_cache.py +59 -0
  6. {ucon-2.3.0 → ucon-2.4.0}/ucon/aspects/__init__.py +2 -0
  7. {ucon-2.3.0 → ucon-2.4.0}/ucon/aspects/exceptions.py +43 -0
  8. {ucon-2.3.0 → ucon-2.4.0}/ucon/comprehensive.ucon.toml +291 -4
  9. {ucon-2.3.0 → ucon-2.4.0}/ucon/core/__init__.py +2 -0
  10. {ucon-2.3.0 → ucon-2.4.0}/ucon/core/_types.py +233 -15
  11. {ucon-2.3.0 → ucon-2.4.0}/ucon/core/exceptions.py +48 -0
  12. {ucon-2.3.0 → ucon-2.4.0}/ucon/formulas/exceptions.py +6 -2
  13. {ucon-2.3.0 → ucon-2.4.0}/ucon/formulas/registry.py +46 -23
  14. {ucon-2.3.0 → ucon-2.4.0}/ucon/formulas/types.py +24 -1
  15. {ucon-2.3.0 → ucon-2.4.0}/ucon/parsing/formulas.py +3 -0
  16. {ucon-2.3.0 → ucon-2.4.0}/ucon/serialization.py +13 -7
  17. {ucon-2.3.0 → ucon-2.4.0}/ucon/units.pyi +1 -0
  18. {ucon-2.3.0 → ucon-2.4.0/ucon.egg-info}/PKG-INFO +1 -1
  19. {ucon-2.3.0 → ucon-2.4.0}/ucon.egg-info/scm_file_list.json +8 -0
  20. ucon-2.4.0/ucon.egg-info/scm_version.json +8 -0
  21. ucon-2.3.0/ucon.egg-info/scm_version.json +0 -8
  22. {ucon-2.3.0 → ucon-2.4.0}/.github/workflows/downstream.yaml +0 -0
  23. {ucon-2.3.0 → ucon-2.4.0}/.github/workflows/publish.yaml +0 -0
  24. {ucon-2.3.0 → ucon-2.4.0}/.github/workflows/tests.yaml +0 -0
  25. {ucon-2.3.0 → ucon-2.4.0}/.gitignore +0 -0
  26. {ucon-2.3.0 → ucon-2.4.0}/.gitmodules +0 -0
  27. {ucon-2.3.0 → ucon-2.4.0}/LICENSE +0 -0
  28. {ucon-2.3.0 → ucon-2.4.0}/MANIFEST.in +0 -0
  29. {ucon-2.3.0 → ucon-2.4.0}/Makefile +0 -0
  30. {ucon-2.3.0 → ucon-2.4.0}/NOTICE +0 -0
  31. {ucon-2.3.0 → ucon-2.4.0}/README.md +0 -0
  32. {ucon-2.3.0 → ucon-2.4.0}/SECURITY.md +0 -0
  33. {ucon-2.3.0 → ucon-2.4.0}/SUPPORT.md +0 -0
  34. {ucon-2.3.0 → ucon-2.4.0}/mkdocs.yml +0 -0
  35. {ucon-2.3.0 → ucon-2.4.0}/netlify.toml +0 -0
  36. {ucon-2.3.0 → ucon-2.4.0}/pyproject.toml +0 -0
  37. {ucon-2.3.0 → ucon-2.4.0}/requirements.txt +0 -0
  38. {ucon-2.3.0 → ucon-2.4.0}/setup.cfg +0 -0
  39. {ucon-2.3.0 → ucon-2.4.0}/ucon/_active.py +0 -0
  40. {ucon-2.3.0 → ucon-2.4.0}/ucon/_algebra_cache.py +0 -0
  41. {ucon-2.3.0 → ucon-2.4.0}/ucon/_bootstrap.py +0 -0
  42. {ucon-2.3.0 → ucon-2.4.0}/ucon/aspects/forest.py +0 -0
  43. {ucon-2.3.0 → ucon-2.4.0}/ucon/aspects/resolution.py +0 -0
  44. {ucon-2.3.0 → ucon-2.4.0}/ucon/aspects/types.py +0 -0
  45. {ucon-2.3.0 → ucon-2.4.0}/ucon/basis/__init__.py +0 -0
  46. {ucon-2.3.0 → ucon-2.4.0}/ucon/basis/builtin.py +0 -0
  47. {ucon-2.3.0 → ucon-2.4.0}/ucon/basis/graph.py +0 -0
  48. {ucon-2.3.0 → ucon-2.4.0}/ucon/basis/ops.py +0 -0
  49. {ucon-2.3.0 → ucon-2.4.0}/ucon/basis/transforms.py +0 -0
  50. {ucon-2.3.0 → ucon-2.4.0}/ucon/basis/types.py +0 -0
  51. {ucon-2.3.0 → ucon-2.4.0}/ucon/basis/vector.py +0 -0
  52. {ucon-2.3.0 → ucon-2.4.0}/ucon/checking.py +0 -0
  53. {ucon-2.3.0 → ucon-2.4.0}/ucon/constants.py +0 -0
  54. {ucon-2.3.0 → ucon-2.4.0}/ucon/constants.pyi +0 -0
  55. {ucon-2.3.0 → ucon-2.4.0}/ucon/contexts.py +0 -0
  56. {ucon-2.3.0 → ucon-2.4.0}/ucon/conversion.py +0 -0
  57. {ucon-2.3.0 → ucon-2.4.0}/ucon/core/_parsing_graph.py +0 -0
  58. {ucon-2.3.0 → ucon-2.4.0}/ucon/dimension.py +0 -0
  59. {ucon-2.3.0 → ucon-2.4.0}/ucon/dimension.pyi +0 -0
  60. {ucon-2.3.0 → ucon-2.4.0}/ucon/expressions.py +0 -0
  61. {ucon-2.3.0 → ucon-2.4.0}/ucon/formulas/__init__.py +0 -0
  62. {ucon-2.3.0 → ucon-2.4.0}/ucon/graph.py +0 -0
  63. {ucon-2.3.0 → ucon-2.4.0}/ucon/integrations/__init__.py +0 -0
  64. {ucon-2.3.0 → ucon-2.4.0}/ucon/integrations/numpy.py +0 -0
  65. {ucon-2.3.0 → ucon-2.4.0}/ucon/integrations/pandas.py +0 -0
  66. {ucon-2.3.0 → ucon-2.4.0}/ucon/integrations/polars.py +0 -0
  67. {ucon-2.3.0 → ucon-2.4.0}/ucon/integrations/pydantic.py +0 -0
  68. {ucon-2.3.0 → ucon-2.4.0}/ucon/kinds/__init__.py +0 -0
  69. {ucon-2.3.0 → ucon-2.4.0}/ucon/kinds/exceptions.py +0 -0
  70. {ucon-2.3.0 → ucon-2.4.0}/ucon/kinds/lattice.py +0 -0
  71. {ucon-2.3.0 → ucon-2.4.0}/ucon/kinds/types.py +0 -0
  72. {ucon-2.3.0 → ucon-2.4.0}/ucon/maps.py +0 -0
  73. {ucon-2.3.0 → ucon-2.4.0}/ucon/packages.py +0 -0
  74. {ucon-2.3.0 → ucon-2.4.0}/ucon/parsing/__init__.py +0 -0
  75. {ucon-2.3.0 → ucon-2.4.0}/ucon/parsing/aspects.py +0 -0
  76. {ucon-2.3.0 → ucon-2.4.0}/ucon/parsing/dimensions.py +0 -0
  77. {ucon-2.3.0 → ucon-2.4.0}/ucon/parsing/kinds.py +0 -0
  78. {ucon-2.3.0 → ucon-2.4.0}/ucon/parsing/lexer.py +0 -0
  79. {ucon-2.3.0 → ucon-2.4.0}/ucon/parsing/namespaces.py +0 -0
  80. {ucon-2.3.0 → ucon-2.4.0}/ucon/parsing/quantity.py +0 -0
  81. {ucon-2.3.0 → ucon-2.4.0}/ucon/parsing/units.py +0 -0
  82. {ucon-2.3.0 → ucon-2.4.0}/ucon/quantity.py +0 -0
  83. {ucon-2.3.0 → ucon-2.4.0}/ucon/resolver.py +0 -0
  84. {ucon-2.3.0 → ucon-2.4.0}/ucon/system/__init__.py +0 -0
  85. {ucon-2.3.0 → ucon-2.4.0}/ucon/units.py +0 -0
  86. {ucon-2.3.0 → ucon-2.4.0}/ucon.egg-info/SOURCES.txt +0 -0
  87. {ucon-2.3.0 → ucon-2.4.0}/ucon.egg-info/dependency_links.txt +0 -0
  88. {ucon-2.3.0 → ucon-2.4.0}/ucon.egg-info/requires.txt +0 -0
  89. {ucon-2.3.0 → ucon-2.4.0}/ucon.egg-info/top_level.txt +0 -0
  90. {ucon-2.3.0 → ucon-2.4.0}/uv.lock +0 -0
@@ -7,6 +7,247 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [2.4.0] - 2026-11-21
11
+
12
+ ### Added
13
+
14
+ - **The angle kinds, `plane_angle` and `solid_angle` (#348, #344).** `radian`,
15
+ `degree`, `gradian`, `turn`, `arcminute` and `arcsecond` declare
16
+ `default_kind = "plane_angle"`; `steradian` and `square_degree` declare
17
+ `solid_angle`. They are **two independent roots**, not siblings: the kinds
18
+ carry different dimensions and `KindLattice` rejects a cross-dimension parent
19
+ edge (`CrossDimensionParent`), so `lca` reports `DisjointKinds`. This
20
+ forecloses SI's `sr = rad²`, a *power* relation no parent edge expresses; it
21
+ waits on composing kinds and survives meanwhile only as the hand-squared
22
+ `square_degree → steradian` factor. Nothing new refuses — `rad → sr`,
23
+ `rad/s → Hz` and `W/m² → W/sr` raise what they raised before — the kinds are
24
+ insurance for ADR 013, which dissolves the `angle` pseudo-dimension at 3.0.0.
25
+ Of the cross-domain cases this insures `xdom-018` alone: `rad/s` is a
26
+ `UnitProduct` carrying no kind (needs #342, #343), and `W/m² → W/sr` refuses
27
+ on genuine SI signatures (`M·T⁻³` vs `M·L²·T⁻³`) with no tag involved.
28
+
29
+
30
+ - **`Number.to(..., kind=)` — the kind the caller claims the result is (#373,
31
+ #342, #343).** Default `None` leaves the arrival rule in charge, so every
32
+ existing call is unchanged. A claim is admitted only if *implied* by the kind
33
+ already carried — it restates that kind, or weakens it to an ancestor whose
34
+ `join_policy` permits generalizing. Strengthening a kind or exchanging it for
35
+ a sibling raises the new `KindClaimRefused`; a cross-fiber claim is taken as
36
+ given; `KindNotFound` for an unresolvable name.
37
+
38
+ This reaches errors no property of a unit can. *"Report 100 MPa of tensile
39
+ stress as a hydrostatic pressure"* converts `MPa → MPa`; `0.5 MJ/m³ → kPa` is
40
+ a legitimate modulus of resilience while `500 kJ/m³ → kPa` *as a stress* is
41
+ not, and unclaimed the two are one conversion returning `<500.0 kPa>`. Only
42
+ the claim separates them — which is why the product-signature `default_kind`
43
+ plan on #342/#343 could not.
44
+
45
+ - **An `energy_density` kind**, declared and attached to nothing. A second root
46
+ on `Dimension(pressure)` rather than a child of `pressure`: same dimension and
47
+ same derivation — `(N·m)/m³` reduces to `N/m²` — but a different quantity, so
48
+ `lca` reports `DisjointKinds` against the pressure family. `J/m³` carries no
49
+ `default_kind` deliberately, for the reason above.
50
+
51
+ - **`Number.to(..., aspect=)`, and the first aspect families in the catalog
52
+ (#343).** Closes the last two must-fails of UnitSafe's pressure cluster —
53
+ *"report dynamic pressure as static pressure"* and *"equate atmospheric with
54
+ lithostatic pressure"* — taking it to 6 of 6. Both convert a unit to itself
55
+ **and** carry the same kind on both sides, so neither a unit nor a kind could
56
+ reach them: what differs is an adjective.
57
+
58
+ `pressure_role` (`static_pressure`, `dynamic_pressure`) and `pressure_origin`
59
+ (`atmospheric_pressure`, `lithostatic_pressure`, `hydrostatic_pressure`) are
60
+ declared on `join_policy = "lca"` with `applies_to` naming the pressure kinds,
61
+ so a quantity with no kind cannot carry them. They are **not** kinds, and the
62
+ reason is a must-pass row: `P0 = P + ½ρV²` is static plus dynamic, kinds refuse
63
+ addition across disjoint members, so kind-ifying these would make Bernoulli's
64
+ equation refuse. As aspects the sum lifts to the family root — a total
65
+ pressure, role unspecified — while the relabel still refuses, because a claim
66
+ is gated on implication rather than on the join (#376). One declaration serves
67
+ both operations.
68
+
69
+ Claims resolve family-wise, so a value may carry a role and an origin at once
70
+ and a claim about one leaves the other alone. Unknown names propagate the
71
+ forest's own `AspectError`.
72
+
73
+ - **The graph cache now carries the aspect forest.** `ucon/_cache.py` serialized
74
+ the kind lattice and silently dropped aspects, so a declared forest existed
75
+ only under `UCON_NO_CACHE=1` — latent until this release, since no aspects were
76
+ declared. Encode, decode and a parent-first builder now mirror the kinds pass.
77
+
78
+ - **The surface power density kinds: `irradiance`, `radiative_forcing` and
79
+ `heat_flux` (#344).** Three ISO 80000-7 / IPCC quantities share `W/m²`, and
80
+ UnitSafe names the confusion directly — *"equate radiative forcing with heat
81
+ flux as physically identical quantities"* and *"report solar irradiance as
82
+ radiative forcing"*. Disjoint siblings under a refusing
83
+ `surface_power_density` root, the idiom the power, pressure and frequency
84
+ clusters already use, so a crossing refuses while every same-kind conversion
85
+ in the cluster still admits. Nothing attaches them: `W/m²` is a `UnitProduct`
86
+ and the unit genuinely does not say which quantity it carries, so the caller
87
+ states it with `Number.to(..., kind=)`.
88
+
89
+ This is the first kind in the catalog whose dimension is declared as an
90
+ **expression** (`"mass/time^3"`) rather than a registered name, since `W/m²`
91
+ reduces to M·T⁻³ and SI does not name it.
92
+
93
+ - **Clearance vs blood flow, and hydraulic head vs distance (#344).** Two more
94
+ of UnitSafe's unclustered `koq_mismatch` must-fails. `volumetric_flow_rate`
95
+ roots `clearance` and `blood_flow` (L³/T); `length_quantity` roots `distance`
96
+ and `hydraulic_head`. Both pairs fail the add-test — a total clearance is the
97
+ sum of *clearances*, never of a clearance and a flow, and a head and a
98
+ distance do not sum at all — so they are kinds rather than aspects.
99
+
100
+ Nothing attaches them. `meter` carries no `default_kind` and must not: most
101
+ lengths are plain distances, and tagging the unit would force a claim onto
102
+ every one of them. Every clearance must-pass in the benchmark is a same-kind
103
+ unit conversion and still admits.
104
+
105
+ `gfr` is **deliberately not** declared as a sibling of `clearance`: the
106
+ benchmark keys its GFR must-passes as `clearance`, so splitting them would
107
+ refuse a claim the dataset makes. Recorded as a test so the omission reads as
108
+ a decision rather than an oversight.
109
+
110
+ - **Weight basis and administration route as aspects (#344).** Two more
111
+ unclustered `koq_mismatch` must-fails: *"treat ideal body weight and actual
112
+ body weight as identical for dosing"* and *"equate oral morphine equivalent
113
+ dose with IV morphine equivalent dose"*. `body_weight_basis`
114
+ (`ideal_body_weight`, `actual_body_weight`) and `administration_route`
115
+ (`oral_route`, `intravenous_route`), both on `join_policy = "lca"`, with
116
+ `body_mass` and `drug_dose` declared as the kinds they attach to since `mass`
117
+ had none.
118
+
119
+ Aspects rather than kinds because the pair **sums**: a total opioid burden is
120
+ the sum across routes, which is the entire purpose of a morphine-equivalent
121
+ dose. `30 mg` oral plus `10 mg` IV now answers `<40 mg [drug_dose]
122
+ #administration_route>` — total dose, route unspecified — while relabelling
123
+ one route as the other refuses. Kind-ifying them would have broken the sum.
124
+
125
+ Nothing attaches them: a bare `kg` is neither a dose nor a body weight, and
126
+ still carries no kind or aspect.
127
+
128
+ - **Canonical `one`: the unity unit is named, and `"1"` resolves to it (#307).**
129
+ The catalog already declared a `Dimension(none)` unity unit, but with
130
+ `name = ""` — undiscoverable, so `"1"`, `"dimensionless"` and `"unitless"` had
131
+ been given to `fraction`, which carries `Dimension(ratio)`. The obvious
132
+ dimensionless literal therefore landed on the one fiber where a
133
+ `Dimension(none)` kind cannot attach, and
134
+ `Number(20, parse_unit('1'), kind=radiation_weighting_factor)` raised
135
+ `KindDimensionMismatch`. The unit is now `units.one` and those three aliases
136
+ resolve to it, so `Gy * w_R` answers `<40 Gy [dose_equivalent]>` with the
137
+ literal a caller would write.
138
+
139
+ `""` is kept as an alias deliberately: dimensionless *constants* are carried
140
+ by the empty-string unit name. `fraction` keeps `frac` and keeps
141
+ `Dimension(ratio)` — emptying the ratio fiber into `Scale` is 3.0.0's work.
142
+
143
+ - **Division dispatches kinds through its own table (#381).** `/` consulted the
144
+ formula registry with the same key `*` uses, so a formula declared for a
145
+ *product* answered the *quotient* — `Gy * w_R` is a dose equivalent and
146
+ `Gy / w_R` claimed to be one too. v2.3.0's #352 shipped the refusal half of
147
+ this (`Gy / Sv` stopped cancelling to `1.0`); this is the dispatch half.
148
+
149
+ **Operation is now part of a formula's identity.** `KindFormula` gains an
150
+ `operation` field — `Operation.MULTIPLY` (default) or `Operation.DIVIDE` — and
151
+ every registry index is keyed on it, so all four lookup tiers and the
152
+ collision guard became operation-aware together. `commutative` is unchanged
153
+ and remains a different axis: operand *order within* one operation.
154
+
155
+ This widens #347's guard, which read a product and a quotient over one input
156
+ tuple as a single signature — so the inverse declaration ADR 013 §4 names as
157
+ the route to a quotient kind was unregisterable. Both now register, each
158
+ answers only its own operation, and a collision *within* an operation still
159
+ refuses. Additive: formulas declared before this default to `MULTIPLY`.
160
+
161
+ - **A dimension-one unit that names a quantity survives a product (#318).**
162
+ `UnitProduct` dropped every `Dimension(none)` factor at construction, keeping
163
+ its *scale* and discarding the unit — so the scale survived without the thing
164
+ it scaled, and a money-rate unit could not be constructed, kinded, or carry a
165
+ declaration. `USD/kWh` rendered as `1/(kW·h)` and `100 kWh × 0.12 USD/kWh`
166
+ answered `<12.0>`; they are now `<UnitProduct USD/(kW·h)>` and `<12.0 USD>`.
167
+
168
+ The discriminator is **identity, not name**: #307 named the canonical unity
169
+ `one` in this same release, so "anonymous" stopped being a usable proxy for
170
+ "is the identity" — a first cut rendered `one * kg` as `one·kg`. Folding keys
171
+ on the unity itself, so `one * kg` is `kg` while `USD/h` keeps its symbol.
172
+
173
+ Four sites carried the same "dimensionless means unity" assumption: the
174
+ reduction path, both construction fast paths, and `Unit.shorthand`, which
175
+ blanked every `Dimension(none)` unit — making `USD` invisible on a bare
176
+ `Number` while a one-factor `UnitProduct` of the same unit rendered it.
177
+
178
+ This reverses a stated canonical-form invariant: "no dimensionless factor
179
+ survives" becomes "no *unity* factor survives". Six tests encoding the old
180
+ form are updated, each gaining a companion for the new rule. Magnitudes are
181
+ unchanged — a scaled symbol carries its scale on the surviving factor, a
182
+ scaled unity still folds into `canonical_scale`. Unblocks the money-rate
183
+ pattern ADR 011 reserves for fee schedules: `500 MWh × 48 USD/MWh` now
184
+ answers `<24000.0 USD [usd]>` in both operand orders, pinned as a test.
185
+
186
+ - **A kind on an unnamed derived dimension no longer breaks the TOML
187
+ round-trip.** `Dimension` renders a vector with no registered name as
188
+ `derived(mass/time^3)`, which is a *rendering*, not an identifier —
189
+ `parse_dimension` rejects it with *"Unknown dimension identifier 'derived'"*.
190
+ Both `_serialize_kind` and `_dimension_to_expression` treated it as a name and
191
+ emitted it verbatim, so any such kind failed to reload. The expression is now
192
+ rebuilt from the vector (`M/T^3`) whenever the name is a `derived(...)`
193
+ rendering. Latent until now, because no kind was declared on an unnamed
194
+ dimension.
195
+
196
+ ### Documentation
197
+
198
+ - **Three roadmap corrections, all scheduling rather than scope.**
199
+
200
+ *`**` moves from v2.3.1 to v3.2.0.* The deferred-behaviour suite named the
201
+ contradiction: the bullet's own "Blocked by" line cites `DerivedKind` and a `**`
202
+ dispatch row as **v3.2.0** work, while "Fixed in" claimed v2.3.1 — three minor
203
+ releases ahead of its prerequisite. v3.2.0 already lists the dispatch row, so the
204
+ bullet now sits beside it.
205
+
206
+ The test docstring also records *why* it matters, since `kind is None` reads as
207
+ harmless: `**` launders the kind stratum.
208
+ `Gy[absorbed_dose] + Sv[dose_equivalent]` raises `JoinRefused`, while
209
+ `(Gy)**2 + (Sv)**2` answers `<13.0 Gy²>` — squaring two incommensurable
210
+ quantities makes them addable. And `None` is a false claim, not a missing one:
211
+ `Gy²` has a kind and lacks a *name*, as `m × m` is `derived(length^2)`.
212
+
213
+ *v2.6.0 and v3.0.0 decouple from the currency basis component (#292).* The
214
+ basis-component design rested on currency needing a guard that holds with no kind
215
+ lattice installed; #383 made that guard structural, since base-form signatures
216
+ carry the currency symbol. The v3.0.0 row now states the basis rename and shim
217
+ retirement on their own footing — `information` has held slot 8 since before
218
+ currency was proposed — with the slot-9 fold contingent on #292's review, and
219
+ v2.6.0 no longer asserts 3.0.0-prerequisite status.
220
+
221
+
222
+
223
+ - **A regression suite pinning the deferred behaviours**
224
+ (`tests/ucon/test_deferred_behaviours.py`). Eleven assertions record what
225
+ ucon does *today* where what it does is known-wrong, filed, and blocked
226
+ behind a release that has not happened: the `nines` scalar/additive
227
+ contradiction (#341), same-unit addition on points and levels (#340's
228
+ explicitly out-of-scope half, ADR 009 §3), `lm → cd` (#346), the
229
+ dimensionless kinds that cannot attach to `percent`/`fraction` (#344),
230
+ `rad² ↔ sr` and the idempotent tag algebra (#348), `Number` being
231
+ unhashable (#353, blocked on #362), `**` dropping the kind, and the
232
+ torque/energy and pressure/energy-density clusters converting freely
233
+ (#342, #343). Each test's docstring names the issue, the blocker and the
234
+ release that closes it, so changing one of these behaviours fails CI and
235
+ points the reader at the filed cause instead of inviting a re-diagnosis.
236
+ The file is not a specification of intent; it is the companion to
237
+ `tests/ucon/core/test_operator_stratum_grid.py` for behaviours that are
238
+ not cells of that grid.
239
+
240
+
241
+ - **The v2.4.0 roadmap row records that #342 and #343 moved to #373.** Both issues
242
+ prescribed `default_kind` on product signatures. Measurement against UnitSafe says
243
+ otherwise: four of cluster 7's six must-fails convert a unit to itself
244
+ (`MPa → MPa`), which no unit-keyed tag can reach, and tagging `J/m³` with
245
+ `energy_density` would fail the must-pass `0.5 MJ/m³ → kPa` — the same operation as
246
+ the must-fail `500 kJ/m³ → kPa`, differing only in the claim. A `kind=` argument on
247
+ `Number.to()` (#373) clears 12 of the 14 must-fails against the lattice as it
248
+ stands, since `join(torque, energy)` already refuses while `join(torque, torque)`
249
+ admits. Both issues keep their diagnoses and carry a comment pointing at #373.
250
+
10
251
  ## [2.3.0] - 2026-10-20
11
252
 
12
253
  ### Added
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ucon
3
- Version: 2.3.0
3
+ Version: 2.4.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>
@@ -47,12 +47,12 @@ This roadmap tracks **major milestones** on the path to v2. For incremental upda
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
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
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 |
50
+ | v2.4.0 | **Unity, the dimensionless fold, and the pre-retirement KOQ floor** — the v2.3.1 and v2.4.0 rows shipped together and are merged here; see CHANGELOG 2.4.0. Canonical `one` resolving from `"1"`, `"dimensionless"` and `"unitless"` (#307); `UnitProduct` keeps a dimension-one unit that names a quantity and folds only the unity (#318); division dispatches kinds through its own table, with the operation part of a formula's identity (#381, widening #347's guard). **The KOQ floor arrived by a different route than planned:** #342/#343 needed a claim at the conversion boundary, not `default_kind` on product signatures — `Number.to(..., kind=)` and `Number.to(..., aspect=)` (#373), gated on implication rather than on the join `+` applies (#376). Clusters closed: torque/energy 8/8 (#342 ✓), pressure/stress/energy-density 6/6 (#343 ✓), plus six of the twenty unclustered `koq_mismatch` must-fails — surface power density, clearance vs blood flow, hydraulic head vs distance, weight basis and administration route. Angle kinds declared and carried (#348, #344). First aspect families in the catalog, and the graph cache taught to carry the aspect forest. **Not in this release:** `angular_velocity` and the first deprecation rung, both carried to v2.5.0; the `Scale` correctness work, carried to v2.4.1. *UnitSafe: high — 12 of the 14 KOQ-floor must-fails are reachable, and the `ea` residue is gone from every multiply step.* | Complete |
51
+ | v2.4.1 | **`Scale` calculates exactly** — `Scale × Scale`, `Scale / Scale` and `Scale ** n` compute the exact exponent and then discard it when no named prefix matches, falling through to `Scale.nearest()`: **244 of 522 single-base pairs return a wrong scale**, `centi × centi` as `milli` and, where `nearest` clamps at the table's ends, `femto × femto` as `femto` — off by 10¹⁵. Naming cannot fix it: a finite set of powers is never closed under multiplication, and adding the full SI set *raises* the unnamed count from 208 to 528. So `Scale` carries an `Exponent` and the conventional prefixes become a registry over it — `.name` renders `10^-4` where no name exists, as `Dimension` already renders `derived(mass/time^3)`. Measured on a prototype: 522/522 exact, zero regressions, named results keep identity, cross-base products keep `nearest()` since no exact power exists there. Cache and serialization key on `Scale[scale_name]`, so the wire form becomes `(base, power)`. Plus `UnitProduct.canonical_scale` entering identity — two products with `canonical_scale` 1.0 and 100.0 compare **equal** and hash **equal** while yielding magnitudes 100× apart, which breaks the hash contract and is reachable from ordinary code. *UnitSafe: none — `Number` arithmetic routes through `UnitProduct`, which does not fold scales, so no benchmark path is affected.* | Planned |
52
+ | v2.5.0 | **Deprecation rungs and `Scale` members** — **carried from v2.4.0:** the `angular_velocity` kind (#344, #348 — insurance for the retirement; `rad/s → Hz` already refuses on base-form signatures, so no must-fail is exposed meanwhile) and the first deprecation rung (`PendingDeprecationWarning`). Note the ladder wants rung one to precede rung two by a release; if both land here the warning window collapses, so rung one should ride a 2.4.x if one emerges. Then `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) — **Under review 2026-11-20 ([#292](https://github.com/withtwoemms/ucon/issues/292)):** the basis-component design rested on currency needing a guard that holds with no kind lattice installed, and #383 made that guard structural — base-form signatures carry the currency symbol, so `USD/yr → Hz` and `USD/yr + EUR/yr` already refuse. If that argument holds, this row loses its slot-9 work and its 3.0.0-prerequisite status, keeping only the `fx` package, star-topology validation and `ContingentCollision`. `[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
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 |
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`; the system basis is renamed and the shim transform retires — it has not been SI since `information` took slot 8, which is reason enough independent of currency; `currency` folds into slot 9 **only if** #292 keeps the basis-component design, now under review; `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
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
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
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 |
@@ -74,6 +74,7 @@ from ucon.core import (
74
74
  DimensionNotCovered,
75
75
  KindConstraint,
76
76
  KindArrivalRefused,
77
+ KindClaimRefused,
77
78
  KindDimensionMismatch,
78
79
  KindMismatch,
79
80
  NonScalableError,
@@ -111,6 +112,7 @@ from ucon.formulas import FormulaRegistry
111
112
  from ucon.aspects import (
112
113
  Aspect,
113
114
  AspectError,
115
+ AspectClaimRefused,
114
116
  AspectNotApplicable,
115
117
  AspectRefused,
116
118
  )
@@ -197,6 +199,7 @@ __all__ = [
197
199
  'InvalidRename',
198
200
  'Aspect',
199
201
  'AspectError',
202
+ 'AspectClaimRefused',
200
203
  'AspectNotApplicable',
201
204
  'AspectRefused',
202
205
  'Kind',
@@ -218,6 +221,7 @@ __all__ = [
218
221
  'Exponent',
219
222
  'KindConstraint',
220
223
  'KindArrivalRefused',
224
+ 'KindClaimRefused',
221
225
  'KindDimensionMismatch',
222
226
  'KindMismatch',
223
227
  'NonScalableError',
@@ -47,6 +47,10 @@ _HEADER_FMT = "!4sHBBB3s"
47
47
  _HEADER_SIZE = struct.calcsize(_HEADER_FMT)
48
48
 
49
49
 
50
+ from ucon.aspects.forest import AspectForest
51
+ from ucon.aspects.types import Aspect, MultPolicy
52
+ from ucon.kinds.types import JoinPolicy
53
+
50
54
  def _env_disabled() -> bool:
51
55
  return os.environ.get("UCON_NO_CACHE", "").strip() in ("1", "true", "yes")
52
56
 
@@ -357,6 +361,22 @@ def _to_primitives(graph: "Graph") -> dict:
357
361
  "a": kind.aliases,
358
362
  }
359
363
 
364
+ # --- Pass 5a: Aspects ---
365
+ # Mirrors the Kinds pass. Without this the forest is silently dropped on
366
+ # every cache hit, which is the default path -- declared aspects would
367
+ # exist only under ``UCON_NO_CACHE=1``.
368
+ aspect_forest = getattr(graph, "_aspect_forest", None)
369
+ if aspect_forest is not None:
370
+ for aspect in aspect_forest:
371
+ out[f"a:{aspect.name}"] = {
372
+ "_t": "A",
373
+ "n": aspect.name,
374
+ "p": aspect.parent.name if aspect.parent else None,
375
+ "jp": aspect.join_policy.value,
376
+ "at": sorted(aspect.applies_to),
377
+ "mp": aspect.multiplication_policy.value,
378
+ }
379
+
360
380
  # --- Pass 5b: Formulas ---
361
381
  if hasattr(graph, '_formula_registry') and graph._formula_registry is not None:
362
382
 
@@ -729,6 +749,16 @@ def _from_primitives(raw: dict) -> "Graph":
729
749
  kind_lattice = KindLattice(kind_obj_map.values())
730
750
  graph._kind_lattice = kind_lattice
731
751
 
752
+ # --- Pass 7a: Aspects ---
753
+ aspect_data_map: dict[str, dict] = {}
754
+ for key, val in raw.items():
755
+ if key.startswith("a:") and val.get("_t") == "A":
756
+ aspect_data_map[val["n"]] = val
757
+ if aspect_data_map:
758
+ aspect_obj_map: dict[str, "Aspect"] = {}
759
+ _build_aspects_recursive(aspect_data_map, aspect_obj_map)
760
+ graph._aspect_forest = AspectForest(aspect_obj_map.values())
761
+
732
762
  # --- Pass 7b: Formulas ---
733
763
  formula_data: list[dict] = []
734
764
  for key, val in raw.items():
@@ -875,6 +905,35 @@ def _from_primitives(raw: dict) -> "Graph":
875
905
  return graph
876
906
 
877
907
 
908
+ def _build_aspects_recursive(
909
+ data_map: dict[str, dict],
910
+ obj_map: dict[str, "Aspect"],
911
+ ) -> None:
912
+ """Build Aspect objects in parent-first order.
913
+
914
+ The peer of :func:`_build_kinds_recursive`. Aspects carry no dimension, so
915
+ there is no dim_map; ``applies_to`` and ``multiplication_policy`` are
916
+ root-only and round-trip as declared.
917
+ """
918
+ def _build(name: str) -> "Aspect":
919
+ if name in obj_map:
920
+ return obj_map[name]
921
+ val = data_map[name]
922
+ parent = _build(val["p"]) if val["p"] is not None else None
923
+ aspect = Aspect(
924
+ name=val["n"],
925
+ parent=parent,
926
+ join_policy=JoinPolicy(val["jp"]),
927
+ applies_to=frozenset(val.get("at") or ()),
928
+ multiplication_policy=MultPolicy(val["mp"]),
929
+ )
930
+ obj_map[name] = aspect
931
+ return aspect
932
+
933
+ for aspect_name in data_map:
934
+ _build(aspect_name)
935
+
936
+
878
937
  def _build_kinds_recursive(
879
938
  data_map: dict[str, dict],
880
939
  obj_map: dict[str, "Kind"],
@@ -16,6 +16,7 @@ Design record: ``docs/internal/decisions/008-aspect-stratum.md``.
16
16
 
17
17
  from ucon.aspects.exceptions import (
18
18
  AspectError,
19
+ AspectClaimRefused,
19
20
  AspectNotApplicable,
20
21
  AspectRefused,
21
22
  )
@@ -31,5 +32,6 @@ __all__ = [
31
32
  "resolve_mul_aspects",
32
33
  "AspectError",
33
34
  "AspectRefused",
35
+ "AspectClaimRefused",
34
36
  "AspectNotApplicable",
35
37
  ]
@@ -21,6 +21,7 @@ if TYPE_CHECKING:
21
21
 
22
22
 
23
23
  __all__ = [
24
+ "AspectClaimRefused",
24
25
  "AspectError",
25
26
  "AspectRefused",
26
27
  "AspectNotApplicable",
@@ -73,6 +74,48 @@ class AspectRefused(AspectError):
73
74
  super().__init__(f"Aspect refusal: {detail}")
74
75
 
75
76
 
77
+ class AspectClaimRefused(AspectError):
78
+ """A conversion's claimed aspect is not supported by the value.
79
+
80
+ The aspect peer of
81
+ :class:`~ucon.core.exceptions.KindClaimRefused`, and admitted by the same
82
+ rule: a claim may restate the aspect already carried in that family, or
83
+ weaken it to an ancestor whose ``join_policy`` permits generalizing across
84
+ that ancestor's children. It may not strengthen, nor exchange one sibling
85
+ for another.
86
+
87
+ This is the stratum where the distinction between combining and asserting
88
+ bites hardest. ``pressure_role`` carries ``JoinPolicy.LCA`` precisely so
89
+ that ``static + dynamic`` resolves to the family root — a total pressure,
90
+ role unspecified, which is what Bernoulli's ``P0 = P + ½ρV²`` produces.
91
+ Reporting a dynamic pressure *as* a static pressure is a different act, and
92
+ refusing it is not in tension with summing them: one asks what two
93
+ quantities make together, the other whether a value supports an assertion.
94
+
95
+ Attributes
96
+ ----------
97
+ current : Aspect
98
+ The aspect carried in the claimed aspect's family.
99
+ claimed : Aspect
100
+ The aspect the caller claimed.
101
+ unit : Unit | UnitProduct
102
+ The target unit.
103
+ """
104
+
105
+ def __init__(self, *, current, claimed, unit) -> None:
106
+ self.current = current
107
+ self.claimed = claimed
108
+ self.unit = unit
109
+ unit_name = getattr(unit, "name", None) or repr(unit)
110
+ super().__init__(
111
+ f"Cannot claim aspect {claimed.name!r} for a value carrying "
112
+ f"{current.name!r} on conversion to {unit_name!r}: the claim is not "
113
+ f"implied by the aspect already carried. A claim may restate it, or "
114
+ f"weaken it to an ancestor that permits generalizing; it may not "
115
+ f"strengthen it or exchange it for a sibling."
116
+ )
117
+
118
+
76
119
  class AspectNotApplicable(AspectError):
77
120
  """An aspect family does not apply to the quantity's kind.
78
121