ucon 2.1.7__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.
Files changed (92) hide show
  1. {ucon-2.1.7 → ucon-2.2.0}/.gitignore +16 -0
  2. {ucon-2.1.7 → ucon-2.2.0}/CHANGELOG.md +134 -0
  3. {ucon-2.1.7/ucon.egg-info → ucon-2.2.0}/PKG-INFO +1 -1
  4. {ucon-2.1.7 → ucon-2.2.0}/ROADMAP.md +6 -0
  5. {ucon-2.1.7 → ucon-2.2.0}/ucon/__init__.py +10 -0
  6. {ucon-2.1.7 → ucon-2.2.0}/ucon/_cache.py +0 -7
  7. ucon-2.2.0/ucon/aspects/__init__.py +35 -0
  8. ucon-2.2.0/ucon/aspects/exceptions.py +92 -0
  9. ucon-2.2.0/ucon/aspects/forest.py +179 -0
  10. ucon-2.2.0/ucon/aspects/resolution.py +144 -0
  11. ucon-2.2.0/ucon/aspects/types.py +103 -0
  12. {ucon-2.1.7 → ucon-2.2.0}/ucon/comprehensive.ucon.toml +1 -3
  13. {ucon-2.1.7 → ucon-2.2.0}/ucon/conversion.py +31 -1
  14. {ucon-2.1.7 → ucon-2.2.0}/ucon/core/_types.py +99 -23
  15. {ucon-2.1.7 → ucon-2.2.0}/ucon/dimension.py +16 -1
  16. {ucon-2.1.7 → ucon-2.2.0}/ucon/formulas/__init__.py +5 -8
  17. {ucon-2.1.7 → ucon-2.2.0}/ucon/formulas/registry.py +15 -44
  18. {ucon-2.1.7 → ucon-2.2.0}/ucon/formulas/types.py +1 -55
  19. {ucon-2.1.7 → ucon-2.2.0}/ucon/kinds/exceptions.py +32 -3
  20. {ucon-2.1.7 → ucon-2.2.0}/ucon/kinds/lattice.py +5 -1
  21. {ucon-2.1.7 → ucon-2.2.0}/ucon/packages.py +24 -0
  22. {ucon-2.1.7 → ucon-2.2.0}/ucon/parsing/__init__.py +10 -3
  23. ucon-2.2.0/ucon/parsing/aspects.py +189 -0
  24. {ucon-2.1.7 → ucon-2.2.0}/ucon/parsing/formulas.py +2 -23
  25. ucon-2.2.0/ucon/parsing/namespaces.py +144 -0
  26. {ucon-2.1.7 → ucon-2.2.0}/ucon/serialization.py +73 -8
  27. {ucon-2.1.7 → ucon-2.2.0}/ucon/system/__init__.py +8 -8
  28. {ucon-2.1.7 → ucon-2.2.0/ucon.egg-info}/PKG-INFO +1 -1
  29. {ucon-2.1.7 → ucon-2.2.0}/ucon.egg-info/SOURCES.txt +5 -0
  30. {ucon-2.1.7 → ucon-2.2.0}/ucon.egg-info/scm_file_list.json +21 -5
  31. ucon-2.2.0/ucon.egg-info/scm_version.json +8 -0
  32. ucon-2.1.7/ucon/aspects/__init__.py +0 -38
  33. ucon-2.1.7/ucon/aspects/types.py +0 -154
  34. ucon-2.1.7/ucon.egg-info/scm_version.json +0 -8
  35. {ucon-2.1.7 → ucon-2.2.0}/.github/workflows/downstream.yaml +0 -0
  36. {ucon-2.1.7 → ucon-2.2.0}/.github/workflows/publish.yaml +0 -0
  37. {ucon-2.1.7 → ucon-2.2.0}/.github/workflows/tests.yaml +0 -0
  38. {ucon-2.1.7 → ucon-2.2.0}/.gitmodules +0 -0
  39. {ucon-2.1.7 → ucon-2.2.0}/LICENSE +0 -0
  40. {ucon-2.1.7 → ucon-2.2.0}/MANIFEST.in +0 -0
  41. {ucon-2.1.7 → ucon-2.2.0}/Makefile +0 -0
  42. {ucon-2.1.7 → ucon-2.2.0}/NOTICE +0 -0
  43. {ucon-2.1.7 → ucon-2.2.0}/README.md +0 -0
  44. {ucon-2.1.7 → ucon-2.2.0}/SECURITY.md +0 -0
  45. {ucon-2.1.7 → ucon-2.2.0}/SUPPORT.md +0 -0
  46. {ucon-2.1.7 → ucon-2.2.0}/mkdocs.yml +0 -0
  47. {ucon-2.1.7 → ucon-2.2.0}/netlify.toml +0 -0
  48. {ucon-2.1.7 → ucon-2.2.0}/pyproject.toml +0 -0
  49. {ucon-2.1.7 → ucon-2.2.0}/requirements.txt +0 -0
  50. {ucon-2.1.7 → ucon-2.2.0}/setup.cfg +0 -0
  51. {ucon-2.1.7 → ucon-2.2.0}/ucon/_active.py +0 -0
  52. {ucon-2.1.7 → ucon-2.2.0}/ucon/_algebra_cache.py +0 -0
  53. {ucon-2.1.7 → ucon-2.2.0}/ucon/_bootstrap.py +0 -0
  54. {ucon-2.1.7 → ucon-2.2.0}/ucon/basis/__init__.py +0 -0
  55. {ucon-2.1.7 → ucon-2.2.0}/ucon/basis/builtin.py +0 -0
  56. {ucon-2.1.7 → ucon-2.2.0}/ucon/basis/graph.py +0 -0
  57. {ucon-2.1.7 → ucon-2.2.0}/ucon/basis/ops.py +0 -0
  58. {ucon-2.1.7 → ucon-2.2.0}/ucon/basis/transforms.py +0 -0
  59. {ucon-2.1.7 → ucon-2.2.0}/ucon/basis/types.py +0 -0
  60. {ucon-2.1.7 → ucon-2.2.0}/ucon/basis/vector.py +0 -0
  61. {ucon-2.1.7 → ucon-2.2.0}/ucon/checking.py +0 -0
  62. {ucon-2.1.7 → ucon-2.2.0}/ucon/constants.py +0 -0
  63. {ucon-2.1.7 → ucon-2.2.0}/ucon/constants.pyi +0 -0
  64. {ucon-2.1.7 → ucon-2.2.0}/ucon/contexts.py +0 -0
  65. {ucon-2.1.7 → ucon-2.2.0}/ucon/core/__init__.py +0 -0
  66. {ucon-2.1.7 → ucon-2.2.0}/ucon/core/_parsing_graph.py +0 -0
  67. {ucon-2.1.7 → ucon-2.2.0}/ucon/core/exceptions.py +0 -0
  68. {ucon-2.1.7 → ucon-2.2.0}/ucon/dimension.pyi +0 -0
  69. {ucon-2.1.7 → ucon-2.2.0}/ucon/expressions.py +0 -0
  70. {ucon-2.1.7 → ucon-2.2.0}/ucon/formulas/exceptions.py +0 -0
  71. {ucon-2.1.7 → ucon-2.2.0}/ucon/graph.py +0 -0
  72. {ucon-2.1.7 → ucon-2.2.0}/ucon/integrations/__init__.py +0 -0
  73. {ucon-2.1.7 → ucon-2.2.0}/ucon/integrations/numpy.py +0 -0
  74. {ucon-2.1.7 → ucon-2.2.0}/ucon/integrations/pandas.py +0 -0
  75. {ucon-2.1.7 → ucon-2.2.0}/ucon/integrations/polars.py +0 -0
  76. {ucon-2.1.7 → ucon-2.2.0}/ucon/integrations/pydantic.py +0 -0
  77. {ucon-2.1.7 → ucon-2.2.0}/ucon/kinds/__init__.py +0 -0
  78. {ucon-2.1.7 → ucon-2.2.0}/ucon/kinds/types.py +0 -0
  79. {ucon-2.1.7 → ucon-2.2.0}/ucon/maps.py +0 -0
  80. {ucon-2.1.7 → ucon-2.2.0}/ucon/parsing/dimensions.py +0 -0
  81. {ucon-2.1.7 → ucon-2.2.0}/ucon/parsing/kinds.py +0 -0
  82. {ucon-2.1.7 → ucon-2.2.0}/ucon/parsing/lexer.py +0 -0
  83. {ucon-2.1.7 → ucon-2.2.0}/ucon/parsing/quantity.py +0 -0
  84. {ucon-2.1.7 → ucon-2.2.0}/ucon/parsing/units.py +0 -0
  85. {ucon-2.1.7 → ucon-2.2.0}/ucon/quantity.py +0 -0
  86. {ucon-2.1.7 → ucon-2.2.0}/ucon/resolver.py +0 -0
  87. {ucon-2.1.7 → ucon-2.2.0}/ucon/units.py +0 -0
  88. {ucon-2.1.7 → ucon-2.2.0}/ucon/units.pyi +0 -0
  89. {ucon-2.1.7 → ucon-2.2.0}/ucon.egg-info/dependency_links.txt +0 -0
  90. {ucon-2.1.7 → ucon-2.2.0}/ucon.egg-info/requires.txt +0 -0
  91. {ucon-2.1.7 → ucon-2.2.0}/ucon.egg-info/top_level.txt +0 -0
  92. {ucon-2.1.7 → 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,138 @@ 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
+
10
142
  ### Fixed
11
143
 
12
144
  - **Mechanical CGS units now carry exact SI-factored `base_form`s.**
@@ -2674,6 +2806,8 @@ Deprecated surfaces are scheduled for removal in v2.0.
2674
2806
  - Initial commit
2675
2807
 
2676
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
2677
2811
  [2.1.6]: https://github.com/withtwoemms/ucon/compare/2.1.5...2.1.6
2678
2812
  [2.1.5]: https://github.com/withtwoemms/ucon/compare/2.1.4...2.1.5
2679
2813
  [2.1.4]: https://github.com/withtwoemms/ucon/compare/2.1.3...2.1.4
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ucon
3
- Version: 2.1.7
3
+ Version: 2.2.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>
@@ -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