ucon 2.3.0__tar.gz → 2.4.1__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.1}/CHANGELOG.md +271 -0
  2. {ucon-2.3.0/ucon.egg-info → ucon-2.4.1}/PKG-INFO +1 -1
  3. {ucon-2.3.0 → ucon-2.4.1}/ROADMAP.md +6 -5
  4. {ucon-2.3.0 → ucon-2.4.1}/ucon/__init__.py +4 -0
  5. {ucon-2.3.0 → ucon-2.4.1}/ucon/_cache.py +59 -0
  6. {ucon-2.3.0 → ucon-2.4.1}/ucon/aspects/__init__.py +2 -0
  7. {ucon-2.3.0 → ucon-2.4.1}/ucon/aspects/exceptions.py +43 -0
  8. {ucon-2.3.0 → ucon-2.4.1}/ucon/comprehensive.ucon.toml +291 -4
  9. {ucon-2.3.0 → ucon-2.4.1}/ucon/core/__init__.py +2 -0
  10. {ucon-2.3.0 → ucon-2.4.1}/ucon/core/_types.py +257 -19
  11. {ucon-2.3.0 → ucon-2.4.1}/ucon/core/exceptions.py +48 -0
  12. {ucon-2.3.0 → ucon-2.4.1}/ucon/formulas/exceptions.py +6 -2
  13. {ucon-2.3.0 → ucon-2.4.1}/ucon/formulas/registry.py +46 -23
  14. {ucon-2.3.0 → ucon-2.4.1}/ucon/formulas/types.py +24 -1
  15. {ucon-2.3.0 → ucon-2.4.1}/ucon/parsing/formulas.py +3 -0
  16. {ucon-2.3.0 → ucon-2.4.1}/ucon/serialization.py +13 -7
  17. {ucon-2.3.0 → ucon-2.4.1}/ucon/units.pyi +1 -0
  18. {ucon-2.3.0 → ucon-2.4.1/ucon.egg-info}/PKG-INFO +1 -1
  19. {ucon-2.3.0 → ucon-2.4.1}/ucon.egg-info/scm_file_list.json +8 -0
  20. ucon-2.4.1/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.1}/.github/workflows/downstream.yaml +0 -0
  23. {ucon-2.3.0 → ucon-2.4.1}/.github/workflows/publish.yaml +0 -0
  24. {ucon-2.3.0 → ucon-2.4.1}/.github/workflows/tests.yaml +0 -0
  25. {ucon-2.3.0 → ucon-2.4.1}/.gitignore +0 -0
  26. {ucon-2.3.0 → ucon-2.4.1}/.gitmodules +0 -0
  27. {ucon-2.3.0 → ucon-2.4.1}/LICENSE +0 -0
  28. {ucon-2.3.0 → ucon-2.4.1}/MANIFEST.in +0 -0
  29. {ucon-2.3.0 → ucon-2.4.1}/Makefile +0 -0
  30. {ucon-2.3.0 → ucon-2.4.1}/NOTICE +0 -0
  31. {ucon-2.3.0 → ucon-2.4.1}/README.md +0 -0
  32. {ucon-2.3.0 → ucon-2.4.1}/SECURITY.md +0 -0
  33. {ucon-2.3.0 → ucon-2.4.1}/SUPPORT.md +0 -0
  34. {ucon-2.3.0 → ucon-2.4.1}/mkdocs.yml +0 -0
  35. {ucon-2.3.0 → ucon-2.4.1}/netlify.toml +0 -0
  36. {ucon-2.3.0 → ucon-2.4.1}/pyproject.toml +0 -0
  37. {ucon-2.3.0 → ucon-2.4.1}/requirements.txt +0 -0
  38. {ucon-2.3.0 → ucon-2.4.1}/setup.cfg +0 -0
  39. {ucon-2.3.0 → ucon-2.4.1}/ucon/_active.py +0 -0
  40. {ucon-2.3.0 → ucon-2.4.1}/ucon/_algebra_cache.py +0 -0
  41. {ucon-2.3.0 → ucon-2.4.1}/ucon/_bootstrap.py +0 -0
  42. {ucon-2.3.0 → ucon-2.4.1}/ucon/aspects/forest.py +0 -0
  43. {ucon-2.3.0 → ucon-2.4.1}/ucon/aspects/resolution.py +0 -0
  44. {ucon-2.3.0 → ucon-2.4.1}/ucon/aspects/types.py +0 -0
  45. {ucon-2.3.0 → ucon-2.4.1}/ucon/basis/__init__.py +0 -0
  46. {ucon-2.3.0 → ucon-2.4.1}/ucon/basis/builtin.py +0 -0
  47. {ucon-2.3.0 → ucon-2.4.1}/ucon/basis/graph.py +0 -0
  48. {ucon-2.3.0 → ucon-2.4.1}/ucon/basis/ops.py +0 -0
  49. {ucon-2.3.0 → ucon-2.4.1}/ucon/basis/transforms.py +0 -0
  50. {ucon-2.3.0 → ucon-2.4.1}/ucon/basis/types.py +0 -0
  51. {ucon-2.3.0 → ucon-2.4.1}/ucon/basis/vector.py +0 -0
  52. {ucon-2.3.0 → ucon-2.4.1}/ucon/checking.py +0 -0
  53. {ucon-2.3.0 → ucon-2.4.1}/ucon/constants.py +0 -0
  54. {ucon-2.3.0 → ucon-2.4.1}/ucon/constants.pyi +0 -0
  55. {ucon-2.3.0 → ucon-2.4.1}/ucon/contexts.py +0 -0
  56. {ucon-2.3.0 → ucon-2.4.1}/ucon/conversion.py +0 -0
  57. {ucon-2.3.0 → ucon-2.4.1}/ucon/core/_parsing_graph.py +0 -0
  58. {ucon-2.3.0 → ucon-2.4.1}/ucon/dimension.py +0 -0
  59. {ucon-2.3.0 → ucon-2.4.1}/ucon/dimension.pyi +0 -0
  60. {ucon-2.3.0 → ucon-2.4.1}/ucon/expressions.py +0 -0
  61. {ucon-2.3.0 → ucon-2.4.1}/ucon/formulas/__init__.py +0 -0
  62. {ucon-2.3.0 → ucon-2.4.1}/ucon/graph.py +0 -0
  63. {ucon-2.3.0 → ucon-2.4.1}/ucon/integrations/__init__.py +0 -0
  64. {ucon-2.3.0 → ucon-2.4.1}/ucon/integrations/numpy.py +0 -0
  65. {ucon-2.3.0 → ucon-2.4.1}/ucon/integrations/pandas.py +0 -0
  66. {ucon-2.3.0 → ucon-2.4.1}/ucon/integrations/polars.py +0 -0
  67. {ucon-2.3.0 → ucon-2.4.1}/ucon/integrations/pydantic.py +0 -0
  68. {ucon-2.3.0 → ucon-2.4.1}/ucon/kinds/__init__.py +0 -0
  69. {ucon-2.3.0 → ucon-2.4.1}/ucon/kinds/exceptions.py +0 -0
  70. {ucon-2.3.0 → ucon-2.4.1}/ucon/kinds/lattice.py +0 -0
  71. {ucon-2.3.0 → ucon-2.4.1}/ucon/kinds/types.py +0 -0
  72. {ucon-2.3.0 → ucon-2.4.1}/ucon/maps.py +0 -0
  73. {ucon-2.3.0 → ucon-2.4.1}/ucon/packages.py +0 -0
  74. {ucon-2.3.0 → ucon-2.4.1}/ucon/parsing/__init__.py +0 -0
  75. {ucon-2.3.0 → ucon-2.4.1}/ucon/parsing/aspects.py +0 -0
  76. {ucon-2.3.0 → ucon-2.4.1}/ucon/parsing/dimensions.py +0 -0
  77. {ucon-2.3.0 → ucon-2.4.1}/ucon/parsing/kinds.py +0 -0
  78. {ucon-2.3.0 → ucon-2.4.1}/ucon/parsing/lexer.py +0 -0
  79. {ucon-2.3.0 → ucon-2.4.1}/ucon/parsing/namespaces.py +0 -0
  80. {ucon-2.3.0 → ucon-2.4.1}/ucon/parsing/quantity.py +0 -0
  81. {ucon-2.3.0 → ucon-2.4.1}/ucon/parsing/units.py +0 -0
  82. {ucon-2.3.0 → ucon-2.4.1}/ucon/quantity.py +0 -0
  83. {ucon-2.3.0 → ucon-2.4.1}/ucon/resolver.py +0 -0
  84. {ucon-2.3.0 → ucon-2.4.1}/ucon/system/__init__.py +0 -0
  85. {ucon-2.3.0 → ucon-2.4.1}/ucon/units.py +0 -0
  86. {ucon-2.3.0 → ucon-2.4.1}/ucon.egg-info/SOURCES.txt +0 -0
  87. {ucon-2.3.0 → ucon-2.4.1}/ucon.egg-info/dependency_links.txt +0 -0
  88. {ucon-2.3.0 → ucon-2.4.1}/ucon.egg-info/requires.txt +0 -0
  89. {ucon-2.3.0 → ucon-2.4.1}/ucon.egg-info/top_level.txt +0 -0
  90. {ucon-2.3.0 → ucon-2.4.1}/uv.lock +0 -0
@@ -7,6 +7,277 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+
11
+ ## [2.4.1] - 2026-11-22
12
+
13
+ ### Fixed
14
+
15
+ - **`UnitProduct.canonical_scale` participates in identity.** `__eq__` compared
16
+ only `factors`, so two products differing solely in their residual scale were
17
+ equal and hashed equal while yielding different magnitudes:
18
+
19
+ ```python
20
+ >>> UnitProduct({}, 1.0) == UnitProduct({}, 100.0)
21
+ True # magnitudes 1.0 and 100.0
22
+ ```
23
+
24
+ Equal objects that are not interchangeable, and unsafe as dict or cache keys.
25
+ Canonical-form invariant 4d permits a non-unit `canonical_scale` exactly when
26
+ `factors` is empty — which is the case identity missed. A product carrying a
27
+ residual also no longer equals a bare `Unit`, since a `Unit` has none.
28
+
29
+ The canonical-form invariant list is also corrected. #318 made a named
30
+ dimension-one factor survive a product but left 4a asserting "no
31
+ dimensionless (NONE-dim) factor survives", and narrowed 5 to the unity
32
+ without saying so — both stated the pre-#318 contract. Amended in place.
33
+
34
+ Not fixed, and filed as #387: invariant 4d (`canonical_scale == 1.0` whenever
35
+ `factors` is non-empty) and invariant 7 (the constructor seed composes) cannot
36
+ both hold for a seeded non-empty product. That is a question about what such a
37
+ product means, not about where to put a number.
38
+
39
+
40
+ ## [2.4.0] - 2026-11-21
41
+
42
+ ### Added
43
+
44
+ - **The angle kinds, `plane_angle` and `solid_angle` (#348, #344).** `radian`,
45
+ `degree`, `gradian`, `turn`, `arcminute` and `arcsecond` declare
46
+ `default_kind = "plane_angle"`; `steradian` and `square_degree` declare
47
+ `solid_angle`. They are **two independent roots**, not siblings: the kinds
48
+ carry different dimensions and `KindLattice` rejects a cross-dimension parent
49
+ edge (`CrossDimensionParent`), so `lca` reports `DisjointKinds`. This
50
+ forecloses SI's `sr = rad²`, a *power* relation no parent edge expresses; it
51
+ waits on composing kinds and survives meanwhile only as the hand-squared
52
+ `square_degree → steradian` factor. Nothing new refuses — `rad → sr`,
53
+ `rad/s → Hz` and `W/m² → W/sr` raise what they raised before — the kinds are
54
+ insurance for ADR 013, which dissolves the `angle` pseudo-dimension at 3.0.0.
55
+ Of the cross-domain cases this insures `xdom-018` alone: `rad/s` is a
56
+ `UnitProduct` carrying no kind (needs #342, #343), and `W/m² → W/sr` refuses
57
+ on genuine SI signatures (`M·T⁻³` vs `M·L²·T⁻³`) with no tag involved.
58
+
59
+
60
+ - **`Number.to(..., kind=)` — the kind the caller claims the result is (#373,
61
+ #342, #343).** Default `None` leaves the arrival rule in charge, so every
62
+ existing call is unchanged. A claim is admitted only if *implied* by the kind
63
+ already carried — it restates that kind, or weakens it to an ancestor whose
64
+ `join_policy` permits generalizing. Strengthening a kind or exchanging it for
65
+ a sibling raises the new `KindClaimRefused`; a cross-fiber claim is taken as
66
+ given; `KindNotFound` for an unresolvable name.
67
+
68
+ This reaches errors no property of a unit can. *"Report 100 MPa of tensile
69
+ stress as a hydrostatic pressure"* converts `MPa → MPa`; `0.5 MJ/m³ → kPa` is
70
+ a legitimate modulus of resilience while `500 kJ/m³ → kPa` *as a stress* is
71
+ not, and unclaimed the two are one conversion returning `<500.0 kPa>`. Only
72
+ the claim separates them — which is why the product-signature `default_kind`
73
+ plan on #342/#343 could not.
74
+
75
+ - **An `energy_density` kind**, declared and attached to nothing. A second root
76
+ on `Dimension(pressure)` rather than a child of `pressure`: same dimension and
77
+ same derivation — `(N·m)/m³` reduces to `N/m²` — but a different quantity, so
78
+ `lca` reports `DisjointKinds` against the pressure family. `J/m³` carries no
79
+ `default_kind` deliberately, for the reason above.
80
+
81
+ - **`Number.to(..., aspect=)`, and the first aspect families in the catalog
82
+ (#343).** Closes the last two must-fails of UnitSafe's pressure cluster —
83
+ *"report dynamic pressure as static pressure"* and *"equate atmospheric with
84
+ lithostatic pressure"* — taking it to 6 of 6. Both convert a unit to itself
85
+ **and** carry the same kind on both sides, so neither a unit nor a kind could
86
+ reach them: what differs is an adjective.
87
+
88
+ `pressure_role` (`static_pressure`, `dynamic_pressure`) and `pressure_origin`
89
+ (`atmospheric_pressure`, `lithostatic_pressure`, `hydrostatic_pressure`) are
90
+ declared on `join_policy = "lca"` with `applies_to` naming the pressure kinds,
91
+ so a quantity with no kind cannot carry them. They are **not** kinds, and the
92
+ reason is a must-pass row: `P0 = P + ½ρV²` is static plus dynamic, kinds refuse
93
+ addition across disjoint members, so kind-ifying these would make Bernoulli's
94
+ equation refuse. As aspects the sum lifts to the family root — a total
95
+ pressure, role unspecified — while the relabel still refuses, because a claim
96
+ is gated on implication rather than on the join (#376). One declaration serves
97
+ both operations.
98
+
99
+ Claims resolve family-wise, so a value may carry a role and an origin at once
100
+ and a claim about one leaves the other alone. Unknown names propagate the
101
+ forest's own `AspectError`.
102
+
103
+ - **The graph cache now carries the aspect forest.** `ucon/_cache.py` serialized
104
+ the kind lattice and silently dropped aspects, so a declared forest existed
105
+ only under `UCON_NO_CACHE=1` — latent until this release, since no aspects were
106
+ declared. Encode, decode and a parent-first builder now mirror the kinds pass.
107
+
108
+ - **The surface power density kinds: `irradiance`, `radiative_forcing` and
109
+ `heat_flux` (#344).** Three ISO 80000-7 / IPCC quantities share `W/m²`, and
110
+ UnitSafe names the confusion directly — *"equate radiative forcing with heat
111
+ flux as physically identical quantities"* and *"report solar irradiance as
112
+ radiative forcing"*. Disjoint siblings under a refusing
113
+ `surface_power_density` root, the idiom the power, pressure and frequency
114
+ clusters already use, so a crossing refuses while every same-kind conversion
115
+ in the cluster still admits. Nothing attaches them: `W/m²` is a `UnitProduct`
116
+ and the unit genuinely does not say which quantity it carries, so the caller
117
+ states it with `Number.to(..., kind=)`.
118
+
119
+ This is the first kind in the catalog whose dimension is declared as an
120
+ **expression** (`"mass/time^3"`) rather than a registered name, since `W/m²`
121
+ reduces to M·T⁻³ and SI does not name it.
122
+
123
+ - **Clearance vs blood flow, and hydraulic head vs distance (#344).** Two more
124
+ of UnitSafe's unclustered `koq_mismatch` must-fails. `volumetric_flow_rate`
125
+ roots `clearance` and `blood_flow` (L³/T); `length_quantity` roots `distance`
126
+ and `hydraulic_head`. Both pairs fail the add-test — a total clearance is the
127
+ sum of *clearances*, never of a clearance and a flow, and a head and a
128
+ distance do not sum at all — so they are kinds rather than aspects.
129
+
130
+ Nothing attaches them. `meter` carries no `default_kind` and must not: most
131
+ lengths are plain distances, and tagging the unit would force a claim onto
132
+ every one of them. Every clearance must-pass in the benchmark is a same-kind
133
+ unit conversion and still admits.
134
+
135
+ `gfr` is **deliberately not** declared as a sibling of `clearance`: the
136
+ benchmark keys its GFR must-passes as `clearance`, so splitting them would
137
+ refuse a claim the dataset makes. Recorded as a test so the omission reads as
138
+ a decision rather than an oversight.
139
+
140
+ - **Weight basis and administration route as aspects (#344).** Two more
141
+ unclustered `koq_mismatch` must-fails: *"treat ideal body weight and actual
142
+ body weight as identical for dosing"* and *"equate oral morphine equivalent
143
+ dose with IV morphine equivalent dose"*. `body_weight_basis`
144
+ (`ideal_body_weight`, `actual_body_weight`) and `administration_route`
145
+ (`oral_route`, `intravenous_route`), both on `join_policy = "lca"`, with
146
+ `body_mass` and `drug_dose` declared as the kinds they attach to since `mass`
147
+ had none.
148
+
149
+ Aspects rather than kinds because the pair **sums**: a total opioid burden is
150
+ the sum across routes, which is the entire purpose of a morphine-equivalent
151
+ dose. `30 mg` oral plus `10 mg` IV now answers `<40 mg [drug_dose]
152
+ #administration_route>` — total dose, route unspecified — while relabelling
153
+ one route as the other refuses. Kind-ifying them would have broken the sum.
154
+
155
+ Nothing attaches them: a bare `kg` is neither a dose nor a body weight, and
156
+ still carries no kind or aspect.
157
+
158
+ - **Canonical `one`: the unity unit is named, and `"1"` resolves to it (#307).**
159
+ The catalog already declared a `Dimension(none)` unity unit, but with
160
+ `name = ""` — undiscoverable, so `"1"`, `"dimensionless"` and `"unitless"` had
161
+ been given to `fraction`, which carries `Dimension(ratio)`. The obvious
162
+ dimensionless literal therefore landed on the one fiber where a
163
+ `Dimension(none)` kind cannot attach, and
164
+ `Number(20, parse_unit('1'), kind=radiation_weighting_factor)` raised
165
+ `KindDimensionMismatch`. The unit is now `units.one` and those three aliases
166
+ resolve to it, so `Gy * w_R` answers `<40 Gy [dose_equivalent]>` with the
167
+ literal a caller would write.
168
+
169
+ `""` is kept as an alias deliberately: dimensionless *constants* are carried
170
+ by the empty-string unit name. `fraction` keeps `frac` and keeps
171
+ `Dimension(ratio)` — emptying the ratio fiber into `Scale` is 3.0.0's work.
172
+
173
+ - **Division dispatches kinds through its own table (#381).** `/` consulted the
174
+ formula registry with the same key `*` uses, so a formula declared for a
175
+ *product* answered the *quotient* — `Gy * w_R` is a dose equivalent and
176
+ `Gy / w_R` claimed to be one too. v2.3.0's #352 shipped the refusal half of
177
+ this (`Gy / Sv` stopped cancelling to `1.0`); this is the dispatch half.
178
+
179
+ **Operation is now part of a formula's identity.** `KindFormula` gains an
180
+ `operation` field — `Operation.MULTIPLY` (default) or `Operation.DIVIDE` — and
181
+ every registry index is keyed on it, so all four lookup tiers and the
182
+ collision guard became operation-aware together. `commutative` is unchanged
183
+ and remains a different axis: operand *order within* one operation.
184
+
185
+ This widens #347's guard, which read a product and a quotient over one input
186
+ tuple as a single signature — so the inverse declaration ADR 013 §4 names as
187
+ the route to a quotient kind was unregisterable. Both now register, each
188
+ answers only its own operation, and a collision *within* an operation still
189
+ refuses. Additive: formulas declared before this default to `MULTIPLY`.
190
+
191
+ - **A dimension-one unit that names a quantity survives a product (#318).**
192
+ `UnitProduct` dropped every `Dimension(none)` factor at construction, keeping
193
+ its *scale* and discarding the unit — so the scale survived without the thing
194
+ it scaled, and a money-rate unit could not be constructed, kinded, or carry a
195
+ declaration. `USD/kWh` rendered as `1/(kW·h)` and `100 kWh × 0.12 USD/kWh`
196
+ answered `<12.0>`; they are now `<UnitProduct USD/(kW·h)>` and `<12.0 USD>`.
197
+
198
+ The discriminator is **identity, not name**: #307 named the canonical unity
199
+ `one` in this same release, so "anonymous" stopped being a usable proxy for
200
+ "is the identity" — a first cut rendered `one * kg` as `one·kg`. Folding keys
201
+ on the unity itself, so `one * kg` is `kg` while `USD/h` keeps its symbol.
202
+
203
+ Four sites carried the same "dimensionless means unity" assumption: the
204
+ reduction path, both construction fast paths, and `Unit.shorthand`, which
205
+ blanked every `Dimension(none)` unit — making `USD` invisible on a bare
206
+ `Number` while a one-factor `UnitProduct` of the same unit rendered it.
207
+
208
+ This reverses a stated canonical-form invariant: "no dimensionless factor
209
+ survives" becomes "no *unity* factor survives". Six tests encoding the old
210
+ form are updated, each gaining a companion for the new rule. Magnitudes are
211
+ unchanged — a scaled symbol carries its scale on the surviving factor, a
212
+ scaled unity still folds into `canonical_scale`. Unblocks the money-rate
213
+ pattern ADR 011 reserves for fee schedules: `500 MWh × 48 USD/MWh` now
214
+ answers `<24000.0 USD [usd]>` in both operand orders, pinned as a test.
215
+
216
+ - **A kind on an unnamed derived dimension no longer breaks the TOML
217
+ round-trip.** `Dimension` renders a vector with no registered name as
218
+ `derived(mass/time^3)`, which is a *rendering*, not an identifier —
219
+ `parse_dimension` rejects it with *"Unknown dimension identifier 'derived'"*.
220
+ Both `_serialize_kind` and `_dimension_to_expression` treated it as a name and
221
+ emitted it verbatim, so any such kind failed to reload. The expression is now
222
+ rebuilt from the vector (`M/T^3`) whenever the name is a `derived(...)`
223
+ rendering. Latent until now, because no kind was declared on an unnamed
224
+ dimension.
225
+
226
+ ### Documentation
227
+
228
+ - **Three roadmap corrections, all scheduling rather than scope.**
229
+
230
+ *`**` moves from v2.3.1 to v3.2.0.* The deferred-behaviour suite named the
231
+ contradiction: the bullet's own "Blocked by" line cites `DerivedKind` and a `**`
232
+ dispatch row as **v3.2.0** work, while "Fixed in" claimed v2.3.1 — three minor
233
+ releases ahead of its prerequisite. v3.2.0 already lists the dispatch row, so the
234
+ bullet now sits beside it.
235
+
236
+ The test docstring also records *why* it matters, since `kind is None` reads as
237
+ harmless: `**` launders the kind stratum.
238
+ `Gy[absorbed_dose] + Sv[dose_equivalent]` raises `JoinRefused`, while
239
+ `(Gy)**2 + (Sv)**2` answers `<13.0 Gy²>` — squaring two incommensurable
240
+ quantities makes them addable. And `None` is a false claim, not a missing one:
241
+ `Gy²` has a kind and lacks a *name*, as `m × m` is `derived(length^2)`.
242
+
243
+ *v2.6.0 and v3.0.0 decouple from the currency basis component (#292).* The
244
+ basis-component design rested on currency needing a guard that holds with no kind
245
+ lattice installed; #383 made that guard structural, since base-form signatures
246
+ carry the currency symbol. The v3.0.0 row now states the basis rename and shim
247
+ retirement on their own footing — `information` has held slot 8 since before
248
+ currency was proposed — with the slot-9 fold contingent on #292's review, and
249
+ v2.6.0 no longer asserts 3.0.0-prerequisite status.
250
+
251
+
252
+
253
+ - **A regression suite pinning the deferred behaviours**
254
+ (`tests/ucon/test_deferred_behaviours.py`). Eleven assertions record what
255
+ ucon does *today* where what it does is known-wrong, filed, and blocked
256
+ behind a release that has not happened: the `nines` scalar/additive
257
+ contradiction (#341), same-unit addition on points and levels (#340's
258
+ explicitly out-of-scope half, ADR 009 §3), `lm → cd` (#346), the
259
+ dimensionless kinds that cannot attach to `percent`/`fraction` (#344),
260
+ `rad² ↔ sr` and the idempotent tag algebra (#348), `Number` being
261
+ unhashable (#353, blocked on #362), `**` dropping the kind, and the
262
+ torque/energy and pressure/energy-density clusters converting freely
263
+ (#342, #343). Each test's docstring names the issue, the blocker and the
264
+ release that closes it, so changing one of these behaviours fails CI and
265
+ points the reader at the filed cause instead of inviting a re-diagnosis.
266
+ The file is not a specification of intent; it is the companion to
267
+ `tests/ucon/core/test_operator_stratum_grid.py` for behaviours that are
268
+ not cells of that grid.
269
+
270
+
271
+ - **The v2.4.0 roadmap row records that #342 and #343 moved to #373.** Both issues
272
+ prescribed `default_kind` on product signatures. Measurement against UnitSafe says
273
+ otherwise: four of cluster 7's six must-fails convert a unit to itself
274
+ (`MPa → MPa`), which no unit-keyed tag can reach, and tagging `J/m³` with
275
+ `energy_density` would fail the must-pass `0.5 MJ/m³ → kPa` — the same operation as
276
+ the must-fail `500 kJ/m³ → kPa`, differing only in the claim. A `kind=` argument on
277
+ `Number.to()` (#373) clears 12 of the 14 must-fails against the lattice as it
278
+ stands, since `join(torque, energy)` already refuses while `join(torque, torque)`
279
+ admits. Both issues keep their diagnoses and carry a comment pointing at #373.
280
+
10
281
  ## [2.3.0] - 2026-10-20
11
282
 
12
283
  ### Added
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ucon
3
- Version: 2.3.0
3
+ Version: 2.4.1
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,13 @@ 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.2. *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 | **`UnitProduct` identity includes the residual scale** — `__eq__` compared only `factors`, so two products differing solely in `canonical_scale` were equal and hashed equal while yielding magnitudes 100× apart, breaking the hash contract (#388). Invariant 4d permits a non-unity residual exactly when `factors` is empty, which is the case identity missed; a product carrying one no longer equals a bare `Unit`. The invariant list is corrected in place — #318 left 4a asserting "no dimensionless factor survives" and narrowed 5 without saying so, both stating the pre-#318 contract. **Correcting this row's earlier claim that the defect is reachable from ordinary code: measured, it is not.** No catalog unit carries a non-unity residual and none of 40,000 pairwise quotients produces one — cross-scale factors survive separately under invariant 6, so `mcg/kg` leaves its ratio in `fold_scale()`. Only a caller-supplied constructor seed sets the field, which is #387. The release therefore closes a hazard on a field nothing reachable populates. *UnitSafe: none.* | Complete |
52
+ | v2.4.2 | **`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)`. *UnitSafe: none — `Number` arithmetic routes through `UnitProduct`, which does not fold scales, so no benchmark path is affected.* | Planned |
53
+ | 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 |
54
+ | 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
55
  | 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.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
57
  | 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
58
  | 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
59
  | *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