ucon 2.1.6__tar.gz → 2.2.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.1.6 → ucon-2.2.0}/.gitignore +16 -0
- {ucon-2.1.6 → ucon-2.2.0}/CHANGELOG.md +161 -0
- {ucon-2.1.6/ucon.egg-info → ucon-2.2.0}/PKG-INFO +1 -1
- {ucon-2.1.6 → ucon-2.2.0}/ROADMAP.md +6 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/__init__.py +10 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/_cache.py +0 -7
- ucon-2.2.0/ucon/aspects/__init__.py +35 -0
- ucon-2.2.0/ucon/aspects/exceptions.py +92 -0
- ucon-2.2.0/ucon/aspects/forest.py +179 -0
- ucon-2.2.0/ucon/aspects/resolution.py +144 -0
- ucon-2.2.0/ucon/aspects/types.py +103 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/checking.py +21 -5
- {ucon-2.1.6 → ucon-2.2.0}/ucon/comprehensive.ucon.toml +60 -3
- {ucon-2.1.6 → ucon-2.2.0}/ucon/conversion.py +31 -1
- {ucon-2.1.6 → ucon-2.2.0}/ucon/core/_types.py +119 -28
- {ucon-2.1.6 → ucon-2.2.0}/ucon/dimension.py +16 -1
- {ucon-2.1.6 → ucon-2.2.0}/ucon/formulas/__init__.py +5 -8
- {ucon-2.1.6 → ucon-2.2.0}/ucon/formulas/registry.py +15 -44
- {ucon-2.1.6 → ucon-2.2.0}/ucon/formulas/types.py +1 -55
- {ucon-2.1.6 → ucon-2.2.0}/ucon/kinds/exceptions.py +32 -3
- {ucon-2.1.6 → ucon-2.2.0}/ucon/kinds/lattice.py +5 -1
- {ucon-2.1.6 → ucon-2.2.0}/ucon/packages.py +24 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/parsing/__init__.py +10 -3
- ucon-2.2.0/ucon/parsing/aspects.py +189 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/parsing/formulas.py +2 -23
- ucon-2.2.0/ucon/parsing/namespaces.py +144 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/serialization.py +73 -8
- {ucon-2.1.6 → ucon-2.2.0}/ucon/system/__init__.py +8 -8
- {ucon-2.1.6 → ucon-2.2.0/ucon.egg-info}/PKG-INFO +1 -1
- {ucon-2.1.6 → ucon-2.2.0}/ucon.egg-info/SOURCES.txt +5 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon.egg-info/scm_file_list.json +22 -5
- ucon-2.2.0/ucon.egg-info/scm_version.json +8 -0
- ucon-2.1.6/ucon/aspects/__init__.py +0 -38
- ucon-2.1.6/ucon/aspects/types.py +0 -154
- ucon-2.1.6/ucon.egg-info/scm_version.json +0 -8
- {ucon-2.1.6 → ucon-2.2.0}/.github/workflows/downstream.yaml +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/.github/workflows/publish.yaml +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/.github/workflows/tests.yaml +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/.gitmodules +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/LICENSE +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/MANIFEST.in +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/Makefile +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/NOTICE +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/README.md +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/SECURITY.md +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/SUPPORT.md +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/mkdocs.yml +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/netlify.toml +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/pyproject.toml +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/requirements.txt +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/setup.cfg +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/_active.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/_algebra_cache.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/_bootstrap.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/basis/__init__.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/basis/builtin.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/basis/graph.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/basis/ops.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/basis/transforms.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/basis/types.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/basis/vector.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/constants.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/constants.pyi +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/contexts.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/core/__init__.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/core/_parsing_graph.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/core/exceptions.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/dimension.pyi +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/expressions.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/formulas/exceptions.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/graph.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/integrations/__init__.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/integrations/numpy.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/integrations/pandas.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/integrations/polars.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/integrations/pydantic.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/kinds/__init__.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/kinds/types.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/maps.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/parsing/dimensions.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/parsing/kinds.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/parsing/lexer.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/parsing/quantity.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/parsing/units.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/quantity.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/resolver.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/units.py +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon/units.pyi +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon.egg-info/dependency_links.txt +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon.egg-info/requires.txt +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/ucon.egg-info/top_level.txt +0 -0
- {ucon-2.1.6 → ucon-2.2.0}/uv.lock +0 -0
|
@@ -133,3 +133,19 @@ dmypy.json
|
|
|
133
133
|
|
|
134
134
|
# ucon graph cache (generated binary, not source)
|
|
135
135
|
*.ucon.cache
|
|
136
|
+
|
|
137
|
+
# Internal working notes: upper-cased prefixes are machine-local by convention
|
|
138
|
+
# (enumerated because ignore matching is case-insensitive on this platform)
|
|
139
|
+
docs/internal/ADR_*
|
|
140
|
+
docs/internal/ARCHITECTURE_*
|
|
141
|
+
docs/internal/CASE_STUDIES_*
|
|
142
|
+
docs/internal/DESIGN_*
|
|
143
|
+
docs/internal/FEEDBACK_*
|
|
144
|
+
docs/internal/IMPLEMENTATION_PLAN_*
|
|
145
|
+
docs/internal/ISSUE_REPORT_*
|
|
146
|
+
docs/internal/PROPOSAL_*
|
|
147
|
+
docs/internal/RELEASE_PLAN_*
|
|
148
|
+
docs/internal/SUMMARY*
|
|
149
|
+
docs/internal/VETTED_*
|
|
150
|
+
docs/internal/tickets/
|
|
151
|
+
docs/internal/evidence/
|
|
@@ -7,6 +7,160 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [2.2.0] - 2026-09-12
|
|
11
|
+
|
|
12
|
+
### Removed
|
|
13
|
+
|
|
14
|
+
- **The flat aspect model, outright.** `AspectSet`, `AspectJoinPolicy`,
|
|
15
|
+
`join_aspects`, `AspectRule`, and the formula aspect-projection
|
|
16
|
+
machinery (`KindFormula.aspect_rules`, `project_aspects`, the
|
|
17
|
+
aspect-carrying `FormulaRegistry.apply` signature) are deleted — no
|
|
18
|
+
deprecation shim. None of these names was ever exported through
|
|
19
|
+
`ucon/__init__.py`, and an unkeyed set cannot distinguish conflict
|
|
20
|
+
from absence (the defect the aspect stratum exists to fix).
|
|
21
|
+
`FormulaRegistry.apply` now takes kinds only and returns
|
|
22
|
+
`(formula, output_kind, match_kind)`: formulas do kind work; aspect
|
|
23
|
+
propagation belongs to the stratum's carry rule.
|
|
24
|
+
|
|
25
|
+
### Added
|
|
26
|
+
|
|
27
|
+
- **Family-wise aspect resolution in Number arithmetic.** Addition and
|
|
28
|
+
subtraction resolve per family: equal positions carry, differing
|
|
29
|
+
positions join at their LCA under the ancestor's policy (`refuse`
|
|
30
|
+
raises `AspectRefused`), and partial presence consults the ambient
|
|
31
|
+
strict bit — strict refuses, permissive inherits with a warning.
|
|
32
|
+
Multiplication and division follow the carry rule: a factor's
|
|
33
|
+
provenance rides the product even past kind degradation, and partial
|
|
34
|
+
presence carries per the family's `multiplication_policy`. No path
|
|
35
|
+
drops a position silently. Single-operand operations (`.to()`,
|
|
36
|
+
scalar `*`/`/`, `**`, `simplify()`, `to_base()`, `Ratio.evaluate()`,
|
|
37
|
+
`UnitSystem.adopt()`, `Bridge.apply()`) thread aspects unchanged.
|
|
38
|
+
`resolve_add_aspects` / `resolve_mul_aspects` ship via
|
|
39
|
+
`ucon.aspects`.
|
|
40
|
+
- **D3 namespacing: full qualification + the `namespace` rewriter.**
|
|
41
|
+
(#285) Package-declared kinds and aspects carry `pkg:name` — aliases
|
|
42
|
+
included, since an unqualified alias collides across packages exactly
|
|
43
|
+
the way a name does. The ergonomics are recovered by
|
|
44
|
+
`rewrite_namespace` (via `ucon.parsing`): `namespace = "pkg"` in
|
|
45
|
+
`[package]` qualifies every unprefixed declared name and
|
|
46
|
+
kind-reference (kinds, aspects, formula inputs/outputs, constant
|
|
47
|
+
kinds); `@name` escapes to root; `pkg:name` spellings pass through
|
|
48
|
+
as explicit cross-package references. The rewrite is a pure
|
|
49
|
+
dict→dict transformation that consults nothing loaded (it cannot
|
|
50
|
+
shadow) and consumes the `namespace` key (it is idempotent, and its
|
|
51
|
+
output equals the hand-qualified file). Applied automatically by
|
|
52
|
+
`load_package` and `from_toml`.
|
|
53
|
+
- **Packages can declare aspects.** `[[aspects]]` sections in a
|
|
54
|
+
package TOML parse into `UnitPackage.aspects`;
|
|
55
|
+
`ConversionGraph.with_package` merges them into the graph's forest.
|
|
56
|
+
No silent override: a same-named distinct aspect raises
|
|
57
|
+
`AspectError` at composition — under qualification, collisions
|
|
58
|
+
indicate a missing namespace, not a tie to break.
|
|
59
|
+
- **Cross-fiber `NameCollision` now diagnoses itself.** (#285) The
|
|
60
|
+
flat kind-name index stays in 2.x — coexistence of same-named kinds
|
|
61
|
+
in different fibers under name-only `Kind.__eq__` would silently
|
|
62
|
+
conflate them in lattice walks, and extending equality is a breaking
|
|
63
|
+
change reserved for a major. When a collision spans fibers, the
|
|
64
|
+
error now names both dimensions and points at `pkg:name`
|
|
65
|
+
qualification as the supported resolution.
|
|
66
|
+
- **`[[aspects]]` TOML and serialization round-trip.**
|
|
67
|
+
`parse_aspects_payload` / `load_aspects_file` (via `ucon.parsing`)
|
|
68
|
+
build an `AspectForest` from declarations — order-independent parent
|
|
69
|
+
resolution, typed errors (schema faults raise `ValueError`;
|
|
70
|
+
duplicates, orphan or cyclic parents, and root-only fields on child
|
|
71
|
+
entries raise `AspectError` — never a Kind-named exception).
|
|
72
|
+
`to_toml(..., aspects=...)` emits `[[aspects]]` sections
|
|
73
|
+
(defaults omitted, parents before children) with fallback to the
|
|
74
|
+
graph's loaded forest; `from_toml` restores it. No builtin aspects:
|
|
75
|
+
core ships mechanism, domains ship vocabulary.
|
|
76
|
+
- **`Number.aspects`** — additive `frozenset[Aspect]` field, default
|
|
77
|
+
empty; `Number.kind` and every existing idiom untouched. `applies_to`
|
|
78
|
+
is enforced at construction (the one sanctioned kind-read in the
|
|
79
|
+
aspect layer): a restricted family refuses attachment to the wrong
|
|
80
|
+
kind — or to an unkinded Number — at the moment the claim is made;
|
|
81
|
+
wildcard (`"*"`) and unrestricted families attach kind-independently.
|
|
82
|
+
`repr` gains sorted `#aspect` tokens.
|
|
83
|
+
- **`AspectForest`** — family-grouped aspect trees, each family running
|
|
84
|
+
on a private, mirrored kind-lattice engine (the engine untouched;
|
|
85
|
+
the vetted isomorphism preserved by construction). Root-as-⊤ turns
|
|
86
|
+
would-be disjoint-subtree crashes into typed `AspectRefused`
|
|
87
|
+
verdicts; the rewrap boundary guarantees no Kind-named exception
|
|
88
|
+
ever surfaces from an aspect declaration.
|
|
89
|
+
- **The aspect data model.** `Aspect` — one node type, peer of `Kind`:
|
|
90
|
+
trees whose root *is* the family and its ⊤; `join_policy` defaults to
|
|
91
|
+
refuse; root-only `applies_to` and `multiplication_policy` (`carry`).
|
|
92
|
+
Exception surface mirroring the kind layer: `AspectError`,
|
|
93
|
+
`AspectRefused` (family conflict and partial-under-strict, one type,
|
|
94
|
+
warrant-shaped payload), `AspectNotApplicable`. First public aspect
|
|
95
|
+
exports: `Aspect`, `AspectError`, `AspectRefused`,
|
|
96
|
+
`AspectNotApplicable` via `ucon/__init__.py`. (#296, ADR 008 —
|
|
97
|
+
resolution, `Number.aspects`, and TOML arrive in the same release.)
|
|
98
|
+
|
|
99
|
+
### Deprecated
|
|
100
|
+
|
|
101
|
+
- **Pseudo-dimensions.** `Dimension.pseudo(...)` now emits
|
|
102
|
+
`PendingDeprecationWarning` citing the migration path (declare a
|
|
103
|
+
`Kind` over the dimensionless dimension — kinds carry the semantic
|
|
104
|
+
isolation pseudo-dimensions approximate) and the removal version
|
|
105
|
+
(3.0.0, together with the TOML `tag` schema). The builtin four
|
|
106
|
+
(`angle`, `solid_angle`, `ratio`, `count`) stay silent at import
|
|
107
|
+
and retire with the schema.
|
|
108
|
+
|
|
109
|
+
### Changed
|
|
110
|
+
|
|
111
|
+
- **Test suite: function-local imports hoisted to module top.** ~1,250
|
|
112
|
+
local import lines across 40 test files move to module scope per the
|
|
113
|
+
no-local-imports rule; `integrations/` keeps its module-level
|
|
114
|
+
try/except optional-dependency guards; two genuinely distinct private
|
|
115
|
+
helpers (`_get_numpy` in `core._types` vs `maps`) hoist under aliases.
|
|
116
|
+
No behavior change (suite results identical before/after).
|
|
117
|
+
- **v2.2.0 delivers the aspect stratum; package infrastructure moves
|
|
118
|
+
to v2.3.0.** Release reassignment per
|
|
119
|
+
[decisions/008](docs/internal/decisions/008-aspect-stratum.md) and
|
|
120
|
+
[ROADMAP.md](ROADMAP.md). The never-exported flat `AspectSet` model
|
|
121
|
+
is removed outright with the stratum's arrival in this release (it
|
|
122
|
+
was never
|
|
123
|
+
public: no aspect symbol has ever shipped through
|
|
124
|
+
`ucon/__init__.py`).
|
|
125
|
+
|
|
126
|
+
### Documentation
|
|
127
|
+
|
|
128
|
+
- **Internal design records landed in-repo.** ADRs 008 (aspect
|
|
129
|
+
stratum), 009 (Turnstile), 010 (chart nomenclature), and 011
|
|
130
|
+
(currency via kinds and rate contexts) join the
|
|
131
|
+
[`docs/internal/decisions/`](docs/internal/decisions/) series; the operator-flow decision-tables
|
|
132
|
+
design and the Turnstile implementation brief land under
|
|
133
|
+
[`docs/internal/proposals/`](docs/internal/proposals/) with supersession notes. The
|
|
134
|
+
how-ucon-achieves-type-safety explainer is rewritten against v2.1.x
|
|
135
|
+
reality: the kind lattice joins the enforcement-layer story,
|
|
136
|
+
fictional pre-v2 API is corrected to the conversion-graph surface,
|
|
137
|
+
and the not-yet-caught boundary (numeral-scheme safety, scheduled
|
|
138
|
+
per ADR 009) is stated honestly.
|
|
139
|
+
|
|
140
|
+
## [2.1.7] - 2026-09-09
|
|
141
|
+
|
|
142
|
+
### Fixed
|
|
143
|
+
|
|
144
|
+
- **Mechanical CGS units now carry exact SI-factored `base_form`s.**
|
|
145
|
+
(#283) `base_form is None` conflated three unrelated causes: chart
|
|
146
|
+
structure (celsius, dB — no factorization exists), basis scoping
|
|
147
|
+
(dyne — an exact factorization exists but was never recorded), and
|
|
148
|
+
pseudo-dimensions (degree). Eight purely multiplicative CGS-mechanical
|
|
149
|
+
units — dyne, erg, poise, stokes, barye, galileo, kayser, langley —
|
|
150
|
+
are now populated with their exact SI equivalents, so `None` recovers
|
|
151
|
+
meaning: either no factorization exists, or (electromagnetic CGS:
|
|
152
|
+
gauss, maxwell, statvolt, …) the factorization is dimensionally
|
|
153
|
+
ill-typed across bases and conversion routes through `RebasedUnit`
|
|
154
|
+
edges. The `BaseForm` contract docstring now states all of this
|
|
155
|
+
explicitly, including: never infer chart/scale structure from
|
|
156
|
+
`base_form is None`. `enforce_dimensions` cross-basis coercion still
|
|
157
|
+
lands on named SI units (joule, pascal·second) — the graph route is
|
|
158
|
+
preferred and the algebraic decomposition is a fallback — and every
|
|
159
|
+
`base_form` consumer (base-form conversion shortcut, composite-path
|
|
160
|
+
sibling links from #280) now covers these CGS units.
|
|
161
|
+
|
|
162
|
+
## [2.1.6] - 2026-09-09
|
|
163
|
+
|
|
10
164
|
### Fixed
|
|
11
165
|
|
|
12
166
|
- **Re-adding an identical `Kind` object is now an idempotent no-op.**
|
|
@@ -19,6 +173,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
19
173
|
Re-registering the identical object now returns quietly; a *distinct*
|
|
20
174
|
object with the same name still raises `NameCollision`, and
|
|
21
175
|
`AliasCollision` is reachable only when an alias is actually involved.
|
|
176
|
+
Relatedly, the kinds parser now rejects duplicate `[[kinds]]` names
|
|
177
|
+
itself (`NameCollision`) — that rejection previously happened only by
|
|
178
|
+
accident, via the self-referential lattice collision this release
|
|
179
|
+
fixes. *(Entry added retroactively with the 2.1.7 re-sectioning.)*
|
|
22
180
|
|
|
23
181
|
## [2.1.5] - 2026-09-09
|
|
24
182
|
|
|
@@ -2648,6 +2806,9 @@ Deprecated surfaces are scheduled for removal in v2.0.
|
|
|
2648
2806
|
- Initial commit
|
|
2649
2807
|
|
|
2650
2808
|
<!-- Links -->
|
|
2809
|
+
[2.2.0]: https://github.com/withtwoemms/ucon/compare/2.1.7...2.2.0
|
|
2810
|
+
[2.1.7]: https://github.com/withtwoemms/ucon/compare/2.1.6...2.1.7
|
|
2811
|
+
[2.1.6]: https://github.com/withtwoemms/ucon/compare/2.1.5...2.1.6
|
|
2651
2812
|
[2.1.5]: https://github.com/withtwoemms/ucon/compare/2.1.4...2.1.5
|
|
2652
2813
|
[2.1.4]: https://github.com/withtwoemms/ucon/compare/2.1.3...2.1.4
|
|
2653
2814
|
[2.1.3]: https://github.com/withtwoemms/ucon/compare/2.1.2...2.1.3
|
|
@@ -43,6 +43,12 @@ This roadmap tracks **major milestones** on the path to v2. For incremental upda
|
|
|
43
43
|
| v1.11.0 | **Eager system initialization.** `ucon/__init__.py` pushes a `UnitSystem` onto the `_active` ContextVar at import time, so the active-system tier in `get_default_graph()` is always hit. The module-level `_default_graph` singleton becomes dead code; `set_default_graph`, `reset_default_graph`, and `UnitSystem.from_globals` are deprecated. | Complete |
|
|
44
44
|
| v1.12.0 | **Cycle-break completion — structural rather than runtime.** The `_active` ContextVar relocates to a true Layer-0 leaf (`ucon._active`) with zero intra-ucon imports; `AlgebraCache` moves to `ucon._algebra_cache`; the transitional `_resolve_unit_impl` dependency-injection scaffold and the `constants._constants_cache` cross-module attribute assignment both retire. A static AST audit (`test_no_cross_module_injection.py`) guards against future regressions. No public API change. | Complete |
|
|
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
|
+
| 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
|
+
| 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`). | Planned |
|
|
48
|
+
| v2.3.0 | **Package infrastructure** — `[[contexts]]` in TOML, `PolynomialMap` with branch inverses, declared `Unit.chart` ([decisions/010](docs/internal/decisions/010-chart-nomenclature.md)), `default_kind`. | Planned |
|
|
49
|
+
| v2.4.0 | **Array stratum parity** — `NumberArray` receives the kind and aspect strata (#297, #298): array-level `kind` and `aspects` fields mirroring the shared-`unit` design, scalar-resolver reuse (one resolution per array op), extraction stamping so `arr[i]` satisfies every `Number` invariant, integrations round-trip. | Planned |
|
|
50
|
+
| v3.0.0 | **Lean structural major** — pseudo-dimension retirement (TOML schema), `Number` frozen, `Unit`/`UnitProduct` identity unification, deprecation removals. The breaks, and only the breaks. | Planned |
|
|
51
|
+
| v3.1.0 | **The Turnstile** — per [decisions/009](docs/internal/decisions/009-turnstile.md): four-stratum arithmetic dispatch (dimension, chart, kind, aspect), derived point/displacement, cyclic/ordinal kind flags, lazy warrants via `explain()`. New refusals on previously-wrong paths are fixes. | Planned |
|
|
46
52
|
|
|
47
53
|
---
|
|
48
54
|
|
|
@@ -104,6 +104,12 @@ from ucon.system import (
|
|
|
104
104
|
use,
|
|
105
105
|
)
|
|
106
106
|
from ucon.formulas import FormulaRegistry
|
|
107
|
+
from ucon.aspects import (
|
|
108
|
+
Aspect,
|
|
109
|
+
AspectError,
|
|
110
|
+
AspectNotApplicable,
|
|
111
|
+
AspectRefused,
|
|
112
|
+
)
|
|
107
113
|
from ucon.kinds import Kind, KindLattice
|
|
108
114
|
from ucon.dimension import (
|
|
109
115
|
Dimension,
|
|
@@ -185,6 +191,10 @@ __all__ = [
|
|
|
185
191
|
'ExtendConflict',
|
|
186
192
|
'FormulaRegistry',
|
|
187
193
|
'InvalidRename',
|
|
194
|
+
'Aspect',
|
|
195
|
+
'AspectError',
|
|
196
|
+
'AspectNotApplicable',
|
|
197
|
+
'AspectRefused',
|
|
188
198
|
'Kind',
|
|
189
199
|
'KindLattice',
|
|
190
200
|
'RegistryDiff',
|
|
@@ -346,7 +346,6 @@ def _to_primitives(graph: "Graph") -> dict:
|
|
|
346
346
|
|
|
347
347
|
# --- Pass 5b: Formulas ---
|
|
348
348
|
if hasattr(graph, '_formula_registry') and graph._formula_registry is not None:
|
|
349
|
-
from ucon.aspects.types import AspectRule
|
|
350
349
|
|
|
351
350
|
for formula in graph._formula_registry:
|
|
352
351
|
out[f"f:{formula.name}"] = {
|
|
@@ -355,7 +354,6 @@ def _to_primitives(graph: "Graph") -> dict:
|
|
|
355
354
|
"e": formula.expression,
|
|
356
355
|
"ik": {b: k.name for b, k in formula.input_kinds.items()},
|
|
357
356
|
"ok": formula.output_kind.name,
|
|
358
|
-
"ar": {b: r.value for b, r in formula.aspect_rules.items()},
|
|
359
357
|
"g": formula.generalizes,
|
|
360
358
|
"c": formula.commutative,
|
|
361
359
|
"no": formula.notes,
|
|
@@ -716,7 +714,6 @@ def _from_primitives(raw: dict) -> "Graph":
|
|
|
716
714
|
formula_data.append(val)
|
|
717
715
|
|
|
718
716
|
if formula_data and kind_obj_map:
|
|
719
|
-
from ucon.aspects.types import AspectRule
|
|
720
717
|
from ucon.formulas import FormulaRegistry, KindFormula
|
|
721
718
|
|
|
722
719
|
formulas = []
|
|
@@ -730,15 +727,11 @@ def _from_primitives(raw: dict) -> "Graph":
|
|
|
730
727
|
else:
|
|
731
728
|
output_kind = kind_obj_map.get(fd["ok"])
|
|
732
729
|
if output_kind is not None:
|
|
733
|
-
aspect_rules = {
|
|
734
|
-
b: AspectRule(r) for b, r in fd.get("ar", {}).items()
|
|
735
|
-
}
|
|
736
730
|
formulas.append(KindFormula(
|
|
737
731
|
name=fd["n"],
|
|
738
732
|
expression=fd["e"],
|
|
739
733
|
input_kinds=input_kinds,
|
|
740
734
|
output_kind=output_kind,
|
|
741
|
-
aspect_rules=aspect_rules,
|
|
742
735
|
generalizes=fd.get("g", False),
|
|
743
736
|
commutative=fd.get("c", True),
|
|
744
737
|
notes=fd.get("no", ""),
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Copyright 2026 The Radiativity Company
|
|
2
|
+
# Licensed under the Apache License, Version 2.0
|
|
3
|
+
|
|
4
|
+
"""
|
|
5
|
+
Aspects: the discriminator that gates combination below the kind layer.
|
|
6
|
+
|
|
7
|
+
An *aspect* qualifies a quantity on terms the kind cannot express: two
|
|
8
|
+
dose equivalents — same dimension, same unit, same kind — may still be
|
|
9
|
+
weighted per different standards, and their sum conforms to neither.
|
|
10
|
+
Aspects are tree nodes grouped by family (the tree's root); resolution
|
|
11
|
+
is family-wise, and the flat-set model this package shipped through
|
|
12
|
+
v2.1.x (which could not distinguish *conflict* from *absence*) is gone.
|
|
13
|
+
|
|
14
|
+
Design record: ``docs/internal/decisions/008-aspect-stratum.md``.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from ucon.aspects.exceptions import (
|
|
18
|
+
AspectError,
|
|
19
|
+
AspectNotApplicable,
|
|
20
|
+
AspectRefused,
|
|
21
|
+
)
|
|
22
|
+
from ucon.aspects.forest import AspectForest
|
|
23
|
+
from ucon.aspects.resolution import resolve_add_aspects, resolve_mul_aspects
|
|
24
|
+
from ucon.aspects.types import Aspect, MultPolicy
|
|
25
|
+
|
|
26
|
+
__all__ = [
|
|
27
|
+
"Aspect",
|
|
28
|
+
"AspectForest",
|
|
29
|
+
"MultPolicy",
|
|
30
|
+
"resolve_add_aspects",
|
|
31
|
+
"resolve_mul_aspects",
|
|
32
|
+
"AspectError",
|
|
33
|
+
"AspectRefused",
|
|
34
|
+
"AspectNotApplicable",
|
|
35
|
+
]
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# Copyright 2026 The Radiativity Company
|
|
2
|
+
# Licensed under the Apache License, Version 2.0
|
|
3
|
+
|
|
4
|
+
"""
|
|
5
|
+
Exceptions raised by the aspect stratum.
|
|
6
|
+
|
|
7
|
+
Mirrors the kind layer's discipline (:mod:`ucon.kinds.exceptions`):
|
|
8
|
+
a common base, structured payloads, and messages that name what was
|
|
9
|
+
caught. ``AspectRefused`` covers both runtime refusal categories —
|
|
10
|
+
family conflict, and partial-under-strict — distinguished by whether
|
|
11
|
+
one side of the payload is ``None``.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
from typing import TYPE_CHECKING
|
|
17
|
+
|
|
18
|
+
if TYPE_CHECKING:
|
|
19
|
+
from ucon.aspects.types import Aspect
|
|
20
|
+
from ucon.kinds.types import JoinPolicy, Kind
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
__all__ = [
|
|
24
|
+
"AspectError",
|
|
25
|
+
"AspectRefused",
|
|
26
|
+
"AspectNotApplicable",
|
|
27
|
+
]
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class AspectError(Exception):
|
|
31
|
+
"""Base class for aspect stratum errors."""
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
class AspectRefused(AspectError):
|
|
35
|
+
"""An operation's operands cannot be reconciled within one family.
|
|
36
|
+
|
|
37
|
+
Two categories share this type:
|
|
38
|
+
|
|
39
|
+
- **Family conflict** — both operands carry positions in the family
|
|
40
|
+
and the lowest common ancestor's policy refuses the join
|
|
41
|
+
(``left`` and ``right`` are both :class:`Aspect`\\ s).
|
|
42
|
+
- **Partial under strict** — one operand carries the family and the
|
|
43
|
+
other is silent (the silent side is ``None``).
|
|
44
|
+
|
|
45
|
+
The ``family`` attribute is the family's root aspect; ``policy`` is
|
|
46
|
+
the join policy consulted. The payload is deliberately
|
|
47
|
+
warrant-shaped so a future unified refusal can wrap it losslessly.
|
|
48
|
+
"""
|
|
49
|
+
|
|
50
|
+
def __init__(
|
|
51
|
+
self,
|
|
52
|
+
*,
|
|
53
|
+
family: "Aspect",
|
|
54
|
+
left: "Aspect | None",
|
|
55
|
+
right: "Aspect | None",
|
|
56
|
+
policy: "JoinPolicy | None" = None,
|
|
57
|
+
) -> None:
|
|
58
|
+
self.family = family
|
|
59
|
+
self.left = left
|
|
60
|
+
self.right = right
|
|
61
|
+
self.policy = policy
|
|
62
|
+
if left is not None and right is not None:
|
|
63
|
+
detail = (
|
|
64
|
+
f"'{left.name}' and '{right.name}' cannot be reconciled "
|
|
65
|
+
f"under family '{family.name}'"
|
|
66
|
+
)
|
|
67
|
+
else:
|
|
68
|
+
present = left if left is not None else right
|
|
69
|
+
detail = (
|
|
70
|
+
f"one operand carries '{present.name}' "
|
|
71
|
+
f"(family '{family.name}') and the other is silent"
|
|
72
|
+
)
|
|
73
|
+
super().__init__(f"Aspect refusal: {detail}")
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
class AspectNotApplicable(AspectError):
|
|
77
|
+
"""An aspect family does not apply to the quantity's kind.
|
|
78
|
+
|
|
79
|
+
Raised at attachment time — ``Number(...)`` construction or formula
|
|
80
|
+
load — never during resolution. The ``family`` attribute is the
|
|
81
|
+
family root; ``kind`` is the offending kind (or ``None`` when the
|
|
82
|
+
family requires a kind and none was given).
|
|
83
|
+
"""
|
|
84
|
+
|
|
85
|
+
def __init__(self, *, family: "Aspect", kind: "Kind | None") -> None:
|
|
86
|
+
self.family = family
|
|
87
|
+
self.kind = kind
|
|
88
|
+
kind_name = kind.name if kind is not None else "<unkinded>"
|
|
89
|
+
super().__init__(
|
|
90
|
+
f"Aspect family '{family.name}' does not apply to kind "
|
|
91
|
+
f"'{kind_name}' (applies_to = {sorted(family.applies_to)!r})"
|
|
92
|
+
)
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
# Copyright 2026 The Radiativity Company
|
|
2
|
+
# Licensed under the Apache License, Version 2.0
|
|
3
|
+
|
|
4
|
+
"""
|
|
5
|
+
The aspect forest: family-grouped trees over the shared lattice engine.
|
|
6
|
+
|
|
7
|
+
Aspect trees run on the *kind-lattice engine* — each family's nodes are
|
|
8
|
+
mirrored into :class:`~ucon.kinds.types.Kind` objects (over the ``none``
|
|
9
|
+
dimension) and loaded into a private per-family
|
|
10
|
+
:class:`~ucon.kinds.lattice.KindLattice`. The engine is untouched
|
|
11
|
+
byte-for-byte, which is what preserves the vetted isomorphism: every
|
|
12
|
+
join/LCA behavior demonstrated for kinds transfers to aspects because it
|
|
13
|
+
*is* the same code.
|
|
14
|
+
|
|
15
|
+
Two boundary rules keep the layers legible:
|
|
16
|
+
|
|
17
|
+
- **Rewrap:** engine errors are ``KindError`` flavors; no Kind-named
|
|
18
|
+
exception may leak from an aspect declaration. Everything structural
|
|
19
|
+
is caught here and re-raised as :class:`AspectError` (with the engine
|
|
20
|
+
error chained as ``__cause__``); operational refusals become
|
|
21
|
+
:class:`AspectRefused`.
|
|
22
|
+
- **Root = family = ⊤:** the family is its tree's root by construction
|
|
23
|
+
— no synthetic top. Two disjoint subtrees within one family meet at
|
|
24
|
+
the root, whose default policy is ``refuse``.
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
from __future__ import annotations
|
|
28
|
+
|
|
29
|
+
from typing import Dict, Iterable, Iterator, List, Tuple
|
|
30
|
+
|
|
31
|
+
from ucon.aspects.exceptions import AspectError, AspectRefused
|
|
32
|
+
from ucon.aspects.types import Aspect
|
|
33
|
+
from ucon.dimension import Dimension
|
|
34
|
+
from ucon.kinds.exceptions import KindError
|
|
35
|
+
from ucon.kinds.lattice import KindLattice
|
|
36
|
+
from ucon.kinds.types import JoinPolicy, Kind
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
__all__ = ["AspectForest"]
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
# The engine requires a dimension; aspects have none. Every mirrored
|
|
43
|
+
# node shares this, so the engine's cross-dimension guard is inert.
|
|
44
|
+
_MIRROR_DIMENSION = Dimension.none
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
class AspectForest:
|
|
48
|
+
"""A collection of aspect trees, one lattice engine per family.
|
|
49
|
+
|
|
50
|
+
Construction closes over parents (passing leaves is enough),
|
|
51
|
+
validates root-only fields, and loads each family into its own
|
|
52
|
+
mirrored :class:`KindLattice`. All structural failures surface as
|
|
53
|
+
:class:`AspectError`.
|
|
54
|
+
"""
|
|
55
|
+
|
|
56
|
+
def __init__(self, aspects: Iterable[Aspect] = ()) -> None:
|
|
57
|
+
self._by_name: Dict[str, Aspect] = {}
|
|
58
|
+
# collect the parent-closure, dedup by name with identity check
|
|
59
|
+
for aspect in aspects:
|
|
60
|
+
node: Aspect | None = aspect
|
|
61
|
+
while node is not None:
|
|
62
|
+
existing = self._by_name.get(node.name)
|
|
63
|
+
if existing is None:
|
|
64
|
+
self._by_name[node.name] = node
|
|
65
|
+
elif existing is not node:
|
|
66
|
+
raise AspectError(
|
|
67
|
+
f"Duplicate aspect name {node.name!r}: two distinct "
|
|
68
|
+
f"nodes share it"
|
|
69
|
+
)
|
|
70
|
+
node = node.parent
|
|
71
|
+
|
|
72
|
+
# root-only field validation
|
|
73
|
+
for node in self._by_name.values():
|
|
74
|
+
if not node.is_root and node.applies_to:
|
|
75
|
+
raise AspectError(
|
|
76
|
+
f"Aspect {node.name!r} declares applies_to but is not a "
|
|
77
|
+
f"family root; the root ({node.root.name!r}) carries the "
|
|
78
|
+
f"family's rules"
|
|
79
|
+
)
|
|
80
|
+
|
|
81
|
+
# group by family and mirror each family into its own engine
|
|
82
|
+
self._families: Dict[str, List[Aspect]] = {}
|
|
83
|
+
for node in self._by_name.values():
|
|
84
|
+
self._families.setdefault(node.root.name, []).append(node)
|
|
85
|
+
|
|
86
|
+
self._engines: Dict[str, KindLattice] = {}
|
|
87
|
+
for root_name, members in self._families.items():
|
|
88
|
+
mirrored: Dict[str, Kind] = {}
|
|
89
|
+
|
|
90
|
+
def mirror(a: Aspect) -> Kind:
|
|
91
|
+
if a.name not in mirrored:
|
|
92
|
+
mirrored[a.name] = Kind(
|
|
93
|
+
a.name,
|
|
94
|
+
dimension=_MIRROR_DIMENSION,
|
|
95
|
+
parent=mirror(a.parent) if a.parent is not None else None,
|
|
96
|
+
join_policy=a.join_policy,
|
|
97
|
+
)
|
|
98
|
+
return mirrored[a.name]
|
|
99
|
+
|
|
100
|
+
try:
|
|
101
|
+
for member in members:
|
|
102
|
+
mirror(member)
|
|
103
|
+
self._engines[root_name] = KindLattice(mirrored.values())
|
|
104
|
+
except KindError as exc:
|
|
105
|
+
raise AspectError(
|
|
106
|
+
f"Invalid aspect family {root_name!r}: {exc}"
|
|
107
|
+
) from exc
|
|
108
|
+
|
|
109
|
+
# ---------- lookups ----------
|
|
110
|
+
|
|
111
|
+
def __contains__(self, name: str) -> bool:
|
|
112
|
+
return name in self._by_name
|
|
113
|
+
|
|
114
|
+
def __len__(self) -> int:
|
|
115
|
+
return len(self._by_name)
|
|
116
|
+
|
|
117
|
+
def __iter__(self) -> Iterator[Aspect]:
|
|
118
|
+
return iter(self._by_name.values())
|
|
119
|
+
|
|
120
|
+
def get(self, name: str) -> Aspect:
|
|
121
|
+
"""Resolve a name to its aspect; :class:`AspectError` if absent."""
|
|
122
|
+
aspect = self._by_name.get(name)
|
|
123
|
+
if aspect is None:
|
|
124
|
+
raise AspectError(f"Unknown aspect: {name!r}")
|
|
125
|
+
return aspect
|
|
126
|
+
|
|
127
|
+
def families(self) -> Tuple[Aspect, ...]:
|
|
128
|
+
"""The family roots, one per tree."""
|
|
129
|
+
return tuple(self.get(name) for name in self._families)
|
|
130
|
+
|
|
131
|
+
def family_of(self, aspect: Aspect) -> Aspect:
|
|
132
|
+
"""The family root governing *aspect* (registered instance)."""
|
|
133
|
+
return self.get(aspect.root.name)
|
|
134
|
+
|
|
135
|
+
# ---------- family-wise operations ----------
|
|
136
|
+
|
|
137
|
+
def lca(self, a: Aspect, b: Aspect) -> Tuple[Aspect, JoinPolicy]:
|
|
138
|
+
"""Lowest common ancestor within one family, with its policy.
|
|
139
|
+
|
|
140
|
+
Operands from different families are a caller error — resolution
|
|
141
|
+
groups by family before consulting the engine — and raise
|
|
142
|
+
:class:`AspectError`.
|
|
143
|
+
"""
|
|
144
|
+
family_a, family_b = a.root.name, b.root.name
|
|
145
|
+
if family_a != family_b:
|
|
146
|
+
raise AspectError(
|
|
147
|
+
f"Aspects {a.name!r} and {b.name!r} belong to different "
|
|
148
|
+
f"families ({family_a!r} vs {family_b!r}); family-wise "
|
|
149
|
+
f"resolution never compares across families"
|
|
150
|
+
)
|
|
151
|
+
engine = self._engines.get(family_a)
|
|
152
|
+
if engine is None:
|
|
153
|
+
raise AspectError(f"Unknown aspect family: {family_a!r}")
|
|
154
|
+
try:
|
|
155
|
+
node, policy = engine.lca(engine.get(a.name), engine.get(b.name))
|
|
156
|
+
except KindError as exc:
|
|
157
|
+
raise AspectError(
|
|
158
|
+
f"Aspect resolution failed in family {family_a!r}: {exc}"
|
|
159
|
+
) from exc
|
|
160
|
+
return self.get(node.name), policy
|
|
161
|
+
|
|
162
|
+
def join(self, a: Aspect, b: Aspect) -> Aspect:
|
|
163
|
+
"""LCA-based join honoring the ancestor's policy.
|
|
164
|
+
|
|
165
|
+
Equal aspects short-circuit. A ``refuse`` ancestor raises
|
|
166
|
+
:class:`AspectRefused` carrying the family, both operands, and
|
|
167
|
+
the policy consulted.
|
|
168
|
+
"""
|
|
169
|
+
if a.name == b.name:
|
|
170
|
+
return self.get(a.name)
|
|
171
|
+
ancestor, policy = self.lca(a, b)
|
|
172
|
+
if policy is JoinPolicy.REFUSE:
|
|
173
|
+
raise AspectRefused(
|
|
174
|
+
family=self.family_of(a),
|
|
175
|
+
left=self.get(a.name),
|
|
176
|
+
right=self.get(b.name),
|
|
177
|
+
policy=policy,
|
|
178
|
+
)
|
|
179
|
+
return ancestor
|