PyPI - ucon - Versions diffs - 0.3.5rc1__tar.gz → 0.3.5rc2__tar.gz - Mend

ucon 0.3.5rc1tar.gz → 0.3.5rc2tar.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 (38) hide show

{ucon-0.3.5rc1 → ucon-0.3.5rc2}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.3.5rc1
+Version: 0.3.5rc2
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
@@ -55,8 +55,8 @@ Dynamic: summary
 It combines **units**, **scales**, and **dimensions** into a composable algebra that supports:
 - Dimensional analysis through `Number` and `Ratio`
-- Scale-aware arithmetic and conversions
-- Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, ect.)
+- Scale-aware arithmetic via `UnitFactor` and `UnitProduct`
+- Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, etc.)
 - A clean foundation for physics, chemistry, data modeling, and beyond
 Think of it as **`decimal.Decimal` for the physical world** — precise, predictable, and type-safe.
@@ -70,20 +70,22 @@ The crux of this tiny library is to provide abstractions that simplify the answe
 To best answer this question, we turn to an age-old technique ([dimensional analysis](https://en.wikipedia.org/wiki/Dimensional_analysis)) which essentially allows for the solution to be written as a product of ratios. `ucon` comes equipped with some useful primitives:
 | Type                          | Defined In                              | Purpose                                                                                             | Typical Use Cases                                                                                                      |
 | ----------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **`Vector`**                  | `ucon.dimension`                        | Represents the exponent tuple of a physical quantity’s base dimensions (e.g., T, L, M, I, Θ, J, N). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
-| **`Dimension`**               | `ucon.dimension`                        | Encapsulates physical dimensions (e.g., length, time, mass) as algebraic combinations of vectors.   | Enforcing dimensional consistency; defining relationships between quantities (e.g., length / time = velocity).         |
-| **`Unit`**                    | `ucon.unit`                             | Represents a named, dimensioned measurement unit (e.g., meter, second, joule).                      | Attaching human-readable units to quantities; defining or composing new units (`newton = kilogram * meter / second²`). |
+| **`Vector`**                  | `ucon.algebra`                          | Represents the exponent tuple of a physical quantity's base dimensions (e.g., T, L, M, I, Θ, J, N). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
+| **`Exponent`**                | `ucon.algebra`                          | Represents base-power pairs (e.g., 10³, 2¹⁰) used by `Scale`.                                       | Performing arithmetic on powers and bases; normalizing scales across conversions.                                      |
+| **`Dimension`**               | `ucon.core`                             | Encapsulates physical dimensions (e.g., length, time, mass) as algebraic combinations of vectors.   | Enforcing dimensional consistency; defining relationships between quantities (e.g., length / time = velocity).         |
 | **`Scale`**                   | `ucon.core`                             | Encodes powers of base magnitudes (binary or decimal prefixes like kilo-, milli-, mebi-).           | Adjusting numeric scale without changing dimension (e.g., kilometer ↔ meter, byte ↔ kibibyte).                         |
-| **`Exponent`**                | `ucon.core`                             | Represents base-power pairs (e.g., 10³, 2¹⁰) used by `Scale`.                                       | Performing arithmetic on powers and bases; normalizing scales across conversions.                                      |
-| **`Number`**                  | `ucon.core`                             | Combines a numeric quantity with a unit and scale; the primary measurable type.                     | Performing arithmetic with units; converting between compatible units; representing physical quantities like 5 m/s.    |
-| **`Ratio`**                   | `ucon.core`                             | Represents the division of two `Number` objects; captures relationships between quantities.         | Expressing rates, densities, efficiencies (e.g., energy / time = power, length / time = velocity).                     |
-| **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI and common derived units).                                     | Quick access to standard physical units (`units.meter`, `units.second`, `units.newton`, etc.).                               |                                                   |
+| **`Unit`**                    | `ucon.core`                             | An atomic, scale-free measurement symbol (e.g., meter, second, joule) with a `Dimension`.           | Defining base units; serving as graph nodes for future conversions.                                                    |
+| **`UnitFactor`**              | `ucon.core`                             | Pairs a `Unit` with a `Scale` (e.g., kilo + gram = kg). Used as keys inside `UnitProduct`.          | Preserving user-provided scale prefixes through algebraic operations.                                                  |
+| **`UnitProduct`**             | `ucon.core`                             | A product/quotient of `UnitFactor`s with exponent tracking and simplification.                      | Representing composite units like m/s, kg·m/s², kJ·h.                                                                 |
+| **`Number`**                  | `ucon.quantity`                         | Combines a numeric quantity with a unit; the primary measurable type.                               | Performing arithmetic with units; representing physical quantities like 5 m/s.                                         |
+| **`Ratio`**                   | `ucon.quantity`                         | Represents the division of two `Number` objects; captures relationships between quantities.         | Expressing rates, densities, efficiencies (e.g., energy / time = power, length / time = velocity).                     |
+| **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI and common derived units).                                     | Quick access to standard physical units (`units.meter`, `units.second`, `units.newton`, etc.).                          |
 ### Under the Hood
 `ucon` models unit math through a hierarchy where each layer builds on the last:
-<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/0c704737a52b9e4a87cda5c839e9aa40f7e5bb48/ucon.data-model_v035.png align="center" alt="ucon Data Model" width=600/>
+<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/f24134c362829dc72e7dff18bfcaa24b9be01b54/ucon.data-model_v035.png align="center" alt="ucon Data Model" width=600/>
 ## Why `ucon`?
@@ -91,24 +93,22 @@ Python already has mature libraries for handling units and physical quantities
 | Library   | Focus                                                   | Limitation                                                                                                             |
 | --------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **Pint**  | Runtime unit conversion and compatibility checking      | Treats quantities as decorated numbers — conversions work, but the algebra behind them isn’t inspectable or type-safe. |
+| **Pint**  | Runtime unit conversion and compatibility checking      | Treats quantities as decorated numbers — conversions work, but the algebra behind them isn't inspectable or type-safe. |
 | **SymPy** | Symbolic algebra and simplification of unit expressions | Excellent for symbolic reasoning, but not designed for runtime validation, conversion, or serialization.               |
 | **Unum**  | Unit-aware arithmetic and unit propagation              | Tracks units through arithmetic but lacks explicit dimensional algebra, conversion taxonomy, or runtime introspection. |
 Together, these tools can _use_ units, but none can explicitly represent and verify the relationships between units and dimensions.
-That’s the gap `ucon` fills.
+That's the gap `ucon` fills.
 It treats units, dimensions, and scales as first-class objects and builds a composable algebra around them.
 This allows you to:
 - Represent dimensional meaning explicitly (`Dimension`, `Vector`);
 - Compose and compute with type-safe, introspectable quantities (`Unit`, `Number`);
-- Perform reversible, declarative conversions (standard, linear, affine, nonlinear);
-- Serialize and validate measurements with Pydantic integration;
 - Extend the system with custom unit registries and conversion families.
 Where Pint, Unum, and SymPy focus on _how_ to compute with units,
-`ucon` focuses on why those computations make sense. Every operation checks the dimensional structure, _not just the unit labels_. This means ucon doesn’t just track names: it enforces physics:
+`ucon` focuses on why those computations make sense. Every operation checks the dimensional structure, _not just the unit labels_. This means ucon doesn't just track names: it enforces physics:
 ```python
 from ucon import Number, units
@@ -136,7 +136,8 @@ This sort of dimensional analysis:
 ```
 becomes straightforward when you define a measurement:
 ```python
-from ucon import Number, Scale, Units, Ratio
+from ucon import Number, Scale, units
+from ucon.quantity import Ratio
 # Two milliliters of bromine
 mL = Scale.milli * units.liter
@@ -149,27 +150,36 @@ bromine_density = Ratio(
 )
 # Multiply to find mass
-grams_bromine = two_mL_bromine * bromine_density
-print(grams_bromine)  # <6.238 gram>
+grams_bromine = bromine_density.evaluate() * two_mL_bromine
+print(grams_bromine)  # <6.238 g>
 ```
-Scale conversion is automatic and precise:
+Scale prefixes compose naturally:
 ```python
-grams_bromine.to(Scale.milli)  # <6238.0 milligram>
-grams_bromine.to(Scale.kibi)   # <0.006091796875 kibigram>
+km = Scale.kilo * units.meter       # UnitProduct with kilo-scaled meter
+mg = Scale.milli * units.gram       # UnitProduct with milli-scaled gram
+print(km.shorthand)  # 'km'
+print(mg.shorthand)  # 'mg'
+# Scale arithmetic
+print(km.fold_scale())  # 1000.0
+print(mg.fold_scale())  # 0.001
 ```
+> **Note:** Unit _conversions_ (e.g., `number.to(units.inch)`) are planned for v0.4.x
+> via the `ConversionGraph` abstraction. See [ROADMAP.md](./ROADMAP.md).
 ---
 ## Roadmap Highlights
-| Version | Theme | Focus |
-|----------|-------|--------|
-| [**0.3.x**](https://github.com/withtwoemms/ucon/milestone/1) | Primitive Type Refinement | Unified algebraic foundation |
-| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | Linear & affine conversions |
-| [**0.6.x**](https://github.com/withtwoemms/ucon/milestone/4) | Nonlinear / Specialized Units | Decibel, Percent, pH |
-| [**0.8.x**](https://github.com/withtwoemms/ucon/milestone/6) | Pydantic Integration | Type-safe quantity validation |
+| Version | Theme | Focus | Status |
+|----------|-------|--------|--------|
+| **0.3.5** | Dimensional Algebra | Unit/Scale separation, `UnitFactor`, `UnitProduct` | ✅ Complete |
+| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | `ConversionGraph`, `Number.to()` | 🚧 Up Next |
+| [**0.6.x**](https://github.com/withtwoemms/ucon/milestone/4) | Nonlinear / Specialized Units | Decibel, Percent, pH | ⏳ Planned |
+| [**0.8.x**](https://github.com/withtwoemms/ucon/milestone/6) | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
 See full roadmap: [ROADMAP.md](./ROADMAP.md)
@@ -182,13 +192,13 @@ Ensure `nox` is installed.
 ```
 pip install -r requirements.txt
 ```
-Then run the full test suite (agains all supported python versions) before committing:
+Then run the full test suite (against all supported python versions) before committing:
 ```bash
 nox -s test
 ```
 ---
-> “If it can be measured, it can be represented.
+> "If it can be measured, it can be represented.
 If it can be represented, it can be validated.
-If it can be validated, it can be trusted.”
+If it can be validated, it can be trusted."

{ucon-0.3.5rc1 → ucon-0.3.5rc2}/README.md RENAMED Viewed

@@ -18,8 +18,8 @@
 It combines **units**, **scales**, and **dimensions** into a composable algebra that supports:
 - Dimensional analysis through `Number` and `Ratio`
-- Scale-aware arithmetic and conversions
-- Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, ect.)
+- Scale-aware arithmetic via `UnitFactor` and `UnitProduct`
+- Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, etc.)
 - A clean foundation for physics, chemistry, data modeling, and beyond
 Think of it as **`decimal.Decimal` for the physical world** — precise, predictable, and type-safe.
@@ -33,20 +33,22 @@ The crux of this tiny library is to provide abstractions that simplify the answe
 To best answer this question, we turn to an age-old technique ([dimensional analysis](https://en.wikipedia.org/wiki/Dimensional_analysis)) which essentially allows for the solution to be written as a product of ratios. `ucon` comes equipped with some useful primitives:
 | Type                          | Defined In                              | Purpose                                                                                             | Typical Use Cases                                                                                                      |
 | ----------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **`Vector`**                  | `ucon.dimension`                        | Represents the exponent tuple of a physical quantity’s base dimensions (e.g., T, L, M, I, Θ, J, N). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
-| **`Dimension`**               | `ucon.dimension`                        | Encapsulates physical dimensions (e.g., length, time, mass) as algebraic combinations of vectors.   | Enforcing dimensional consistency; defining relationships between quantities (e.g., length / time = velocity).         |
-| **`Unit`**                    | `ucon.unit`                             | Represents a named, dimensioned measurement unit (e.g., meter, second, joule).                      | Attaching human-readable units to quantities; defining or composing new units (`newton = kilogram * meter / second²`). |
+| **`Vector`**                  | `ucon.algebra`                          | Represents the exponent tuple of a physical quantity's base dimensions (e.g., T, L, M, I, Θ, J, N). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
+| **`Exponent`**                | `ucon.algebra`                          | Represents base-power pairs (e.g., 10³, 2¹⁰) used by `Scale`.                                       | Performing arithmetic on powers and bases; normalizing scales across conversions.                                      |
+| **`Dimension`**               | `ucon.core`                             | Encapsulates physical dimensions (e.g., length, time, mass) as algebraic combinations of vectors.   | Enforcing dimensional consistency; defining relationships between quantities (e.g., length / time = velocity).         |
 | **`Scale`**                   | `ucon.core`                             | Encodes powers of base magnitudes (binary or decimal prefixes like kilo-, milli-, mebi-).           | Adjusting numeric scale without changing dimension (e.g., kilometer ↔ meter, byte ↔ kibibyte).                         |
-| **`Exponent`**                | `ucon.core`                             | Represents base-power pairs (e.g., 10³, 2¹⁰) used by `Scale`.                                       | Performing arithmetic on powers and bases; normalizing scales across conversions.                                      |
-| **`Number`**                  | `ucon.core`                             | Combines a numeric quantity with a unit and scale; the primary measurable type.                     | Performing arithmetic with units; converting between compatible units; representing physical quantities like 5 m/s.    |
-| **`Ratio`**                   | `ucon.core`                             | Represents the division of two `Number` objects; captures relationships between quantities.         | Expressing rates, densities, efficiencies (e.g., energy / time = power, length / time = velocity).                     |
-| **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI and common derived units).                                     | Quick access to standard physical units (`units.meter`, `units.second`, `units.newton`, etc.).                               |                                                   |
+| **`Unit`**                    | `ucon.core`                             | An atomic, scale-free measurement symbol (e.g., meter, second, joule) with a `Dimension`.           | Defining base units; serving as graph nodes for future conversions.                                                    |
+| **`UnitFactor`**              | `ucon.core`                             | Pairs a `Unit` with a `Scale` (e.g., kilo + gram = kg). Used as keys inside `UnitProduct`.          | Preserving user-provided scale prefixes through algebraic operations.                                                  |
+| **`UnitProduct`**             | `ucon.core`                             | A product/quotient of `UnitFactor`s with exponent tracking and simplification.                      | Representing composite units like m/s, kg·m/s², kJ·h.                                                                 |
+| **`Number`**                  | `ucon.quantity`                         | Combines a numeric quantity with a unit; the primary measurable type.                               | Performing arithmetic with units; representing physical quantities like 5 m/s.                                         |
+| **`Ratio`**                   | `ucon.quantity`                         | Represents the division of two `Number` objects; captures relationships between quantities.         | Expressing rates, densities, efficiencies (e.g., energy / time = power, length / time = velocity).                     |
+| **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI and common derived units).                                     | Quick access to standard physical units (`units.meter`, `units.second`, `units.newton`, etc.).                          |
 ### Under the Hood
 `ucon` models unit math through a hierarchy where each layer builds on the last:
-<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/0c704737a52b9e4a87cda5c839e9aa40f7e5bb48/ucon.data-model_v035.png align="center" alt="ucon Data Model" width=600/>
+<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/f24134c362829dc72e7dff18bfcaa24b9be01b54/ucon.data-model_v035.png align="center" alt="ucon Data Model" width=600/>
 ## Why `ucon`?
@@ -54,24 +56,22 @@ Python already has mature libraries for handling units and physical quantities
 | Library   | Focus                                                   | Limitation                                                                                                             |
 | --------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **Pint**  | Runtime unit conversion and compatibility checking      | Treats quantities as decorated numbers — conversions work, but the algebra behind them isn’t inspectable or type-safe. |
+| **Pint**  | Runtime unit conversion and compatibility checking      | Treats quantities as decorated numbers — conversions work, but the algebra behind them isn't inspectable or type-safe. |
 | **SymPy** | Symbolic algebra and simplification of unit expressions | Excellent for symbolic reasoning, but not designed for runtime validation, conversion, or serialization.               |
 | **Unum**  | Unit-aware arithmetic and unit propagation              | Tracks units through arithmetic but lacks explicit dimensional algebra, conversion taxonomy, or runtime introspection. |
 Together, these tools can _use_ units, but none can explicitly represent and verify the relationships between units and dimensions.
-That’s the gap `ucon` fills.
+That's the gap `ucon` fills.
 It treats units, dimensions, and scales as first-class objects and builds a composable algebra around them.
 This allows you to:
 - Represent dimensional meaning explicitly (`Dimension`, `Vector`);
 - Compose and compute with type-safe, introspectable quantities (`Unit`, `Number`);
-- Perform reversible, declarative conversions (standard, linear, affine, nonlinear);
-- Serialize and validate measurements with Pydantic integration;
 - Extend the system with custom unit registries and conversion families.
 Where Pint, Unum, and SymPy focus on _how_ to compute with units,
-`ucon` focuses on why those computations make sense. Every operation checks the dimensional structure, _not just the unit labels_. This means ucon doesn’t just track names: it enforces physics:
+`ucon` focuses on why those computations make sense. Every operation checks the dimensional structure, _not just the unit labels_. This means ucon doesn't just track names: it enforces physics:
 ```python
 from ucon import Number, units
@@ -99,7 +99,8 @@ This sort of dimensional analysis:
 ```
 becomes straightforward when you define a measurement:
 ```python
-from ucon import Number, Scale, Units, Ratio
+from ucon import Number, Scale, units
+from ucon.quantity import Ratio
 # Two milliliters of bromine
 mL = Scale.milli * units.liter
@@ -112,27 +113,36 @@ bromine_density = Ratio(
 )
 # Multiply to find mass
-grams_bromine = two_mL_bromine * bromine_density
-print(grams_bromine)  # <6.238 gram>
+grams_bromine = bromine_density.evaluate() * two_mL_bromine
+print(grams_bromine)  # <6.238 g>
 ```
-Scale conversion is automatic and precise:
+Scale prefixes compose naturally:
 ```python
-grams_bromine.to(Scale.milli)  # <6238.0 milligram>
-grams_bromine.to(Scale.kibi)   # <0.006091796875 kibigram>
+km = Scale.kilo * units.meter       # UnitProduct with kilo-scaled meter
+mg = Scale.milli * units.gram       # UnitProduct with milli-scaled gram
+print(km.shorthand)  # 'km'
+print(mg.shorthand)  # 'mg'
+# Scale arithmetic
+print(km.fold_scale())  # 1000.0
+print(mg.fold_scale())  # 0.001
 ```
+> **Note:** Unit _conversions_ (e.g., `number.to(units.inch)`) are planned for v0.4.x
+> via the `ConversionGraph` abstraction. See [ROADMAP.md](./ROADMAP.md).
 ---
 ## Roadmap Highlights
-| Version | Theme | Focus |
-|----------|-------|--------|
-| [**0.3.x**](https://github.com/withtwoemms/ucon/milestone/1) | Primitive Type Refinement | Unified algebraic foundation |
-| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | Linear & affine conversions |
-| [**0.6.x**](https://github.com/withtwoemms/ucon/milestone/4) | Nonlinear / Specialized Units | Decibel, Percent, pH |
-| [**0.8.x**](https://github.com/withtwoemms/ucon/milestone/6) | Pydantic Integration | Type-safe quantity validation |
+| Version | Theme | Focus | Status |
+|----------|-------|--------|--------|
+| **0.3.5** | Dimensional Algebra | Unit/Scale separation, `UnitFactor`, `UnitProduct` | ✅ Complete |
+| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | `ConversionGraph`, `Number.to()` | 🚧 Up Next |
+| [**0.6.x**](https://github.com/withtwoemms/ucon/milestone/4) | Nonlinear / Specialized Units | Decibel, Percent, pH | ⏳ Planned |
+| [**0.8.x**](https://github.com/withtwoemms/ucon/milestone/6) | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
 See full roadmap: [ROADMAP.md](./ROADMAP.md)
@@ -145,13 +155,13 @@ Ensure `nox` is installed.
 ```
 pip install -r requirements.txt
 ```
-Then run the full test suite (agains all supported python versions) before committing:
+Then run the full test suite (against all supported python versions) before committing:
 ```bash
 nox -s test
 ```
 ---
-> “If it can be measured, it can be represented.
+> "If it can be measured, it can be represented.
 If it can be represented, it can be validated.
-If it can be validated, it can be trusted.”
+If it can be validated, it can be trusted."

{ucon-0.3.5rc1 → ucon-0.3.5rc2}/ROADMAP.md RENAMED Viewed

@@ -4,61 +4,68 @@
 ---
-## 🪜 Current Version: **v0.3.0**
+## 🪜 Current Version: **v0.3.5**
 Stable baseline for:
-- `ucon.core` (`Number`, `Scale`, `Ratio`)
-- `ucon.unit` (basic unit representation and composition)
+- `ucon.core` (`Dimension`, `Scale`, `Unit`, `UnitFactor`, `UnitProduct`)
+- `ucon.quantity` (`Number`, `Ratio`)
 - `ucon.units` (canonical SI definitions)
 - Initial CI, testing, and packaging
 ---
-## 🚀 v0.3.x — Dimensional Algebra (In Progress)
+## ✅ v0.3.x — Dimensional Algebra (Complete)
 ### 🔹 Summary
-> Introduces `ucon.dimension` as the foundation for algebraic reasoning.
+> Introduces dimensional algebra and establishes the Unit/Scale separation
+> that underpins all downstream work.
 ### ✅ Goals
-- [x] Implement `Vector` and `Dimension` classes
-- [x] Integrate dimensions into `Unit`
-- [x] Refactor `ucon.units` to use dimensional definitions
+- [x] Implement `Vector` and `Dimension` classes
+- [x] Integrate dimensions into `Unit`
+- [x] Refactor `ucon.units` to use dimensional definitions
 - [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
+- [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
 - [x] Add regression tests for prefix math (`kilo / milli → mega`, `2¹⁰ / 10³ → 1.024×`)
-- [ ] Document Exponent/Scale relationship in developer guide
+- [x] Separate `scale` from `Unit`; delegate to `UnitFactor(unit, scale)`
+- [x] Introduce `UnitProduct` with `fold_scale()` and `_residual_scale_factor`
+- [x] `Number.value` returns as-expressed magnitude; `_canonical_magnitude` folds scale internally
+- [x] Remove dead code and unify naming (`UnitFactor`, `UnitProduct`) across all docstrings and repr
 ### 🧩 Outcomes
-- All units acquire explicit dimensional semantics
-- 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ᵐ`)~
-- Simplified, consistent `Scale` and `Number` behavior
-- Ready for integration into the conversion engine (`ucon.conversions`)
+- All units acquire explicit dimensional semantics
+- Enables composable and type-safe dimensional operations
+- Establishes the mathematical foundation for future conversions
+- Unified algebraic foundation for all scaling and magnitude operations
+- Clean Unit/Scale separation: `Unit` is an atomic symbol, `UnitFactor` pairs it with a `Scale`
+- `UnitProduct` correctly tracks residual scale from cancelled units
+- Type system is ready for a `ConversionGraph` to be built on top
 ---
-## ⚙️ v0.4.x — Conversion System Foundations
+## ⚙️ v0.4.x — Conversion System Foundations (Up Next)
 ### 🔹 Summary
 > Implements unified conversion engine for standard, linear, and affine conversions.
 ### ✅ Goals
-- [ ] Introduce `ucon.conversions` registry keyed by `Dimension`
-- [ ] Add support for `standard`, `linear`, and `affine` conversion types
-- [ ] Implement `.to(target_unit)` for `Number`
-- [ ] Round-trip validation for reversible conversions
-- [ ] Extend tests to include temperature, pressure, and base SI conversions
+- [ ] Introduce `ConversionGraph` registry keyed by `Dimension`
+- [ ] Add support for `standard`, `linear`, and `affine` conversion types
+- [ ] Implement `Number.to(target_unit)` and `Number.simplify()`
+- [ ] Scale-only conversions short-circuit without graph lookup
+- [ ] Composite-to-composite conversion via per-component decomposition
+- [ ] Round-trip validation for reversible conversions
+- [ ] Extend tests to include temperature, pressure, and base SI conversions
+- [ ] Document Exponent/Scale relationship in developer guide
 ### 🧩 Outcomes
-- Unified conversion taxonomy
-- Reversible, dimension-checked conversions
-- Forms the basis for nonlinear and domain-specific conversion families
+- Unified conversion taxonomy
+- Reversible, dimension-checked conversions
+- Scale-aware graph that leverages the `Unit`/`UnitFactor` separation from v0.3.x
+- Forms the basis for nonlinear and domain-specific conversion families
 ---
@@ -68,16 +75,16 @@ Stable baseline for:
 > Introduces an extensible registry system for custom units and aliases.
 ### ✅ Goals
-- [x] Implement `have(name)` membership check
-- [ ] Add `UnitSystem` abstraction
-- [ ] Support `registry.add(unit)` and dynamic system registration
-- [ ] Validate alias uniqueness and collision prevention
-- [ ] Include examples for user-defined unit extensions
+- [x] Implement `have(name)` membership check
+- [ ] Add `UnitSystem` abstraction
+- [ ] Support `registry.add(unit)` and dynamic system registration
+- [ ] Validate alias uniqueness and collision prevention
+- [ ] Include examples for user-defined unit extensions
 ### 🧩 Outcomes
-- Registry-based extensibility for domain-specific systems
-- Dynamic unit registration and discovery
-- Groundwork for plugin-style system extensions
+- Registry-based extensibility for domain-specific systems
+- Dynamic unit registration and discovery
+- Groundwork for plugin-style system extensions
 ---
@@ -87,20 +94,20 @@ Stable baseline for:
 > Adds support for logarithmic, fractional, and other specialized dimensionless conversions.
 ### ✅ Goals
-- [ ] Extend conversion registry schema with `"nonlinear"` family
-- [ ] Add `to_base` / `from_base` lambdas for function-based mappings
-- [ ] Define sample nonlinear conversions (`decibel`, `bel`, `pH`)
-- [ ] Add tolerance-aware tests for nonlinear conversions
+- [ ] Extend conversion registry schema with `"nonlinear"` family
+- [ ] Add `to_base` / `from_base` lambdas for function-based mappings
+- [ ] Define sample nonlinear conversions (`decibel`, `bel`, `pH`)
+- [ ] Add tolerance-aware tests for nonlinear conversions
 - [ ] Introduce structured dimensionless unit family (`radian`, `percent`, `ppm`, `count`, etc.)
 - [ ] Define canonical dimensionless subtypes for angular, fractional, and count semantics
 - [ ] Ensure automatic collapse of equivalent units (`m/m → none`, `J/J → none`) via Ratio
 ### 🧩 Outcomes
-- Support for function-based (nonlinear) physical conversions
-- Unified algebraic framework across all conversion types
+- Support for function-based (nonlinear) physical conversions
+- Unified algebraic framework across all conversion types
 - Rich, semantically meaningful representation of dimensionless quantities
 - Enables acoustics (dB), geometry (rad, sr), statistics (probability), and fractional scales (%, ppm)
 ---
 ## 🧰 v0.7.x — Testing, Developer Experience, & API Polish
@@ -109,16 +116,16 @@ Stable baseline for:
 > Strengthens tests, developer ergonomics, and runtime feedback.
 ### ✅ Goals
-- [ ] Reach 95%+ test coverage
-- [ ] Add property-based tests for dimensional invariants
-- [ ] Improve error reporting, `__repr__`, and exception messaging
-- [ ] Validate public API imports and maintain consistent naming
-- [ ] Add CI coverage reports and build badges
+- [ ] Reach 95%+ test coverage
+- [ ] Add property-based tests for dimensional invariants
+- [ ] Improve error reporting, `__repr__`, and exception messaging
+- [ ] Validate public API imports and maintain consistent naming
+- [ ] Add CI coverage reports and build badges
 ### 🧩 Outcomes
-- Reliable, developer-friendly foundation
-- Consistent runtime behavior and output clarity
-- Prepares API for public documentation and 1.0 freeze
+- Reliable, developer-friendly foundation
+- Consistent runtime behavior and output clarity
+- Prepares API for public documentation and 1.0 freeze
 ---
@@ -128,16 +135,16 @@ Stable baseline for:
 > Introduces seamless integration with **Pydantic v2**, enabling validation, serialization, and typed dimensional models.
 ### ✅ Goals
-- [ ] Define Pydantic-compatible field types (`UnitType`, `NumberType`)
-- [ ] Implement `__get_pydantic_core_schema__` for Units and Numbers
-- [ ] Support automatic conversion/validation for user-defined models
-- [ ] Add YAML / JSON encoding for quantities (`Number(unit="meter", quantity=5)`)
-- [ ] Add Pydantic-based examples (API config, simulation parameters)
+- [ ] Define Pydantic-compatible field types (`UnitType`, `NumberType`)
+- [ ] Implement `__get_pydantic_core_schema__` for Units and Numbers
+- [ ] Support automatic conversion/validation for user-defined models
+- [ ] Add YAML / JSON encoding for quantities (`Number(unit="meter", quantity=5)`)
+- [ ] Add Pydantic-based examples (API config, simulation parameters)
 ### 🧩 Outcomes
-- Native validation and serialization for dimensioned quantities
-- Enables safe configuration in data models and APIs
-- Bridges `ucon`’s algebraic model with modern Python typing ecosystems
+- Native validation and serialization for dimensioned quantities
+- Enables safe configuration in data models and APIs
+- Bridges `ucon`'s algebraic model with modern Python typing ecosystems
 ---
@@ -147,16 +154,16 @@ Stable baseline for:
 > Completes documentation, finalizes examples, and preps release candidates.
 ### ✅ Goals
-- [ ] Write comprehensive README and developer guide
-- [ ] Publish API reference docs (Sphinx / MkDocs)
-- [ ] Add SymPy / Pint comparison appendix
-- [ ] Freeze and document all public APIs
-- [ ] Publish one or more release candidates (RC1, RC2)
+- [ ] Write comprehensive README and developer guide
+- [ ] Publish API reference docs (Sphinx / MkDocs)
+- [ ] Add SymPy / Pint comparison appendix
+- [ ] Freeze and document all public APIs
+- [ ] Publish one or more release candidates (RC1, RC2)
 ### 🧩 Outcomes
-- Complete public-facing documentation
-- API frozen and versioned for stability
-- Ready for final testing and validation before 1.0
+- Complete public-facing documentation
+- API frozen and versioned for stability
+- Ready for final testing and validation before 1.0
 ---
@@ -166,15 +173,15 @@ Stable baseline for:
 > First major release: a unified algebra for composable, type-safe, and semantically clear unit conversion.
 ### ✅ Goals
-- [ ] Tag and release to PyPI
-- [ ] Validate packaging and dependency metadata
-- [ ] Include examples and tutorials in docs
-- [ ] Announce 1.0 on GitHub and PyPI
+- [ ] Tag and release to PyPI
+- [ ] Validate packaging and dependency metadata
+- [ ] Include examples and tutorials in docs
+- [ ] Announce 1.0 on GitHub and PyPI
 ### 🧩 Outcomes
-- Stable, well-tested release
-- Fully type-safe and validated core
-- Production-ready for integration into scientific and engineering workflows
+- Stable, well-tested release
+- Fully type-safe and validated core
+- Production-ready for integration into scientific and engineering workflows
 ---
@@ -192,24 +199,24 @@ Stable baseline for:
 ## 🗓️ Milestone Summary
-| Version | Theme | Key Focus | Target | Status |
-|----------|--------|------------|---------|---------|
-| **0.3.0** | Dimensional Algebra | Introduce `ucon.dimension` | **Nov 2025** | 🚧 In Progress |
-| **0.4.0** | Conversion Engine | Standard, linear, affine conversions | **Jan 2026** | ⏳ Planned |
-| **0.5.0** | Unit Systems & Registries | Extensible registry system | **Mar 2026** | ⏳ Planned |
-| **0.6.0** | Nonlinear Conversions | Logarithmic / exponential families | **May 2026** | ⏳ Planned |
-| **0.7.0** | Testing & API Polish | Coverage, ergonomics, stability | **Jul 2026** | ⏳ Planned |
-| **0.8.0** | 🧩 **Pydantic Integration** | Typed validation, serialization | **Sep 2026** | 🧭 Newly Added |
-| **0.9.x** | Documentation & RC | Freeze API, publish docs, RCs | **Nov 2026** | ⏳ Planned |
-| **1.0.0** | Stable Release | Publish production-ready core | **Jan 2027** | 🔮 Future |
+| Version | Theme | Key Focus | Status |
+|----------|--------|------------|---------|
+| **0.3.5** | Dimensional Algebra | Unit/Scale separation, `UnitFactor`, `UnitProduct` | ✅ Complete |
+| **0.4.0** | Conversion Engine | `ConversionGraph`, `Number.to()`, scale-aware lookup | 🚧 Up Next |
+| **0.5.0** | Unit Systems & Registries | Extensible registry system | ⏳ Planned |
+| **0.6.0** | Nonlinear Conversions | Logarithmic / exponential families | ⏳ Planned |
+| **0.7.0** | Testing & API Polish | Coverage, ergonomics, stability | ⏳ Planned |
+| **0.8.0** | Pydantic Integration | Typed validation, serialization | ⏳ Planned |
+| **0.9.x** | Documentation & RC | Freeze API, publish docs, RCs | ⏳ Planned |
+| **1.0.0** | Stable Release | Publish production-ready core | 🔮 Future |
 ---
 ### ✨ Guiding Principle
-> “If it can be measured, it can be represented.
-> If it can be represented, it can be validated.
-> If it can be validated, it can be trusted.”
+> "If it can be measured, it can be represented.
+> If it can be represented, it can be validated.
+> If it can be validated, it can be trusted."
 ---
@@ -220,3 +227,4 @@ Stable baseline for:
   class Config(BaseModel):
       length: NumberType[Dimension.length]
       time: NumberType[Dimension.time]
+  ```

{ucon-0.3.5rc1 → ucon-0.3.5rc2}/ucon/core.py RENAMED Viewed

@@ -240,8 +240,7 @@ class Scale(Enum):
     def __mul__(self, other):
         # --- Case 1: applying Scale to simple Unit --------------------
-        if isinstance(other, Unit) and not isinstance(other, UnitProduct):
-            # Unit no longer has scale attribute - always safe to apply
+        if isinstance(other, Unit):
             return UnitProduct({UnitFactor(unit=other, scale=self): 1})
         # --- Case 2: other cases are NOT handled here -----------------
@@ -343,8 +342,6 @@ class Unit:
         Unit * Unit -> UnitProduct
         Unit * UnitProduct -> UnitProduct
         """
-        from ucon.core import UnitProduct  # local import to avoid circulars
         if isinstance(other, UnitProduct):
             # let UnitProduct handle merging
             return other.__rmul__(self)
@@ -356,12 +353,13 @@ class Unit:
     def __truediv__(self, other):
         """
-        Unit / Unit:
-          - If same unit => dimensionless Unit()
-          - If denominator is dimensionless => self
-          - Else => UnitProduct
+        Unit / Unit or Unit / UnitProduct => UnitProduct
         """
-        from ucon.core import UnitProduct  # local import
+        if isinstance(other, UnitProduct):
+            combined = {self: 1.0}
+            for u, exp in other.factors.items():
+                combined[u] = combined.get(u, 0.0) - exp
+            return UnitProduct(combined)
         if not isinstance(other, Unit):
             return NotImplemented
@@ -385,13 +383,13 @@ class Unit:
         """
         Unit ** n => UnitProduct with that exponent.
         """
-        from ucon.core import UnitProduct  # local import
         return UnitProduct({self: power})
     # ----------------- equality & hashing -----------------
     def __eq__(self, other):
+        if isinstance(other, UnitProduct):
+            return other.__eq__(self)
         if not isinstance(other, Unit):
             return NotImplemented
         return (
@@ -498,7 +496,7 @@ class UnitFactor:
         return NotImplemented
-class UnitProduct(Unit):
+class UnitProduct:
     """
     Represents a product or quotient of Units.
@@ -527,8 +525,7 @@ class UnitProduct(Unit):
         encountered UnitFactor (keeps user-intent scale).
         """
-        # UnitProduct always starts dimensionless
-        super().__init__(name="", dimension=Dimension.none)
+        self.name = ""
         self.aliases = ()
         merged: dict[UnitFactor, float] = {}
@@ -706,6 +703,16 @@ class UnitProduct(Unit):
             result *= factor.scale.value.evaluated ** power
         return result
+    # ------------- Helpers ---------------------------------------------------
+    def _norm(self, aliases: tuple[str, ...]) -> tuple[str, ...]:
+        """Normalize alias bag: drop empty/whitespace-only aliases."""
+        return tuple(a for a in aliases if a.strip())
+    def __pow__(self, power):
+        """UnitProduct ** n => new UnitProduct with scaled exponents."""
+        return UnitProduct({u: exp * power for u, exp in self.factors.items()})
     # ------------- Algebra ---------------------------------------------------
     def __mul__(self, other):
@@ -799,7 +806,7 @@ class UnitProduct(Unit):
         return f"<{self.__class__.__name__} {self.shorthand}>"
     def __eq__(self, other):
-        if isinstance(other, Unit) and not isinstance(other, UnitProduct):
+        if isinstance(other, Unit):
             # Only equal to a plain Unit if we have exactly that unit^1
             # Here, the tuple comparison will invoke UnitFactor.__eq__(Unit)
             # on the key when factors are keyed by UnitFactor.

{ucon-0.3.5rc1 → ucon-0.3.5rc2}/ucon/quantity.py RENAMED Viewed

@@ -43,7 +43,7 @@ class Number:
         <2.5 (m/s)>
     """
     quantity: Union[float, int] = 1.0
-    unit: Unit = units.none
+    unit: Union[Unit, UnitProduct] = units.none
     @property
     def value(self) -> float:

{ucon-0.3.5rc1 → ucon-0.3.5rc2}/ucon.egg-info/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.3.5rc1
+Version: 0.3.5rc2
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
@@ -55,8 +55,8 @@ Dynamic: summary
 It combines **units**, **scales**, and **dimensions** into a composable algebra that supports:
 - Dimensional analysis through `Number` and `Ratio`
-- Scale-aware arithmetic and conversions
-- Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, ect.)
+- Scale-aware arithmetic via `UnitFactor` and `UnitProduct`
+- Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, etc.)
 - A clean foundation for physics, chemistry, data modeling, and beyond
 Think of it as **`decimal.Decimal` for the physical world** — precise, predictable, and type-safe.
@@ -70,20 +70,22 @@ The crux of this tiny library is to provide abstractions that simplify the answe
 To best answer this question, we turn to an age-old technique ([dimensional analysis](https://en.wikipedia.org/wiki/Dimensional_analysis)) which essentially allows for the solution to be written as a product of ratios. `ucon` comes equipped with some useful primitives:
 | Type                          | Defined In                              | Purpose                                                                                             | Typical Use Cases                                                                                                      |
 | ----------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **`Vector`**                  | `ucon.dimension`                        | Represents the exponent tuple of a physical quantity’s base dimensions (e.g., T, L, M, I, Θ, J, N). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
-| **`Dimension`**               | `ucon.dimension`                        | Encapsulates physical dimensions (e.g., length, time, mass) as algebraic combinations of vectors.   | Enforcing dimensional consistency; defining relationships between quantities (e.g., length / time = velocity).         |
-| **`Unit`**                    | `ucon.unit`                             | Represents a named, dimensioned measurement unit (e.g., meter, second, joule).                      | Attaching human-readable units to quantities; defining or composing new units (`newton = kilogram * meter / second²`). |
+| **`Vector`**                  | `ucon.algebra`                          | Represents the exponent tuple of a physical quantity's base dimensions (e.g., T, L, M, I, Θ, J, N). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
+| **`Exponent`**                | `ucon.algebra`                          | Represents base-power pairs (e.g., 10³, 2¹⁰) used by `Scale`.                                       | Performing arithmetic on powers and bases; normalizing scales across conversions.                                      |
+| **`Dimension`**               | `ucon.core`                             | Encapsulates physical dimensions (e.g., length, time, mass) as algebraic combinations of vectors.   | Enforcing dimensional consistency; defining relationships between quantities (e.g., length / time = velocity).         |
 | **`Scale`**                   | `ucon.core`                             | Encodes powers of base magnitudes (binary or decimal prefixes like kilo-, milli-, mebi-).           | Adjusting numeric scale without changing dimension (e.g., kilometer ↔ meter, byte ↔ kibibyte).                         |
-| **`Exponent`**                | `ucon.core`                             | Represents base-power pairs (e.g., 10³, 2¹⁰) used by `Scale`.                                       | Performing arithmetic on powers and bases; normalizing scales across conversions.                                      |
-| **`Number`**                  | `ucon.core`                             | Combines a numeric quantity with a unit and scale; the primary measurable type.                     | Performing arithmetic with units; converting between compatible units; representing physical quantities like 5 m/s.    |
-| **`Ratio`**                   | `ucon.core`                             | Represents the division of two `Number` objects; captures relationships between quantities.         | Expressing rates, densities, efficiencies (e.g., energy / time = power, length / time = velocity).                     |
-| **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI and common derived units).                                     | Quick access to standard physical units (`units.meter`, `units.second`, `units.newton`, etc.).                               |                                                   |
+| **`Unit`**                    | `ucon.core`                             | An atomic, scale-free measurement symbol (e.g., meter, second, joule) with a `Dimension`.           | Defining base units; serving as graph nodes for future conversions.                                                    |
+| **`UnitFactor`**              | `ucon.core`                             | Pairs a `Unit` with a `Scale` (e.g., kilo + gram = kg). Used as keys inside `UnitProduct`.          | Preserving user-provided scale prefixes through algebraic operations.                                                  |
+| **`UnitProduct`**             | `ucon.core`                             | A product/quotient of `UnitFactor`s with exponent tracking and simplification.                      | Representing composite units like m/s, kg·m/s², kJ·h.                                                                 |
+| **`Number`**                  | `ucon.quantity`                         | Combines a numeric quantity with a unit; the primary measurable type.                               | Performing arithmetic with units; representing physical quantities like 5 m/s.                                         |
+| **`Ratio`**                   | `ucon.quantity`                         | Represents the division of two `Number` objects; captures relationships between quantities.         | Expressing rates, densities, efficiencies (e.g., energy / time = power, length / time = velocity).                     |
+| **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI and common derived units).                                     | Quick access to standard physical units (`units.meter`, `units.second`, `units.newton`, etc.).                          |
 ### Under the Hood
 `ucon` models unit math through a hierarchy where each layer builds on the last:
-<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/0c704737a52b9e4a87cda5c839e9aa40f7e5bb48/ucon.data-model_v035.png align="center" alt="ucon Data Model" width=600/>
+<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/f24134c362829dc72e7dff18bfcaa24b9be01b54/ucon.data-model_v035.png align="center" alt="ucon Data Model" width=600/>
 ## Why `ucon`?
@@ -91,24 +93,22 @@ Python already has mature libraries for handling units and physical quantities
 | Library   | Focus                                                   | Limitation                                                                                                             |
 | --------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **Pint**  | Runtime unit conversion and compatibility checking      | Treats quantities as decorated numbers — conversions work, but the algebra behind them isn’t inspectable or type-safe. |
+| **Pint**  | Runtime unit conversion and compatibility checking      | Treats quantities as decorated numbers — conversions work, but the algebra behind them isn't inspectable or type-safe. |
 | **SymPy** | Symbolic algebra and simplification of unit expressions | Excellent for symbolic reasoning, but not designed for runtime validation, conversion, or serialization.               |
 | **Unum**  | Unit-aware arithmetic and unit propagation              | Tracks units through arithmetic but lacks explicit dimensional algebra, conversion taxonomy, or runtime introspection. |
 Together, these tools can _use_ units, but none can explicitly represent and verify the relationships between units and dimensions.
-That’s the gap `ucon` fills.
+That's the gap `ucon` fills.
 It treats units, dimensions, and scales as first-class objects and builds a composable algebra around them.
 This allows you to:
 - Represent dimensional meaning explicitly (`Dimension`, `Vector`);
 - Compose and compute with type-safe, introspectable quantities (`Unit`, `Number`);
-- Perform reversible, declarative conversions (standard, linear, affine, nonlinear);
-- Serialize and validate measurements with Pydantic integration;
 - Extend the system with custom unit registries and conversion families.
 Where Pint, Unum, and SymPy focus on _how_ to compute with units,
-`ucon` focuses on why those computations make sense. Every operation checks the dimensional structure, _not just the unit labels_. This means ucon doesn’t just track names: it enforces physics:
+`ucon` focuses on why those computations make sense. Every operation checks the dimensional structure, _not just the unit labels_. This means ucon doesn't just track names: it enforces physics:
 ```python
 from ucon import Number, units
@@ -136,7 +136,8 @@ This sort of dimensional analysis:
 ```
 becomes straightforward when you define a measurement:
 ```python
-from ucon import Number, Scale, Units, Ratio
+from ucon import Number, Scale, units
+from ucon.quantity import Ratio
 # Two milliliters of bromine
 mL = Scale.milli * units.liter
@@ -149,27 +150,36 @@ bromine_density = Ratio(
 )
 # Multiply to find mass
-grams_bromine = two_mL_bromine * bromine_density
-print(grams_bromine)  # <6.238 gram>
+grams_bromine = bromine_density.evaluate() * two_mL_bromine
+print(grams_bromine)  # <6.238 g>
 ```
-Scale conversion is automatic and precise:
+Scale prefixes compose naturally:
 ```python
-grams_bromine.to(Scale.milli)  # <6238.0 milligram>
-grams_bromine.to(Scale.kibi)   # <0.006091796875 kibigram>
+km = Scale.kilo * units.meter       # UnitProduct with kilo-scaled meter
+mg = Scale.milli * units.gram       # UnitProduct with milli-scaled gram
+print(km.shorthand)  # 'km'
+print(mg.shorthand)  # 'mg'
+# Scale arithmetic
+print(km.fold_scale())  # 1000.0
+print(mg.fold_scale())  # 0.001
 ```
+> **Note:** Unit _conversions_ (e.g., `number.to(units.inch)`) are planned for v0.4.x
+> via the `ConversionGraph` abstraction. See [ROADMAP.md](./ROADMAP.md).
 ---
 ## Roadmap Highlights
-| Version | Theme | Focus |
-|----------|-------|--------|
-| [**0.3.x**](https://github.com/withtwoemms/ucon/milestone/1) | Primitive Type Refinement | Unified algebraic foundation |
-| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | Linear & affine conversions |
-| [**0.6.x**](https://github.com/withtwoemms/ucon/milestone/4) | Nonlinear / Specialized Units | Decibel, Percent, pH |
-| [**0.8.x**](https://github.com/withtwoemms/ucon/milestone/6) | Pydantic Integration | Type-safe quantity validation |
+| Version | Theme | Focus | Status |
+|----------|-------|--------|--------|
+| **0.3.5** | Dimensional Algebra | Unit/Scale separation, `UnitFactor`, `UnitProduct` | ✅ Complete |
+| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | `ConversionGraph`, `Number.to()` | 🚧 Up Next |
+| [**0.6.x**](https://github.com/withtwoemms/ucon/milestone/4) | Nonlinear / Specialized Units | Decibel, Percent, pH | ⏳ Planned |
+| [**0.8.x**](https://github.com/withtwoemms/ucon/milestone/6) | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
 See full roadmap: [ROADMAP.md](./ROADMAP.md)
@@ -182,13 +192,13 @@ Ensure `nox` is installed.
 ```
 pip install -r requirements.txt
 ```
-Then run the full test suite (agains all supported python versions) before committing:
+Then run the full test suite (against all supported python versions) before committing:
 ```bash
 nox -s test
 ```
 ---
-> “If it can be measured, it can be represented.
+> "If it can be measured, it can be represented.
 If it can be represented, it can be validated.
-If it can be validated, it can be trusted.”
+If it can be validated, it can be trusted."