Reconcile IPhysicalQuantity / PhysicalQuantity surface with strategy doc and CLAUDE.md

[matt-edmondson]

Summary

IPhysicalQuantity.cs and PhysicalQuantity.cs are minimal: a Value property and an IsPhysicallyValid shape, with no per-dimension validation, no dimension/base-unit metadata accessors, no In(unit) conversion, and no uncertainty support. Several pieces of documentation imply more.

Evidence

• Semantics.Quantities/IPhysicalQuantity.cs:1-27 — minimal interface.
• Semantics.Quantities/PhysicalQuantity.cs:16-32 — exposes Value; no validation hook.
• docs/design-semantic-quantities.md and docs/strategy-unified-vector-quantities.md reference Dimension, BaseUnit, In(unit), IsPhysicallyValid, WithUncertainty, Magnitude() (the latter is actually emitted on Vector1+).
• CLAUDE.md mentions a polished public API including PhysicalConstants.Generic.*<T>() and dimensional analysis on operators.

Suggested next step

Decide which surface is canonical for the unified-vector branch:

1. Trim docs back to match the slim runtime interface, or
2. Extend IPhysicalQuantity / PhysicalQuantity with the documented members (Dimension metadata, In(unit) conversion, validation hook), backed by tests.

Either way, write down the resulting contract in docs/architecture.md so the generator templates can target it deterministically.

Area / Severity

Quantities / Docs · incomplete

[matt-edmondson]

Status / no change in #70 — needs an architectural decision before code lands.

Current surface (Semantics.Quantities/IPhysicalQuantity.cs, Semantics.Quantities/PhysicalQuantity.cs):

public interface IPhysicalQuantity<T> : ISemanticQuantity<T> where T : struct, INumber<T> {
    T Value { get; }
    bool IsPhysicallyValid { get; }
}

public abstract record PhysicalQuantity<TSelf, T> : SemanticQuantity<TSelf, T>, IPhysicalQuantity<T> {
    public T Value => Quantity;
    public virtual bool IsPhysicallyValid => !T.IsNaN(Value) && T.IsFinite(Value);
}

The branch's working contract has effectively converged on option 1 in this issue (trim docs to match the slim interface): construction-time validation lives in the generated From{Unit} factories (V0 non-negativity from #50, future per-dimension constraints from #51); dimension/base-unit metadata is reachable via the generated *Units types and PhysicalConstants; there is no per-instance In(unit) conversion or WithUncertainty API.

If that direction is right, we'd:

• Trim references to Dimension, BaseUnit, In(unit), WithUncertainty, etc. out of docs/design-semantic-quantities.md and docs/strategy-unified-vector-quantities.md.
• Note in docs/architecture.md that IsPhysicallyValid is a "is this a usable number" check, not a per-dimension constraint check (those throw at construction).

If we instead want option 2 (extend the interface), we'd need to decide:

• Where the dimension/base-unit metadata is exposed — static method on TSelf (consistent with Zero, Magnitude()), separate runtime-discoverable registry, or a new generated IPhysicalQuantity.Dimension member.
• Whether In(Unit) returns T (raw value) or constructs a new typed wrapper, and how it pairs with the per-unit factories from QuantitiesGenerator emits a factory for only the first availableUnit #48.

Recommend deferring until after #48/#49 land — the answer to "what should In(unit) look like" depends on the per-unit factory shape. Happy to draft either direction once the call is made.

---

Generated by Claude Code