Name the quantity, not the unit

[matt-edmondson]

A schema that wanted a mass had to declare one. It wrote a semantic type called Kilograms, put "kg" on it as metadata, and every member of it said the unit twice — once as a name nothing reads and once as text something does. The kilograms are how the stored number is read, which is a fact about the field; the mass is what the value is.

ktsu.Semantics already names all of it: 212 physical quantities in C#, the same 212 as C++ classes from ktsu.Semantics.Cpp, and both are things a target already has. So this adds a Quantity type that names one rather than asking for a copy of it — Quantity(Mass), Quantity(Velocity3D), Quantity(Ratio) — and nothing is generated for it.

That is the whole difference from Semantic, and both are wanted. A semantic type is the schema's own — an entity id is not a texture id, and nothing outside the schema has heard of either. A quantity is everybody's.

The registry

QuantityRegistry reads the vocabulary out of the assembly, the same arrangement UnitRegistry has and for the same reason: keeping a list here would fall behind it.

A quantity's dimension takes three routes, in order:

1. A magnitude declares one directly, through IPhysicalQuantity.
2. A vector form does not — IVectorN above zero declares components and no dimension — so its dimension is what Magnitude() answers with.
3. A named overload of a vector form answers neither. Position3D is a Displacement3D under another name and the vocabulary gives it no Magnitude() of its own, so what is followed is the implicit widening onto what it is an overload of.

Six of the 212 are reachable only by that third route, and 212 is not a number chosen here — it is what the C++ projection emits (148 magnitudes, 27 signed scalars, 37 vectors). The two counts agreeing is what says a schema can name every quantity a C++ target has; it was 206 before the widening was followed.

The ten it leaves out are the logarithmic scales and two hand-written audio types. A decibel does not add and a pH does not scale, which is why ktsu.Semantics emits them from logarithmic.json rather than as dimensions — they have no dimensional formula and no vector form, so accepting one would put a type in the schema whose arithmetic means nothing and whose eight exponents a reflection table would have to invent.

Three things follow from a quantity knowing its own dimension

A unit on one has to agree with it. The check the semantic type could never make: a unit is text resolved through UnitRegistry and Kilograms was a name nothing reads, so the two had no way to disagree. The exponents are compared and not the names, because 72 of the vocabulary's dimensions share 63 exponent vectors — a joule and a newton metre are the same eight numbers, and refusing what the physics allows is worse than not checking.

The reflection table asks the type first. Its eight exponents used to come from the member's unit text and nowhere else, so a member that measured something but named no unit was written down as dimensionless — indistinguishable from a flag. A Velocity3D is a length over a time because of what it is.

Storage is the rest of the type, since every quantity is generic over one. It defaults to Float and is omitted from the file when it is, exactly as a vector's ElementType is, and it is held to a bare numeric: a generated semantic type is a record struct over a float implementing no INumber<T>, so Mass<Kilograms> is not a type anything could write.

The two generators

C# spells it ktsu.Semantics.Quantities.Mass<float>, and ClrTypeImporter reads it straight back off the closed type — the one thing generated C# carries that needs no attribute recording what it is. Everything else does, because a sequential struct or a record struct over a float is a shape a hand-written type may have for its own reasons; a Mass<float> is not something a target happened to write, it is the quantity.

C++ spells it wherever the target's vocabulary went, which CppGeneratorOptions.Quantities says in one entry for all 212 — the target named none of them, it ran the generator. That entry also says what the vocabulary is stored in, because a C++ quantity is a class rather than a template and the storage was fixed when it was generated:

"quantities": { "namespace": "holo", "include": "<holotype/quantities/quantities.hpp>" }

A member the schema keeps in a double is refused on a float target rather than emitted as two languages quietly disagreeing about the bytes — the same class of bug the enum width and the bool marshalling were already spelled out to prevent.

Format version 7

Unlike every step since version 1 this is not something an older reader drops. It fails to deserialize the member at all, on a discriminator it has never heard of, so the version moves to say so instead.

The modernised sample says it the new way

Second commit. samples/modernised.schema.json declared Kilograms, Metres, MetresPerSecond and MetresPerSecondSquared — four semantic types named after units, each also carrying the unit as metadata. Those become Quantity(Mass), Quantity(Radius), Quantity(Speed) and Quantity(Acceleration1D) with the unit on the member.

Coin stays a semantic type, and that is the point of keeping it: a price is this schema's own idea and nothing outside it has heard of a coin. The two ways of saying "this number is not just a number" now sit beside each other in one file, which is what a sample is for.

gravity is Acceleration1D rather than a magnitude because its default is -9.81, and a magnitude form refuses a negative value at construction.

Tests

772 → 795, all passing.

• QuantityTypeTests (15) — the vocabulary count, component arities, the three dimension routes including the widening, the log-scale exclusion, the unknown-name and non-numeric-storage refusals, the unit agreement check and the shared-exponent case that must not be refused, travelsAsBytes, the omit-when-default storage, the file round trip, the C# spelling, and generate-compile-reimport.
• QuantityCppTests (8) — the spelling and its include, the refusal for a target with no vocabulary, the storage mismatch both ways, the options-file checks, a promising class of quantities compiled under -std=c++20 -Wall -Wextra with its static_assert(std::is_trivially_copyable_v<T>), and the reflection table's exponents coming from the quantity with no unit written.
• The modernised sample's C++ target gains a stub vocabulary, so TheModernisedSampleCompiles exercises the new mapping over real types.

What this sets up

Holotype's rigid_body.schema.json declares Mass, Heading, Radius and Restitution as semantic types and names them in holotype.cppgen.json's existingTypes. Those become Quantity(Mass), Quantity(Heading), Quantity(Radius) and Quantity(Ratio), and the existingTypes entries go away — which is the change this was built for.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UGHDsYaaTQdzVR4XBR6miu

---

Generated by Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
93.6% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud