feat(quantities): canonical IPhysicalQuantity surface + typed In() (closes #59)

Implement the IPhysicalQuantity<T> contract decided in #59 with compile-time
dimension safety on unit conversion.

Runtime:
- IPhysicalQuantity<T> now exposes Dimension (DimensionInfo), IComparable, and
  IEquatable; CompareTo throws on cross-dimension comparison, Equals returns
  false (equality is total).
- IUnit gains Name/Symbol/Dimension/ToBaseFactor/ToBaseOffset plus default
  ToBase<T>/FromBase<T> methods over the affine conversion.
- New UnitConversionException type (reserved for any future untyped path).

Generator:
- DimensionsGenerator emits a marker interface per dimension (I{Dim}Unit : IUnit)
  so units can be dimensionally typed at compile time.
- UnitsGenerator now combines units.json with dimensions.json so each unit
  implements the correct I{Dim}Unit marker(s); emits class records (not structs)
  with full property surface (folding metric magnitude + conversionFactor into
  ToBaseFactor) plus a static Units catalogue of singletons.
- QuantitiesGenerator emits Dimension override + typed In(I{Dim}Unit) on every
  V0/V1 base and overload type. Cross-dimension In() calls fail to compile.

Tests + docs:
- PhysicalQuantityCoreTests rewritten against the new compile-time API.
- docs/architecture.md documents the IPhysicalQuantity contract and the typed
  In(I{Dim}Unit) pattern.

The previously aspirational test's runtime "should throw UnitConversionException"
case is now expressed at compile time (length.In(Units.Kilogram) doesn't build).

V2/V3/V4 vector types don't implement IPhysicalQuantity and are out of scope
for In() — per-component conversion is left as follow-up work.

https://claude.ai/code/session_01LqtywMUn5GwFATD5FDdLn6

Author: claude

Semantics.Quantities/IPhysicalQuantity.cs

@@ -4,18 +4,32 @@
 
 namespace ktsu.Semantics.Quantities;
 
+using System;
 using System.Numerics;
 
 /// <summary>
-/// Base interface for all physical quantities with compile-time type safety.
+/// Common surface for every physical quantity. Exposes the underlying
+/// <see cref="Value"/>, a structural validity check, the <see cref="Dimension"/>
+/// the quantity belongs to, and same-dimension comparison.
 /// </summary>
-/// <typeparam name="T">The storage type for the quantity value (e.g., double, float, decimal).</typeparam>
-public interface IPhysicalQuantity<T> : ISemanticQuantity<T>
+/// <remarks>
+/// Concrete generated quantity types also expose a dimensionally-typed
+/// <c>In(I&lt;Dim&gt;Unit)</c> method — kept off this interface so cross-dimension
+/// comparison via the slim contract stays compile-time clean.
+/// </remarks>
+/// <typeparam name="T">The storage type for the quantity value.</typeparam>
+public interface IPhysicalQuantity<T>
+	: ISemanticQuantity<T>
+	, IComparable<IPhysicalQuantity<T>>
+	, IEquatable<IPhysicalQuantity<T>>
 	where T : struct, INumber<T>
 {
-	/// <summary>Gets the value stored in this quantity.</summary>
-	public T Value { get; }
+	/// <summary>Gets the value stored in this quantity (in the dimension's SI base unit).</summary>
+	T Value { get; }
 
-	/// <summary>Gets whether this quantity satisfies physical constraints (e.g., finite, non-NaN).</summary>
-	public bool IsPhysicallyValid { get; }
+	/// <summary>Gets whether this quantity satisfies structural physical constraints (finite, non-NaN).</summary>
+	bool IsPhysicallyValid { get; }
+
+	/// <summary>Gets the physical dimension this quantity belongs to.</summary>
+	DimensionInfo Dimension { get; }
 }

Semantics.Quantities/IUnit.cs

@@ -4,7 +4,52 @@
 
 namespace ktsu.Semantics.Quantities;
 
+using System.Numerics;
+
 /// <summary>
-/// Interface for all physical units.
+/// Common surface for every physical unit. Carries the unit's name, symbol,
+/// the <see cref="DimensionInfo"/> it belongs to, and the affine conversion
+/// (<c>base = value × ToBaseFactor + ToBaseOffset</c>) that maps values in
+/// this unit to the SI base unit of the dimension.
 /// </summary>
-public interface IUnit { }
+/// <remarks>
+/// <para>
+/// For dimensional compile-time safety, generated quantity types do not accept
+/// the raw <see cref="IUnit"/> on <c>In(...)</c>. Each dimension has its own
+/// marker interface (e.g. <c>ILengthUnit : IUnit</c>) which only its units
+/// implement, and the generated <c>In(I&lt;Dim&gt;Unit)</c> overload accepts
+/// only that family. So <c>length.In(Units.Kilogram)</c> fails to compile.
+/// </para>
+/// <para>
+/// <c>ToBase</c> / <c>FromBase</c> are default-implemented; concrete units only
+/// have to provide <see cref="ToBaseFactor"/> and <see cref="ToBaseOffset"/>.
+/// </para>
+/// </remarks>
+public interface IUnit
+{
+	/// <summary>Gets the full name of the unit (e.g. <c>"Kilometer"</c>).</summary>
+	string Name { get; }
+
+	/// <summary>Gets the unit's symbol/abbreviation (e.g. <c>"km"</c>).</summary>
+	string Symbol { get; }
+
+	/// <summary>Gets the unit system this unit belongs to.</summary>
+	UnitSystem System { get; }
+
+	/// <summary>Gets the dimension this unit measures.</summary>
+	DimensionInfo Dimension { get; }
+
+	/// <summary>Gets the multiplication factor used in the to-base affine conversion.</summary>
+	double ToBaseFactor { get; }
+
+	/// <summary>Gets the additive offset used in the to-base affine conversion.</summary>
+	double ToBaseOffset { get; }
+
+	/// <summary>Converts a value expressed in this unit to the dimension's SI base unit.</summary>
+	T ToBase<T>(T value) where T : struct, INumber<T>
+		=> (value * T.CreateChecked(ToBaseFactor)) + T.CreateChecked(ToBaseOffset);
+
+	/// <summary>Converts a value expressed in the dimension's SI base unit to this unit.</summary>
+	T FromBase<T>(T baseValue) where T : struct, INumber<T>
+		=> (baseValue - T.CreateChecked(ToBaseOffset)) / T.CreateChecked(ToBaseFactor);
+}

Semantics.Quantities/PhysicalQuantity.cs

@@ -4,12 +4,13 @@
 
 namespace ktsu.Semantics.Quantities;
 
+using System;
 using System.Numerics;
 
 /// <summary>
 /// Base record for all physical quantity types. Inherits arithmetic operators from
-/// <see cref="SemanticQuantity{TSelf, TStorage}"/> and adds a <see cref="Value"/> property
-/// as an alias for the underlying storage.
+/// <see cref="SemanticQuantity{TSelf, TStorage}"/> and adds <see cref="Value"/>,
+/// <see cref="Dimension"/>, and same-dimension comparison.
 /// </summary>
 /// <typeparam name="TSelf">The derived physical quantity type.</typeparam>
 /// <typeparam name="T">The storage type for the quantity value.</typeparam>
@@ -19,14 +20,54 @@ public abstract record PhysicalQuantity<TSelf, T>
 	where TSelf : PhysicalQuantity<TSelf, T>, new()
 	where T : struct, INumber<T>
 {
-	/// <summary>Gets the value stored in this quantity.</summary>
+	/// <summary>Gets the value stored in this quantity (in the dimension's SI base unit).</summary>
 	public T Value => Quantity;
 
-	/// <summary>Gets whether this quantity satisfies physical constraints.</summary>
+	/// <summary>Gets whether this quantity satisfies structural physical constraints.</summary>
 	public virtual bool IsPhysicallyValid => !T.IsNaN(Value) && T.IsFinite(Value);
 
+	/// <summary>Gets the physical dimension this quantity belongs to. Implemented by generated types.</summary>
+	public abstract DimensionInfo Dimension { get; }
+
 	/// <summary>
 	/// Initializes a new instance of the <see cref="PhysicalQuantity{TSelf, T}"/> class.
 	/// </summary>
 	protected PhysicalQuantity() : base() { }
+
+	/// <summary>
+	/// Compares this quantity to another of the same physical dimension. Throws
+	/// <see cref="ArgumentException"/> if dimensions differ — quantities of different
+	/// dimensions are not ordered.
+	/// </summary>
+	public int CompareTo(IPhysicalQuantity<T>? other)
+	{
+		if (other is null)
+		{
+			return 1;
+		}
+
+		if (!Equals(Dimension, other.Dimension))
+		{
+			throw new ArgumentException(
+				$"Cannot compare quantity of dimension '{Dimension.Name}' to quantity of dimension '{other.Dimension.Name}'.",
+				nameof(other));
+		}
+
+		return Value.CompareTo(other.Value);
+	}
+
+	/// <summary>
+	/// Equality across the <see cref="IPhysicalQuantity{T}"/> surface — two quantities
+	/// are equal iff they share a dimension and a value. Cross-dimension comparisons
+	/// return <c>false</c> (they don't throw — equality is total).
+	/// </summary>
+	public virtual bool Equals(IPhysicalQuantity<T>? other)
+	{
+		if (other is null)
+		{
+			return false;
+		}
+
+		return Equals(Dimension, other.Dimension) && Value.Equals(other.Value);
+	}
 }

Semantics.Quantities/UnitConversionException.cs

@@ -0,0 +1,25 @@
+// Copyright (c) ktsu.dev
+// All rights reserved.
+// Licensed under the MIT license.
+
+namespace ktsu.Semantics.Quantities;
+
+using System;
+
+/// <summary>
+/// Thrown when a unit conversion cannot be performed — typically because the
+/// target unit's dimension does not match the source quantity's dimension.
+/// </summary>
+/// <remarks>
+/// In the typed compile-time path (<see cref="IPhysicalQuantity{T}"/> → <c>In(I&lt;Dim&gt;Unit)</c>),
+/// dimension mismatches fail at compile time. This exception remains for runtime
+/// scenarios where a quantity is converted via the untyped <see cref="IUnit"/> surface.
+/// </remarks>
+public sealed class UnitConversionException : ArgumentException
+{
+	public UnitConversionException() { }
+
+	public UnitConversionException(string message) : base(message) { }
+
+	public UnitConversionException(string message, Exception inner) : base(message, inner) { }
+}

Semantics.SourceGenerators/Generators/DimensionsGenerator.cs

@@ -129,6 +129,25 @@ protected override void Generate(SourceProductionContext context, DimensionsMeta
 
 		sourceFileTemplate.Classes.Add(dimensionsClass);
 
+		// Emit per-dimension marker interfaces (I{Dim}Unit : IUnit) so generated
+		// quantity types can accept dimensionally-compatible units only.
+		foreach (PhysicalDimension dimension in sortedDimensions)
+		{
+			sourceFileTemplate.Classes.Add(new ClassTemplate()
+			{
+				Comments =
+				[
+					"/// <summary>",
+					$"/// Marker interface implemented by every unit of the <c>{dimension.Name}</c> dimension.",
+					"/// Generated quantities use this to make <c>In(...)</c> dimensionally type-safe at compile time.",
+					"/// </summary>",
+				],
+				Keywords = ["public", "interface"],
+				Name = $"I{dimension.Name}Unit",
+				Interfaces = ["IUnit"],
+			});
+		}
+
 		WriteSourceFileTo(codeBlocker, sourceFileTemplate);
 		context.AddSource(sourceFileTemplate.FileName, codeBlocker.ToString());
 	}

Semantics.SourceGenerators/Generators/QuantitiesGenerator.cs

@@ -724,6 +724,43 @@ private static string BuildToBaseExpression(string unitName, Dictionary<string,
 		return scaled;
 	}
 
+	/// <summary>
+	/// Adds the per-quantity surface required by <see cref="ktsu.Semantics.Quantities.IPhysicalQuantity{T}"/>
+	/// (#59): a <c>Dimension</c> override returning <c>PhysicalDimensions.{dim}</c>, plus a
+	/// typed <c>In(I{dim}Unit)</c> method that converts the stored SI-base value into the
+	/// caller's unit. Emitted for V0 and V1 (scalar-storage) types only; vector V2+ types
+	/// have per-component conversion needs and are deferred.
+	/// </summary>
+	private static void AddDimensionAndInMembers(ClassTemplate cls, PhysicalDimension dim)
+	{
+		cls.Members.Add(new FieldTemplate()
+		{
+			Comments = [$"/// <summary>Gets the physical dimension this quantity belongs to.</summary>"],
+			Keywords = ["public", "override", "DimensionInfo"],
+			Name = $"Dimension => PhysicalDimensions.{dim.Name}",
+		});
+
+		cls.Members.Add(new MethodTemplate()
+		{
+			Comments =
+			[
+				"/// <summary>",
+				$"/// Converts this quantity's SI-base value to the value in <paramref name=\"unit\"/>.",
+				"/// Cross-dimension calls (e.g. passing a non-" + dim.Name + " unit) fail at compile time.",
+				"/// </summary>",
+				"/// <param name=\"unit\">The dimensionally-compatible target unit.</param>",
+				"/// <returns>The value expressed in <paramref name=\"unit\"/>.</returns>",
+			],
+			Keywords = ["public", "T"],
+			Name = "In",
+			Parameters =
+			[
+				new ParameterTemplate { Type = $"global::ktsu.Semantics.Quantities.I{dim.Name}Unit", Name = "unit" },
+			],
+			BodyFactory = (body) => body.Write(" => unit.FromBase(Value);"),
+		});
+	}
+
 	private static Dictionary<string, List<T>> GroupBy<T>(List<T> items, Func<T, string> keySelector)
 	{
 		Dictionary<string, List<T>> groups = [];
@@ -803,6 +840,9 @@ private void EmitV0BaseType(
 			"<see cref=\"" + typeName + "{T}\"/>",
 			applyV0Guard: true);
 
+		// Dimension override + typed In() (#59).
+		AddDimensionAndInMembers(cls, dim);
+
 		// V0 - V0 returns the same V0 of T.Abs(left - right) (locked decision in #52).
 		// We emit this on every V0 base type so the derived operator wins overload resolution
 		// over PhysicalQuantity's plain subtraction (which can produce a negative magnitude
@@ -892,6 +932,9 @@ private void EmitV1BaseType(
 			"<see cref=\"" + typeName + "{T}\"/>",
 			applyV0Guard: false);
 
+		// Dimension override + typed In() (#59).
+		AddDimensionAndInMembers(cls, dim);
+
 		// Magnitude method returning V0 base
 		if (v0TypeName != null)
 		{
@@ -1080,6 +1123,9 @@ private void EmitOverloadType(
 				applyV0Guard: vectorForm == 0,
 				strictPositive: strictPositive);
 
+			// Dimension override + typed In() (#59).
+			AddDimensionAndInMembers(cls, dim);
+
 			// Implicit widening to base type
 			cls.Members.Add(new MethodTemplate()
 			{