ucon 0.3.3rc1__tar.gz → 0.3.4__tar.gz

{ucon-0.3.3rc1 → ucon-0.3.4}/.github/workflows/publish.yaml

@@ -14,6 +14,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0  # needed for ancestry check
+          ref: ${{ github.ref_name }}
 
       - name: Set up Python
         uses: actions/setup-python@v5

{ucon-0.3.3rc1 → ucon-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.3.3rc1
+Version: 0.3.4
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
@@ -82,7 +82,7 @@ To best answer this question, we turn to an age-old technique ([dimensional anal
 
 `ucon` models unit math through a hierarchy where each layer builds on the last:
 
-<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/f3518d37445301950026fc9ffd1bd062768005fe/ucon.data-model.png align="center" alt="ucon Data Model" width=600/>
+<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/0c704737a52b9e4a87cda5c839e9aa40f7e5bb48/ucon.data-model_v035.png align="center" alt="ucon Data Model" width=600/>
 
 ## Why `ucon`?
 
@@ -138,12 +138,13 @@ becomes straightforward when you define a measurement:
 from ucon import Number, Scale, Units, Ratio
 
 # Two milliliters of bromine
-two_mL_bromine = Number(unit=Units.liter, scale=Scale.milli, quantity=2)
+mL = Scale.milli * units.liter
+two_mL_bromine = Number(quantity=2, unit=mL)
 
 # Density of bromine: 3.119 g/mL
 bromine_density = Ratio(
-    numerator=Number(unit=Units.gram, quantity=3.119),
-    denominator=Number(unit=Units.liter, scale=Scale.milli),
+    numerator=Number(unit=units.gram, quantity=3.119),
+    denominator=Number(unit=mL),
 )
 
 # Multiply to find mass

{ucon-0.3.3rc1 → ucon-0.3.4}/README.md

@@ -46,7 +46,7 @@ To best answer this question, we turn to an age-old technique ([dimensional anal
 
 `ucon` models unit math through a hierarchy where each layer builds on the last:
 
-<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/f3518d37445301950026fc9ffd1bd062768005fe/ucon.data-model.png align="center" alt="ucon Data Model" width=600/>
+<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/0c704737a52b9e4a87cda5c839e9aa40f7e5bb48/ucon.data-model_v035.png align="center" alt="ucon Data Model" width=600/>
 
 ## Why `ucon`?
 
@@ -102,12 +102,13 @@ becomes straightforward when you define a measurement:
 from ucon import Number, Scale, Units, Ratio
 
 # Two milliliters of bromine
-two_mL_bromine = Number(unit=Units.liter, scale=Scale.milli, quantity=2)
+mL = Scale.milli * units.liter
+two_mL_bromine = Number(quantity=2, unit=mL)
 
 # Density of bromine: 3.119 g/mL
 bromine_density = Ratio(
-    numerator=Number(unit=Units.gram, quantity=3.119),
-    denominator=Number(unit=Units.liter, scale=Scale.milli),
+    numerator=Number(unit=units.gram, quantity=3.119),
+    denominator=Number(unit=mL),
 )
 
 # Multiply to find mass

{ucon-0.3.3rc1 → ucon-0.3.4}/ROADMAP.md

@@ -23,13 +23,13 @@ Stable baseline for:
 - [x] Implement `Vector` and `Dimension` classes  
 - [x] Integrate dimensions into `Unit`  
 - [x] Refactor `ucon.units` to use dimensional definitions  
-- [ ] Publish documentation for dimensional operations  
+- [x] Publish documentation for dimensional operations
 - [x] Verify uniqueness and hashing correctness across all Dimensions  
 - [x] Redesign `Exponent` to support algebraic operations (`__mul__`, `__truediv__`, `to_base`, etc.)  
 - [x] Remove redundant evaluated caching in favor of property-based computation  
 - [x] Integrate `Scale` with Exponent for consistent prefix arithmetic  
 - [ ] Update `Number` and `Ratio` to use Exponent-driven scaling  
-- [ ] Add regression tests for prefix math (`kilo / milli → mega`, `2¹⁰ / 10³ → 1.024×`)  
+- [x] Add regression tests for prefix math (`kilo / milli → mega`, `2¹⁰ / 10³ → 1.024×`)
 - [ ] Document Exponent/Scale relationship in developer guide 
 
 ### 🧩 Outcomes
@@ -37,7 +37,7 @@ Stable baseline for:
 - Enables composable and type-safe dimensional operations  
 - Establishes the mathematical foundation for future conversions  
 - Unified algebraic foundation for all scaling and magnitude operations  
-- Precise, reversible cross-base math (`2ⁿ ↔ 10ᵐ`)  
+- ~Precise, reversible cross-base math (`2ⁿ ↔ 10ᵐ`)~
 - Simplified, consistent `Scale` and `Number` behavior  
 - Ready for integration into the conversion engine (`ucon.conversions`)
 

ucon-0.3.4/docs/decisions/composable-unit-algebra.md

@@ -0,0 +1,241 @@
+# UnitFactor — Structure for a Composable Unit Algebra
+
+## 1. Overview
+
+`UnitFactor` is introduced as a **structural atom** of the unit algebra:
+
+```
+UnitFactor = (unit, scale)
+```
+
+where:
+- `unit` is a stable, canonical unit identity (e.g., gram, liter, meter),  
+- `scale` is a prefix-like symbolic modifier (e.g., milli, kilo, micro).
+
+Unlike the legacy `Unit` object—which merged name, dimension, formatting hints, and scale—`UnitFactor` is **atomic**, **unambiguous**, and **hashable**.  
+It acts as the _basis element_ of the unit algebra — the analogue of a "BasisDimension" (i.e. Length, Time, etc.) in dimensional algebra.
+
+By elevating scale into a first-class algebraic component,  
+`UnitFactor` restores clean structural separation and enables unit expressions that are lossless, composable, and reversible.
+
+---
+
+## 2. The Problem It Solves
+
+### 2.1. Scale Entanglement in Legacy Unit Semantics
+
+Legacy `Unit` objects encoded scale internally:
+
+```
+mg = Unit("mg", dimension=MASS, scale=milli)
+```
+
+This resulted in a system where scale and identity were inseparable, leading to:
+
+- duplicate definitions (`mg` vs `milli * gram`),  
+- unwanted normalization of prefixes,  
+- scale leaking into numeric magnitude,  
+- loss of provenance during calculations.
+
+The system could _represent_ scaled units but could not _reason_ about them consistently.
+
+**`UnitFactor` resolves this by making scale a distinct algebraic coordinate.**
+
+---
+
+### 2.2. Loss of User Intent During Composite Operations
+
+`CompositeUnit` formerly stored raw `Unit` instances, which meant that user-intent information, especially regarding prefixes, was immediately lost.
+
+Example issues:
+
+- `mL` and `L` collapsed unpredictably
+- `(mg/mL) * mL` produced incorrect quantities
+- scale information disappeared inside normalization (absorbed by numeric magnitude)
+- mathematically identical expressions yielded structurally different objects
+
+By shifting to:
+
+```
+{ UnitFactor(base=gram, scale=milli) → +1,
+  UnitFactor(base=liter, scale=milli) → -1 }
+```
+
+the algebra becomes **lossless**, **deterministic**, and fully **transparent**.
+
+---
+
+### 2.3. Embedding Interpretation Inside Algebra
+
+Prior to `UnitFactor`, unit multiplication/division required interpretation:
+
+- Should prefix scale merge?
+- Should the result canonicalize to SI?
+- Should scale affect numeric magnitude?
+- Should shorthand labels collapse?
+
+These semantic choices polluted the algebra layer.
+
+**`UnitFactor` restores algebraic purity by keeping scale symbolic rather than interpretive.**
+
+---
+
+## 3. `UnitFactor` as an Atom in Unit Space
+
+`UnitFactor` parallels dimensional algebra:
+
+**Dimensional Algebra**
+```
+Vector({ BasisDimension → exponent })
+```
+
+**Unit Algebra (with `UnitFactor`)**
+```
+UnitProduct({ UnitFactor → exponent })
+```
+
+`UnitProduct` is the successor to `CompositeUnit`: _a free abelian product over `UnitFactor`s._
+
+This yields a clean architectural symmetry:
+
+| Dimensional Layer | Unit Layer (future) |
+|-------------------|----------------------|
+| BasisDimension | UnitFactor |
+| Vector | UnitProduct |
+| Dimension | UnitForm |
+
+`UnitFactor` is the “basis atom” that makes this composite unit space possible.
+
+---
+
+## 4. What `UnitFactor` Enables
+
+### 4.1. Lossless, Predictable Unit Arithmetic
+
+- user prefixes remain intact
+- cancellation is structural, not heuristic
+- unit cancellation _before_ scale factor reconciliation
+- algebraic operations preserve user intent
+- scale never leaks into numeric magnitude
+
+Examples:
+
+```
+(g/mL) * mL  → g
+(mg/mL) * mL → mg
+```
+
+Correctness is now a mathematical property, not an accidental outcome.
+
+---
+
+### 4.2. Algebraic Normalization without Canonicalization
+
+`UnitFactor` supports strict algebraic behavior:
+
+- no forced SI normalization
+- no heuristic prefix adjustments
+- no implicit conversion to base units
+
+Canonicalization moves into higher layers (`UnitForm`, `ConversionGraph`).
+
+---
+
+### 4.3. Foundation for ConversionGraph
+
+`UnitFactor` exposes:
+
+- base identity
+- scale prefix
+- dimension
+
+as independent coordinates, enabling semantic conversions such as:
+
+```
+kJ·h/s → J·h/s → W·h
+```
+
+`UnitFactor` & `UnitProduct` provide the structural substrate, while `ConversionGraph` handles meaning.
+
+---
+
+## 5. The Path It Paves
+
+### 5.1. Eliminating `Unit.scale`
+
+`Unit` becomes purely declarative:
+
+```
+Unit(name="gram", dimension=MASS)
+```
+
+All scaling semantics shift into `FactoredUnit`.
+Once scale is removed, `Unit` no longer participates in algebraic operations.
+It becomes a **canonical identity object**, analogous to a basis `Dimension` (e.g. time, length, mass, etc.):
+a stable nameable anchor used by registries, `UnitForm`, and `ConversionGraph`.
+
+A Unit carries only semantic information (name, aliases, dimension) and does _not_ combine multiplicatively.
+All algebraic behavior moves exclusively into `UnitFactor` and `UnitProduct`, allowing `Unit` to remain a pure symbolic identity within the broader type ecosystem.
+
+---
+
+### 5.2. CompositeUnit Evolves into UnitProduct
+
+`CompositeUnit` is ultimately replaced by:
+
+```
+UnitProduct = { UnitFactor → exponent }
+```
+
+This yields a principled free abelian structure paralleling dimensional vectors.
+
+---
+
+### 5.3. User-Facing Layer Becomes UnitForm
+
+**UnitForm** becomes the user-visible representation layer:
+
+- parses expressions (`"g/mL"`)  
+- prints canonical or preferred forms  
+- integrates with registries  
+- applies prefix or display policies  
+- guarantees round-trip stability  
+
+`UnitProduct` becomes the algebra;  
+`UnitForm` becomes the language.
+
+---
+
+### 5.4. Integration with ConversionGraph
+
+`UnitFactor` and `UnitProduct` act as the structural substrate for semantic conversions:
+
+- J ↔ W·s  
+- cal ↔ J  
+- mL ↔ L  
+- h ↔ 3600 s
+
+`ConversionGraph` operates on meaning; `UnitProduct` ensures consistent structure.
+
+---
+
+## 6. Architectural Summary
+
+| Layer | Role | Value |
+|-------|------|--------|
+| **Unit** | atomic, canonical identity | base symbol for units |
+| **UnitFactor** | algebraic atom | scale-inclusive symbolic factor |
+| **UnitProduct** | formal product | composable, invertible algebra |
+| **UnitForm** | user-facing interface | formatting, parsing, canonicalization |
+| **ConversionGraph** | semantic layer | derived-unit conversions |
+
+For a deep dive into the new naming conventions check [this](./unit-algebra-naming.md) out
+
+---
+
+## 7. Philosophical Note
+
+> A unit is not a label.  
+> It is a structural atom in an algebra whose interactions encode physical meaning.
+
+`UnitFactor` restores this foundation, revealing the future shape of `ucon`’s unit algebra.

ucon-0.3.4/docs/decisions/composite-units.md

@@ -0,0 +1,160 @@
+# Unit Combination and Algebraic Closure in `ucon`
+
+## 1. Composite Units
+
+Composite dimensions (e.g., velocity, acceleration, density) arise as products or quotients of base dimensions.
+In the continuous model, these combine algebraically in exponent space.
+
+Example: velocity = length / time
+
+$$
+V = \frac{L}{T} = a^{x_L - x_T}
+$$
+
+If the length and time graphs are independent CCGs, their exponents combine by **subtraction of vectors**.
+This allows multi-dimensional conversion to be expressed purely algebraically.
+
+| Quantity | Formula | Exponent Form |
+|-----------|----------|---------------|
+| Velocity | L/T | \( $x_L - x_T$ \) |
+| Acceleration | L/T² | \( $x_L - 2x_T$ \) |
+| Force | M·L/T² | \( $x_M + x_L - 2x_T$ \) |
+| Density | M/L³ | \( $x_M - 3x_L$ \) |
+
+Each component dimension (L, T, M, etc.) maintains its own graph — conversions for composite units are vector sums.
+
+---
+
+## 2. What Would Be Impossible Without `CompositeUnit`
+
+Without `CompositeUnit`, **ucon would be descriptive, not algebraic.**  
+It could *store* conversions but not *derive* them.  
+
+| Capability | Without `CompositeUnit` | With `CompositeUnit` |
+|-------------|------------------------|-----------------------|
+| Unit algebra | Flat mapping of names | Free abelian group of composable morphisms |
+| Derived dimensions | Pre-registered only | Algebraically inferred |
+| Simplification | Manual or string-based | Symbolic, lossless cancellation |
+| Conversion chaining | Requires graph heuristics | Structural traversal via decomposition |
+| Reasoning | String pattern matching | Category-theoretic functor between symbolic and numeric domains |
+| Expressiveness | Lookup tables | Algebraic system of morphisms |
+| Extensibility | Must predefine all derived units | Derived units emerge from composition |
+
+> `CompositeUnit` transforms ucon from a **registry of facts** into an **engine of derivation.**
+
+---
+
+## 3. CompositeUnit, Exponent, and Scale: Cohesive Closure
+
+| Role | Domain | Operation | Closure Guarantee |
+|------|---------|------------|------------------|
+| **Exponent** | Algebra | Powers of numeric bases (10, 2, etc.) | Defines magnitude algebra |
+| **Scale** | Ontology | Named prefixes for exponents | Names exponent values |
+| **Unit** | Ontology | Typed measure symbol | Couples dimension + scale |
+| **CompositeUnit** | Algebra on units | Product, quotient, powers | Closes the group |
+
+This creates the **closure chain**:
+
+$$
+\text{Exponent} \Rightarrow \text{Scale} \Rightarrow \text{Unit} \Rightarrow \text{CompositeUnit}
+$$
+
+Each layer embeds the previous one, while adding new semantics (naming, dimension, composability).
+
+---
+
+## 4. CompositeUnit as Morphism
+
+`CompositeUnit` is both an **element** and a **morphism** in the unit group:
+
+$$
+f: U_1 \to U_2, \quad f(a \cdot b) = f(a) \cdot f(b)
+$$
+
+This gives the unit algebra:
+
+- **Associativity** (composition)
+- **Identity** (`dimensionless`)
+- **Inverses** (`u⁻¹`)
+- **Closure** (`U × U → CompositeUnit ⊂ Unit`)
+
+It forms a **monoidal category** of units where:
+- objects = base units,
+- morphisms = composite transformations,
+- functors = conversions between systems (SI, CGS, Imperial).
+
+---
+
+## 5. Why the ConversionGraph Depends on It
+
+The ConversionGraph functor acts over this unit algebra:
+
+$$
+F: (\text{Unit Algebra}) \to (\text{Numeric Transformations})
+$$
+
+`CompositeUnit` guarantees totality — all symbolic unit expressions can be decomposed and recomposed in graph traversal.
+
+Example:
+```python
+force = units.kilogram * units.meter / (units.second ** 2)
+graph.convert(force, "N")  # Converts via decomposed path
+```
+
+Without `CompositeUnit`, such a conversion is not possible,  
+since the graph would have no way to represent composite relationships between base units.
+
+---
+
+## 6. How Competitors Handle This (or Don’t)
+
+| Library | Composite Concept | Mechanism | Limitations |
+|----------|------------------|------------|--------------|
+| **Pint** | Implicit composite via `Quantity` + registry | Tuple of (unit, exponent) pairs parsed from strings | Composite logic is hidden, not a first-class algebraic type; no symbolic morphisms |
+| **SymPy.physics.units** | Composition through symbolic `Mul(Unit, Unit)` trees | Full symbolic representation | Algebraic but non-canonical; requires tree simplification and lacks registry consistency |
+| **Unyt** | `UnitRegistry` + array wrapper | Exponents over strings | Conversion graph is registry-based only; no morphic algebra |
+| **Astropy.units** | `UnitBase` and compound units via operator overloads | Functional for end users | No first-class algebra for composition; context-dependent simplification |
+| **Unum** | Explicit *universal number* with lazy dimension algebra | Arithmetic objects track dimension exponents | Symbolic but not categorical: lacks conversion composition semantics and no functorial conversion; operations can lose context |
+| **ucon** | **`CompositeUnit` as morphism in a composable unit group** | Explicit algebraic closure; conversion is a functor | Symbolic reasoning, compositional simplification, direct ConversionGraph integration |
+
+### 🔍 Commentary on *Unum*
+- **Strength:** Unum pioneered embedding dimensional arithmetic directly into number objects (`Unum(3, 'm/s²')`).
+- **Weakness:** Its algebra is _monolithic_, coupling value, dimension, and conversion rules in one type.
+  - There’s no separation of concerns — no morphism layer between symbolic representation and numeric transformation.
+  - Conversions are _eager_ rather than structural, meaning they cannot be composed functorially.
+- **Contrast with ucon:**  
+  ucon’s `CompositeUnit` isolates the symbolic structure from numeric evaluation.  
+  This allows deferred evaluation, symbolic simplification, and graph-based reasoning across systems of units.  
+  Thus, ucon’s algebra is **refactorable and extensible**, while unum’s is **monolithic and eager**.
+
+---
+
+## 7. Philosophical Summary
+
+> In most libraries, a “unit” is a label.  
+> In ucon, a unit is a **morphism** in a composable algebra.
+
+`CompositeUnit` makes ucon a **structural model** of physics:
+
+$$
+\frac{L}{T^2} \Rightarrow \text{Acceleration}
+$$
+
+not as a string or a heuristic, but as a typed algebraic expression.
+
+It allows ucon to:
+- **derive** (not just define) relationships,
+- **normalize** representations,
+- **reason** about systems symbolically and numerically.
+
+Thus:
+> ucon is not merely a _unit-aware computation library_ — it is a **dimensional reasoning framework.**
+
+---
+
+## 7. Next Steps (Implementation Implications)
+
+1. Keep `CompositeUnit` algebraically pure (no conversion logic).  
+1. Allow `Unit` and `Scale` to compose naturally.  
+1. Ensure simplification of reciprocal terms (`g·mL/mL → g`).  
+1. Use canonical hashing for composite signatures.  

ucon-0.3.4/docs/decisions/unit-algebra-naming.md

@@ -0,0 +1,169 @@
+# Future Naming Scheme for the `Unit` Algebra  
+*(UnitFactor, UnitProduct, UnitForm)*
+
+## 1. Context
+
+ucon’s evolving unit system is transitioning toward a more explicit algebraic foundation.
+Recent advances—particularly the introduction of `FactoredUnit`—have clarified the need for:
+
+- cleaner separation between *atomic unit components*  
+- purely algebraic composite unit structures  
+- a stable, user-facing layer for rendering, parsing, and canonicalization
+
+As ucon’s unit semantics converge toward a **free abelian group** model (mirroring the dimensional algebra), the existing naming (`CompositeUnit`, `FactoredUnit`, `Unit`) no longer captures the distinctions between:
+
+- the algebraic substrate
+- the atomic symbolic components
+- the user interface layer
+
+This document outlines a naming scheme aligned with that architecture.
+
+---
+
+## 2. Decision
+
+Adopt the following naming triad for a future ucon unit algebra:
+
+### **1. UnitFactor**  
+The atomic building block of unit expressions.
+
+- Represents a pair: _(canonical unit identity, scale)_
+- Corresponds structurally to a “coordinate” or “basis element” of the unit algebra
+- Replaces and generalizes the existing `FactoredUnit`
+- Holds no formatting, registry, or canonicalization responsibilities
+- Exists solely for algebraic manipulation
+
+### **2. UnitProduct**  
+The algebraic combination of UnitFactors.
+
+- A mapping `{UnitFactor → exponent}`
+- Represents a formal multiplicative product
+- Free abelian group structure (addition/subtraction of exponents)
+- Replaces the current `CompositeUnit`
+- Pure algebraic core: no interpretation, no formatting, no normalization
+- Positionally analogous to the dimensional `Vector` type, but specialized to units
+
+### **3. UnitForm**  
+The user-facing representation of units.
+
+- Provides formatting, parsing, canonicalization rules, alias handling, and registry integration
+- Wraps a `UnitProduct` internally
+- Represents what users write and see (`"g/mL"`, `"kW·h"`, `"psi"`)
+- Cleanly decouples UI semantics from algebraic mechanics
+- Replaces the conceptual role of “Unit” as the object users interact with
+
+---
+
+## 3. Rationale
+
+### 3.1. Why **UnitFactor**  
+“Factor” is:
+
+- algebraically accurate
+- readable and intuitive
+- directly compatible with the term “product”
+- expressive of the role: a scaled, atomic unit element that participates in multiplication
+
+Compared to alternatives (“Term”, “BasisUnit”, “Atom”, “Coordinate”),  
+**UnitFactor** strikes the ideal balance between mathematical precision and everyday usability.
+
+---
+
+### 3.2. Why **UnitProduct**  
+The algebra underlying ucon unit combinations is not vector algebra  
+(in the sense of magnitude-1 unit vectors), but **formal multiplicative algebra**.
+
+A UnitProduct is:
+
+- a product of UnitFactors
+- a free abelian group element
+- the natural analogue of a symbolic monomial
+
+“Product” is accessible to users without sacrificing correctness.  
+It avoids the misleading connotation of “vector” and is friendlier than “monomial.”
+
+---
+
+### 3.3. Why **UnitForm**  
+The system needs a distinct layer that:
+
+- users interact with
+- ties into the registry
+- controls printing and parsing
+- decides when/how to reflect prefixes
+- chooses canonical representations
+- remains stable across refactors
+
+“UnitExpression” was serviceable but generic.  
+“UnitForm” is:
+
+- concise
+- semantically clean
+- visually and conceptually distinct from algebraic layers
+- evocative of representation rather than structure
+
+It completes the tiered architecture:
+
+```
+UnitFactor    → structural atom
+UnitProduct   → algebraic composite
+UnitForm      → user-facing representation
+```
+
+---
+
+## 4. Consequences
+
+### Positive
+
+- Clear conceptual separation between algebra and user semantics
+- Naming aligns with physical intuition and mathematical structure
+- Improves API clarity and documentation readability
+- Prepares the codebase for future features:
+  - ConversionGraph
+  - Semantic canonicalization
+  - Unit registry enhancements
+  - Parsing/formatting improvements
+
+### Neutral/Deferred
+
+- No immediate refactor is required; this ADR guides future work  
+- CompositeUnit and FactoredUnit can coexist temporarily during transition
+- Existing APIs remain intact until migration pathways are established
+
+### Negative
+
+- Some renaming churn is expected during adoption
+- Downstream references to “CompositeUnit” and “FactoredUnit” will need updating
+
+---
+
+## 5. Alternatives Considered
+
+- **UnitMonomial / UnitTerm**  
+  - Mathematically elegant but feels overly academic
+- **UnitCoordinate / UnitVector**  
+  - Accurate but too abstract, and “unit vector” is overloaded in linear algebra
+- **UnitExpression**  
+  - Adequate, but less crisp than “UnitForm” as a representation-layer concept
+- **Retaining existing names**  
+  - Would perpetuate conceptual muddiness as the system grows
+
+---
+
+## 6. Future Work (Nonbinding)
+
+- Introduce `UnitFactor` and `UnitProduct` in parallel with existing structures
+- Evolve `UnitForm` as the primary user-facing unit API
+- Gradually refactor internal algebra toward the new architecture
+- Propose complementary ADRs covering:
+  - CanonicalUnit identity objects
+  - Registry architecture
+  - ConversionGraph integration
+  - Unit parsing and pretty-printing models
+
+---
+
+## 7. Acknowledgements
+
+This naming scheme emerged from design discussions surrounding the FactoredUnit refactor, the need for scale-preserving operations, and the broader goal of unifying unit algebra with dimensional algebra in ucon’s long-term architecture.

ucon-0.3.4/docs/explainers/type-operation-matrix.md

@@ -0,0 +1,14 @@
+# Type × Operation Matrix
+
+| Type          | +   | -   | *   | /   | **  | Neg | ==    | Category                |
+|---------------|-----|-----|-----|-----|-----|-----|--------|-------------------------|
+| Vector        | ✓   | ✓   | ✓   | —   | —   | ✓   | ✓      | Algebraic               |
+| Exponent      | —   | —   | ✓   | ✓   | ✓   | —   | ✓      | Algebraic               |
+| Dimension     | —   | —   | ✓   | ✓   | ✓   | —   | ✓      | Algebraic               |
+| CompositeUnit | —   | —   | ✓   | ✓   | ✓   | —   | ✓      | Algebraic               |
+| Number        | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | structural | Algebraic           |
+| Ratio         | —   | —   | ✓   | ✓   | —   | —   | —      | Partial Algebra         |
+| Unit          | —   | —   | —   | —   | —   | —   | ✓      | Semantic                |
+| Scale         | —   | —   | ✓   | —   | —   | —   | —      | Semantic                |
+| ScaleDescriptor | — | —   | —   | —   | —   | —   | —      | Semantic                |
+| FactoredUnit  | —   | —   | —   | —   | —   | —   | ✓      | Semantic            |