default_kind on Unit (v2.3.0 W3) — infrastructure for currency re-kinding

[withtwoemms]

Tracking issue for W3 of docs/internal/IMPLEMENTATION_PLAN_v230_packages.md (v2.3.0, Package infrastructure), which the plan flagged as needing one.

History: this issue was originally filed as "the datum #303 needs." That framing was wrong on both counts — see the comments. #303 is closed as not-a-bug, and the arrival rule was never an open question. The body below reflects current understanding; the comments preserve how it got there.

What

default_kind: str | None as a declared field on Unit, so a unit can name the kind a quantity in that unit is by default.

Why — the currency case

ADR 011 (decisions/011-currency-kinds-and-contexts.md, Accepted 2026-09-10) records the motivating defect: convert(100, USD → EUR, kind="usd") yields 92.14 euros still kinded usd. A rate edge genuinely transformed the quantity into different stuff, so carrying the source kind through is wrong.

default_kind is the datum that lets arrival at EUR re-kind the result.

Note the consumer does not exist yet. ucon ships no currency kinds or units — currency, usd, eur all raise KindNotFound — and native currency support is #292, still open. So this is forward-looking infrastructure, not a repair. Prioritize accordingly.

The arrival rule is already ratified

Not an open decision. ADR 011 states it, and W3 restates it including the sub-case:

"conflict between explicit kind and target default_kind on .to() → … target's declared kind wins on arrival (the 011 rule); document."

(An earlier revision of this issue presented a conflict with .archive/docs/internal/ARCHITECTURE_number-kind-v6.md, which says refuse. That document is archived and superseded.)

Scope

• Foundation — adds default_kind on Unit with auto-attachment at construction #306: the field, the TOML key, auto-attachment at construction, explicit kind= winning. Number.to() untouched. Additive and inert: no shipped unit declares one.
• Arrival rule — implement per ADR 011: arrival at a unit declaring a default_kind re-kinds the result.
• Which units declare — the one genuinely open judgement, and it is narrow. Currency units should, once native currency support via kinds and rate contexts #292 lands. gray and sievert should not: re-kinding Gy → Sv would assert dose_equivalent with no w_R supplied, which is exactly the claim the shipped radiation_weighting formula (comprehensive.ucon.toml:5239, H = D · w_R) exists to require. Weighting belongs on the arithmetic path, not the conversion path.

Related

• adds default_kind on Unit with auto-attachment at construction #306 — foundation, open and green
• native currency support via kinds and rate contexts #292 — native currency support, the intended consumer
• kind survives conversion to a unit outside the kind — manufactures a false label #303 — closed as not-a-bug; the original motivation, retracted

[withtwoemms]

Correcting this issue's framing on two counts. I filed it, and both errors were mine.

1. The arrival rule is not an open decision — it was already ratified

I presented re-kind-on-arrival versus refusal as a conflict needing resolution. It isn't:

• decisions/011-currency-kinds-and-contexts.md is Status: Accepted (2026-09-10) and states the rule: arrival at a default_kind unit re-kinds the result.
• IMPLEMENTATION_PLAN_v230_packages.md W3 restates it and settles the sub-case I called ambiguous: "conflict between explicit kind and target default_kind on .to() → … target's declared kind wins on arrival (the 011 rule); document."

My counter-source was .archive/docs/internal/ARCHITECTURE_number-kind-v6.md — under .archive/, superseded by definition. I weighted an archived document as co-equal with a current accepted ADR and manufactured a decision point from it.

The arrival rule is implementable as ratified. No ruling is outstanding.

2. #303, which motivated this issue, is probably not a bug

See the reassessment on #303. In short: Number(1, Gy, kind=absorbed_dose).to(Sv) preserving absorbed_dose is the same operation as Number(1, m, kind=beam_length).to(cm) preserving beam_length — the library carrying a caller's declaration through a unit change. Treating it as a defect assumes Sv implies dose_equivalent, which contradicts why Kind exists.

Worse, applying 011's re-kind rule to that case would overwrite an explicit absorbed_dose with dose_equivalent, asserting a weighting (H = D·w_R) that never occurred — fabricating a claim rather than preserving one.

What this leaves

default_kind remains worth building, for the case it was designed for. ADR 011's evidence is real: convert(100, USD → EUR, kind="usd") → 92.14 euros still kinded usd is wrong, because a rate edge genuinely transformed the quantity.

The discriminator is whether a conversion transforms or merely re-expresses. Currency conversions traverse a declared edge; Gy→Sv has no edge at all (only gray→rad_dose at comprehensive.ucon.toml:4079 and rem→sievert at :4405) and resolves 1:1 through a shared base_form.

Revised scope

• Foundation — adds default_kind on Unit with auto-attachment at construction #306, open and green: the field, TOML key, auto-attach at construction, .to() untouched. Unaffected by any of this.
• Arrival rule — implement as ADR 011 ratifies it. No decision pending.
• Which units declare — the one genuinely open question, and it is narrow: currency units should; gray and sievert should not, because re-kinding them produces a physically false label. That is a per-declaration judgement, not a change to the rule.

The v2.3.0 roadmap row should also note that W3 is explicitly additive ("no existing unit declares one"), so shipping it does not by itself change any existing conversion.