feat: non-negative quantities support added

Resolves #468

Author: mpusz

docs/blog/posts/quantity-point-bounds.md …posts/range-validated-quantity-points.mddocs/blog/posts/quantity-point-bounds.md renamed to docs/blog/posts/range-validated-quantity-points.md docs/blog/posts/quantity-point-bounds.md renamed to docs/blog/posts/range-validated-quantity-points.md

@@ -29,14 +29,6 @@ polymorphism.
 This article describes the motivation in depth, the design we arrived at, and
 the open questions we would love the community's help to answer.
 
-!!! note "Work in progress"
-
-    This feature is shipping in the current development version of **mp-units**.
-    We are planning a further extension for **non-negative quantity annotations**
-    (quantities that live on a ratio scale and are always ≥ 0, such as _mass_,
-    _duration_, or _electric charge_). That extension will be covered in a
-    follow-up article once the implementation is complete.
-
 <!-- more -->
 
 ## The Problem
@@ -230,7 +222,7 @@ parent's bounds:
 // static_assert fires at compile time if relative bounds exceed parent bounds
 template<>
 inline constexpr auto mp_units::quantity_bounds<ac_setpoint> =
-    mp_units::clamp_to_range{delta<deg_C>(-3), delta<deg_C>(+3)};
+    clamp_to_range{delta<deg_C>(-3), delta<deg_C>(+3)};
     // ❌ compile error if this would violate the parent origin's physical bounds
 ```
 
@@ -245,7 +237,7 @@ instantiated by enforcing the following, in order:
    by the cumulative offset) must nest strictly inside the parent's range.
 
 Both checks are **compile-time** `static_assert`s. They fire exactly once per
-specialisation regardless of how many `quantity_point` variables are constructed.
+specialization regardless of how many `quantity_point` variables are constructed.
 
 ### Full example: geodetic coordinate types
 
@@ -264,7 +256,7 @@ inline constexpr struct equator final : absolute_point_origin<geo_latitude>  {}
 inline constexpr struct prime_meridian final : absolute_point_origin<geo_longitude> {} prime_meridian;
 ```
 
-Outside the anonymous namespace (so the specialisations have external linkage):
+Outside the anonymous namespace (so the specializations have external linkage):
 
 ```cpp
 template<>
@@ -419,6 +411,47 @@ guarantees described above apply here too: you could use `constrained<float>` or
 `constrained<int>` as the representation without changing the
 `quantity_bounds` specialization.
 
+### Non-negative quantity annotations
+
+[Absolute quantities](introducing-absolute-quantities.md) are quantities that
+live on a ratio scale — always measured from a natural zero — such as _mass_,
+_duration_, or _electric charge magnitude_. Non-negativity is the canonical
+constraint for all of them, and **mp-units** now implements it at the
+quantity-specification level.
+
+The `non_negative` flag can be applied to any real-scalar base or named child
+quantity spec, and the library propagates the flag transitively: a quantity
+derived from two non-negative specs is itself non-negative.
+
+```cpp
+static_assert(is_non_negative(isq::length));     // ✅ tagged in ISQ system definition
+static_assert(is_non_negative(isq::mass));       // ✅ tagged in ISQ system definition
+static_assert(is_non_negative(isq::speed));      // ✅ derived: length / duration
+static_assert(!is_non_negative(isq::velocity));  // ❌ vector character — excluded
+```
+
+!!! note
+
+    `kind_of<QS>` is **never** non-negative, even when `QS` itself is tagged `non_negative`,
+    because `kind_of<QS>` represents the entire quantity tree including vector quantities
+    and signed coordinates. This matters when using CTAD with bare SI units:
+
+    ```cpp
+    quantity_point generic{5.0 * m};  // origin uses kind_of<isq::length> — NOT auto-bounded
+    quantity_point dist{distance_traveled(5.0 * m)};  // uses isq::distance — auto-bounded
+    ```
+
+When a `quantity_point` uses a `natural_point_origin` whose quantity spec is
+non-negative, the library **automatically attaches `check_non_negative`** as the
+bounds policy — no explicit `quantity_bounds` specialization is needed. The
+default can always be overridden:
+
+```cpp
+// Override the auto-applied check_non_negative with a clamping policy instead:
+template<>
+inline constexpr auto mp_units::quantity_bounds<natural_point_origin<isq::length>> = clamp_non_negative{};
+```
+
 ---
 
 ## Design Trade-offs and Open Questions
@@ -432,18 +465,12 @@ misleading (there is no "smallest" longitude on a wrapped circle; they're all
 equivalent modulo 360°). The current implementation does return `min` and `max`
 for all policy types that expose these members.
 
-### Should `quantity_bounds` be supported on absolute quantities?
-
-[Absolute quantities](introducing-absolute-quantities.md) are quantities that
-live on a ratio scale — always measured from a natural zero — such as _mass_,
-_duration_, or _electric current magnitude_. Non-negativity is the canonical
-constraint for them and will be addressed by a dedicated language-level
-annotation in a future **mp-units** release.
+### Should `quantity_bounds` be applied to application-level absolute quantity ranges?
 
-Beyond non-negativity, do you see real use cases for attaching
-_application-specific_ bounds to absolute quantities directly — for example,
-clamping a sensor's mass reading to its physical measurement range, or bounding
-a duration to a maximum scheduling window?
+Beyond the automatic non-negativity enforcement described above, do you see real
+use cases for attaching _application-specific_ range bounds to absolute quantities
+directly — for example, clamping a sensor's _mass_ reading to its physical
+measurement range, or bounding a _duration_ to a maximum scheduling window?
 
 ---
 
@@ -460,7 +487,7 @@ domain, we would love to hear from you:
 - Did the design make your use case straightforward to express?
 - Were there cases where you reached for bounds but the current design would not
   cover them?
-- Do you have strong opinions on the open questions above?
+- Do you have a view on either of the two open questions above?
 
 Please join the conversation in the
 [GitHub Discussions](https://github.com/mpusz/mp-units/discussions) or open a
@@ -470,14 +497,15 @@ Please join the conversation in the
 
 ## Summary
 
-|                                                 | Before                | After                               |
-|-------------------------------------------------|-----------------------|-------------------------------------|
-| Latitude type enforces pole constraint          | ❌ user responsibility | ✅ compile-time, zero-overhead       |
-| Longitude wraps cyclically                      | ❌ manual modulo       | ✅ `wrap_to_range` on origin         |
-| Sensor range clamped at API boundary            | ❌ runtime if-else     | ✅ policy on origin                  |
-| Relative origin inherits parent bounds          | ❌ impossible          | ✅ automatic, static-checked nesting |
-| `min()`/`max()`/`numeric_limits` reflect bounds | ❌ reports type limits | ✅ reports domain limits             |
-| Half-line (non-negative) bounds                 | ❌ impossible          | ✅ custom policy with `.min` only    |
+|                                                 | Before                | After                                                  |
+|-------------------------------------------------|-----------------------|--------------------------------------------------------|
+| Latitude type enforces pole constraint          | ❌ user responsibility | ✅ compile-time, zero-overhead                          |
+| Longitude wraps cyclically                      | ❌ manual modulo       | ✅ `wrap_to_range` on origin                            |
+| Sensor range clamped at API boundary            | ❌ runtime if-else     | ✅ policy on origin                                     |
+| Relative origin inherits parent bounds          | ❌ impossible          | ✅ automatic, static-checked nesting                    |
+| `min()`/`max()`/`numeric_limits` reflect bounds | ❌ reports type limits | ✅ reports domain limits                                |
+| Half-line (non-negative) bounds                 | ❌ impossible          | ✅ `check_non_negative` / `clamp_non_negative` policies |
+| Non-negative QS auto-guards natural origins     | ❌ impossible          | ✅ automatic, no specialization needed                  |
 
 The implementation is already merged and covered by a comprehensive compile-time
 test suite. Documentation lives in the

docs/blog/posts/understanding-safety-levels.md

@@ -460,6 +460,59 @@ delays.emplace_back(42, us);   // ✅ OK
 
 There is no construction path that silently discards unit information.
 
+### Non-Negative Quantity Tracking
+
+Beyond numeric representation, **mp-units** also encodes domain constraints at the quantity
+specification level. Many physical quantities are inherently non-negative: _length_, _mass_,
+_duration_, _thermodynamic temperature_, _amount of substance_, and _luminous intensity_ can
+never be negative. The ISQ base quantity definitions in **mp-units** carry this fact as a
+compile-time property:
+
+```cpp
+static_assert(is_non_negative(isq::length));
+static_assert(is_non_negative(isq::mass));
+static_assert(is_non_negative(isq::duration));
+static_assert(!is_non_negative(isq::electric_current));  // can be negative
+```
+
+This property **propagates through derived equations** and is automatically inherited by
+named real-scalar children — if all factors in a multiplication or division are
+non-negative, the result is too, and any named specialization that does not change the
+quantity character carries the constraint forward:
+
+```cpp
+static_assert(is_non_negative(isq::speed));      // length / duration — both non-negative
+static_assert(is_non_negative(isq::area));       // length * length — both non-negative
+static_assert(is_non_negative(isq::distance));   // named real-scalar child of length
+static_assert(!is_non_negative(isq::velocity));  // vector character — excluded from inheritance
+```
+
+!!! note
+
+    `kind_of<QS>` is **never** non-negative, even when `QS` itself is tagged `non_negative`,
+    because `kind_of<QS>` represents the entire quantity tree including vector quantities
+    and signed coordinates. This matters when using CTAD with bare SI units:
+
+    ```cpp
+    quantity_point generic{5.0 * m};                  // origin uses kind_of<isq::length> — NOT auto-bounded
+    quantity_point dist{distance_traveled(5.0 * m)};  // uses isq::distance — auto-bounded
+    ```
+
+This metadata is automatically enforced at runtime for `quantity_point` types: when a
+`quantity_point` uses a natural origin and the associated quantity spec is non-negative,
+the library automatically attaches a `check_non_negative` policy — no explicit
+`quantity_bounds` specialization is needed. You can still override the default by
+providing a full specialization before the type is first instantiated:
+
+```cpp
+// Replace error-on-negative with silent clamp-to-zero (e.g., for FP rounding noise):
+template<>
+inline constexpr auto mp_units::quantity_bounds<natural_point_origin<isq::length>> = clamp_non_negative{};
+```
+
+The metadata is also available for tooling, documentation, and static analysis — for
+example, to automatically select signed vs. unsigned representations.
+
 ### Bounded Quantity Points
 
 Representation safety also extends to **quantity points** (Level 6). The library's
@@ -479,13 +532,18 @@ using latitude = quantity_point<geo_latitude[deg], equator>;
 latitude lat{95.0 * deg};  // reflects to 85° (boundary mirror)
 ```
 
-The library ships four overflow policies (`check_in_range`, `clamp_to_range`,
-`wrap_to_range`, `reflect_in_range`), and the interface is extensible — you can write
-your own policy (e.g. a `clamp_bottom` for halflines that only enforce a lower bound)
+The library ships six overflow policies (`check_in_range`, `clamp_to_range`,
+`wrap_to_range`, `reflect_in_range`, `check_non_negative`, `clamp_non_negative`),
+and the interface is extensible — you can write your own policy (e.g. a one-sided policy
+for custom bounds that are neither zero-based nor symmetric)
 as long as it provides `V operator()(V)`. Combined with the `constrained<T, ErrorPolicy>`
 wrapper described above, `check_in_range` provides **guaranteed enforcement** in every
 build mode — not just debug builds.
 
+`check_non_negative` and `clamp_non_negative` are specifically designed for halflines
+`[0, +∞)`: the former reports a violation when the value is negative, while the latter
+silently clamps negative values to zero.
+
 For the complete walkthrough, see
 [Range-Validated Quantity Points](../../users_guide/framework_basics/the_affine_space.md#range-validated-quantity-points)
 (including [Custom Policies](../../users_guide/framework_basics/the_affine_space.md#custom-policies-one-sided-bounds))

docs/getting_started/safety_features.md

@@ -147,6 +147,58 @@ latitude lat{95.0 * deg, equator};  // throws std::domain_error (out of [-90, 90
     [Representation Types: `constraint_violation_handler`](../users_guide/framework_basics/representation_types.md#constraint-violation-handler).
 
 
+### Non-Negative Quantities
+
+The library also tracks which physical quantities are inherently non-negative (e.g.,
+_length_, _mass_, _duration_) through the type system. This property propagates through
+derived equations and is automatically inherited by named real-scalar children:
+
+```cpp
+static_assert(is_non_negative(isq::length));      // ✅ Tagged in ISQ definitions
+static_assert(is_non_negative(isq::mass));        // ✅ Tagged in ISQ definitions
+static_assert(is_non_negative(isq::distance));    // ✅ Named real-scalar child of length
+static_assert(is_non_negative(isq::speed));       // ✅ Derived: length / duration
+static_assert(!is_non_negative(isq::velocity));   // ❌ Vector character — excluded from inheritance
+```
+
+!!! question "How is non-negativity enforced?"
+
+    Non-negativity is enforced at **two levels**:
+
+    **Compile time (always)**
+    :   The `non_negative` flag is tracked in the type system and propagated through
+        dimensional equations, so the compiler knows whether any derived quantity is
+        non-negative.
+
+    **Runtime (automatic for `quantity_point` with a natural origin)**
+    :   Every `quantity_point` whose reference is rooted at the natural point origin of a
+        non-negative quantity spec automatically has `check_non_negative` bounds attached.
+        This means construction of, or arithmetic on, such a point checks the value:
+
+        - If the representation type has a
+          [`constraint_violation_handler`](../users_guide/framework_basics/representation_types.md#constraint-violation-handler)
+          specialization (e.g., a `constrained<T, Policy>` rep), the handler is invoked on
+          violation — behaviour is guaranteed regardless of build mode.
+        - For plain types (like `double`) the library falls back to
+          [`MP_UNITS_EXPECTS`](../how_to_guides/integration/wide_compatibility.md#contract-checking-macros),
+          which may be disabled in release builds.
+
+        You can override the default policy for a specific quantity spec by providing a
+        full specialization of `quantity_bounds` before the point type is first used:
+
+        ```cpp
+        // Replace error-on-negative with silent clamp-to-zero (e.g., for FP noise):
+        template<>
+        inline constexpr auto mp_units::quantity_bounds<natural_point_origin<isq::length>> = clamp_non_negative{};
+        ```
+
+        See [Tutorial: Custom Contract Handlers](../tutorials/affine_space/custom_contract_handlers.md)
+        for a step-by-step guide to implementing custom error policies with `constrained<T, ErrorPolicy>`.
+
+    For quantities modeled only as a `quantity` displacement (not as a `quantity_point`),
+    non-negativity remains a compile-time property only.
+
+
 ## Level 4: Quantity Kind Safety
 
 **Quantity kind safety** distinguishes between quantities that share the same dimension but

docs/how_to_guides/advanced_usage/ultimate_safety.md

@@ -7,7 +7,7 @@ or compiler optimization level.
 !!! tip "Background reading"
 
     For in-depth background on how `quantity_bounds` and overflow policies work, see
-    [Range-Validated Quantity Points](../../blog/posts/quantity-point-bounds.md).
+    [Range-Validated Quantity Points](../../blog/posts/range-validated-quantity-points.md).
 
 ## The Problem
 
@@ -119,14 +119,12 @@ release-with-debug-info.
 !!! tip "Extensible policy interface"
 
     The `quantity_bounds` customization point accepts any callable policy with the
-    signature `V operator()(V)`. The library ships four built-in policies, but you
-    can write your own — for example a `clamp_bottom` for halflines that only enforce
-    a lower bound, or a domain-specific policy that logs and corrects invalid readings.
-    As long as your policy's `operator()` returns the (possibly adjusted) value,
-    it will integrate seamlessly with the `quantity_point` enforcement machinery.
-
-    See [Custom Policies](../../users_guide/framework_basics/the_affine_space.md#custom-policies-one-sided-bounds)
-    for a complete example of implementing one-sided bound constraints.
+    signature `V operator()(V)`. The library ships six built-in policies — `check_in_range`,
+    `clamp_to_range`, `wrap_to_range`, `reflect_in_range`, `check_non_negative`, and
+    `clamp_non_negative` — and the interface is fully extensible. `check_non_negative` and
+    `clamp_non_negative` cover the common `[0, +∞)` halfline case; they are also applied
+    automatically to natural origins of non-negative ISQ quantity specs. For a fully custom
+    one-sided or asymmetric policy, see [Custom Policies](../../users_guide/framework_basics/the_affine_space.md#custom-policies-one-sided-bounds).
 
 ## How It Works?
 

docs/reference/systems_reference/.cache.json

@@ -1,3 +1,3 @@
 {
-  "source_hash": "d2564890eceb1ea7a6c23336abea40ab1620cdbeec04c5053dca9269ab3c2db0"
+  "source_hash": "9c87a9964988ae7923d976586ab277ceb5c328a96621b6baab79786fe6becbdc"
 }

docs/reference/systems_reference/hierarchies/index.md

@@ -30,7 +30,7 @@ This section contains all quantity hierarchy trees across all systems, grouped b
 ## Dimension: L
 
 - [`hep::length`](length_hep.md) (16 quantities)
-- [`isq::length`](length_isq.md) (13 quantities)
+- [`isq::length`](length_isq.md) (14 quantities)
 
 ## Dimension: M
 
@@ -53,7 +53,7 @@ This section contains all quantity hierarchy trees across all systems, grouped b
 ## Dimension: Θ
 
 - [`hep::temperature`](temperature.md) (1 quantity)
-- [`isq::thermodynamic_temperature`](thermodynamic_temperature.md) (3 quantities)
+- [`isq::thermodynamic_temperature`](thermodynamic_temperature.md) (2 quantities)
 
 ## Dimension: α