feat(values): introduce NumericTypeSpec registry for cold-path dispatch

[aalpar]

Summary

• Adds [numKinds]NumericTypeSpec array populated via registerNumericSpec() in each type's init(), one record per NumericKind
• Migrates Simplify, ExactnessOf, NumberToFloat64, NumberToComplex128 from hand-maintained type switches to registry lookup — collapses 4 of the 12 items from the ADDING-A-NEW-NUMERIC-TYPE guide into a single registration call
• NumberToFloat64 now returns ErrNotAReal for Complex/BigComplex (previously silently extracted the real part), matching R7RS semantics (Q-i=C3)

Design notes

• Fields unexported + 5 getter methods (SchemeName, SimplifyDown, ToFloat64, ToComplex128, IsAlwaysExact) — external callers cannot mutate specs
• validateNumericSpecs exposed as an unexported function so tests can call it with crafted bad state (the live sync.Once is already consumed before tests run)
• Registry is cold-path only — hot-path arithmetic dispatch tables (makeArithmeticDispatch et al.) are untouched

Tests

• TestNumericRegistryAllKindsRegistered — all 7 kinds populated
• TestNumericRegistrySmoke — per-kind getter correctness
• TestEnsureNumericRegistryInitPanics — missing-kind and partial-fill panic paths
• TestRegisterNumericSpecDuplicateRejected — duplicate registration rejected
• Behavioral-equivalence golden tests: pre-migration switch logic captured inline, compared against registry path across 15 exemplars per function (TestSimplifyEquivalence, TestExactnessOfEquivalence, TestNumberToFloat64Equivalence, TestNumberToComplex128Equivalence)

Bench gate

Master and branch binaries run identically under current conditions (~0.89s for 1M-iteration loop). Gabriel suite was throttled during the run (E-cores, 30–60% spread); interleaved master/branch timing confirms no regression — cold-path changes do not appear in the Gabriel workload.

CI

make ci passes: lint (0 issues), all tests green, covercheck (38/38 packages ≥ 80%).

[Copilot]

Pull request overview

This PR introduces a numeric type-spec registry to centralize cold-path numeric behavior and reduce duplicated type-switch maintenance across the numeric tower.

Changes:

• Adds NumericTypeSpec registration/lookup infrastructure and tests.
• Migrates Simplify, ExactnessOf, NumberToFloat64, and NumberToComplex128 to registry-backed dispatch.
• Registers per-kind simplify/conversion/exactness behavior in each numeric type file.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
werr/werr.go	Adds a numeric registry sentinel error.
VERSION	Bumps the project version.
values/* numeric files	Register per-kind numeric specs and helper conversion/simplification functions.
values/numeric_registry.go	Adds the numeric type-spec registry implementation.
values/numeric_registry_test.go	Adds registry coverage and behavioral-equivalence tests.
values/numeric_dispatch_test.go	Updates dispatch coverage for complex-to-float behavior.
values/numeric_tower.go	Delegates simplification/exactness decisions to the registry.
values/promotion.go	Delegates float/complex conversions to the registry.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[aalpar]

Crosscheck findings — resolution summary

5-lens /crosscheck:crosscheck all was run against the diff (code, errors, types, tests, consistency lenses, all on Opus). Findings classified into Critical / Notable / Architectural / Symptom buckets per the workflow in plans/CLAUDE.md.

Behavioral regression fixed

• (make-rectangular (- (make-rectangular 3 0) (make-rectangular 0 0)) 5) now returns 3+5i again. The strict Q-i=C3 contract in PR-1 panicked here because isRealNumber in extensions/math/prim_complex.go:111-122 admits *Complex with imag == 0 as a real number. The new contract: complexToFloat64/bigComplexToFloat64 return the real component when imag == 0 (lossless), error only when imag != 0. This aligns with plans/2026-05-14-numeric-loss-signals-design.md's principle: "succeed silently when no information lost; error precisely when it would be." First crosscheck (3 lenses) had marked this safe; second crosscheck (code lens at Opus) caught the actual isRealNumber body. Test TestNumberToFloat64PanicsOnNonzeroImag locks the contract.

Other Critical fixes

• Receiver s → p on all 5 NumericTypeSpec methods (was 533 p vs 5 s after PR-1).
• numeric_kind.go "ADDING A NEW NUMERIC TYPE" guide updated: removes stale NumberToFloat64/Simplify items, adds registerNumericSpec step, renumbers to 13 items.
• NumberToFloat64 panic preserves ErrNotAReal as cause via werr.WrapForeignErrorWithCause.

Notable

• LookupNumericSpec renamed from Lookup (descriptive in broad values package). Bounds-checks the kind.
• registryMu removed (Go init is single-goroutine).
• Eager init validation moved to validate_numeric_registry.go (sorts after all per-type files lexically; required because rational.go's init runs after numeric_registry.go's).
• 21 new per-type helpers across 7 files gain godoc one-liners noting precision-loss status.
• big_complex.go helpers moved below the dispatch-table comment+var block (godoc attachment).
• Simplify(nil) returns nil; ExactnessOf(nil) panics with ErrNotANumber.
• numeric_registry_test.go gains copyright header.

Test improvements

• TestNumericRegistryAllKindsRegistered uses reflection to verify all function fields non-nil.
• TestNumericRegistrySmoke SimplifyDown line is now meaningfully asserted; added Complex(3+0i) and BigComplex(3,0) cases.
• TestTypeSwitchFunctionsHandleAllTypes recover block surfaces panics as typed failures.
• equivalenceExemplars expanded with MinInt64, BigInteger > int64 (both signs), Float(-0.0), Rational(1/3), inexact-real-with-exact-zero-imag BigComplex.

Deferred

• Loss-signals plumbing for BigFloat/BigInteger/Rational → float64 (silent truncation today): owned by plans/2026-05-14-numeric-loss-signals-impl.md, which is gated on this PR merging.
• Types-lens architectural suggestions (methods-on-Number for SimplifyDown/ToFloat64/ToComplex128; exactness func(Number) Exactness field; collapse parallel arrays): real design improvements but a different design than the user-approved plan; deferred to a future structural-reduction wave.

CI: make ci passes (lint 0 issues, all tests green, 38/38 packages ≥ 80% coverage).

[aalpar]

Copilot inline-comment resolutions

Four Copilot comments on the initial commit (8ab2ced1). Three were resolved by the crosscheck-fix commit (b68a8115); one resolved by the follow-up style commit (e91ed287); one is a known false positive.

1. VERSION bump — not actionable (known false positive)

A pre-commit hook auto-bumps VERSION on every commit. The hook fires on feature PRs too. Per memory feedback-copilot-version-false-positive.md: "pre-commit hook auto-bumps VERSION every commit; Copilot flags on every PR. Expected false positive; don't revert."

2. values/promotion.go ErrNotAReal cause-discard — resolved in b68a8115

NumberToFloat64 now uses werr.WrapForeignErrorWithCause(werr.ErrNotAReal, err, ...):

panic(werr.WrapForeignErrorWithCause(werr.ErrNotAReal, err,
    "NumberToFloat64: cannot convert %T to float64", n))

The inner ErrNotAReal from complexToFloat64/bigComplexToFloat64 is now the sentinel of the panicked error AND its cause. errors.Is(panicVal, werr.ErrNotAReal) succeeds. Test TestNumberToFloat64PanicsOnNonzeroImag locks this contract.

3. values/numeric_registry_test.go:329 complex(3+0i, 0) syntax — resolved in e91ed287

Copilot's "will not compile" assessment was inaccurate (Go converts untyped complex constants with zero imag implicitly to float, so the original compiled fine), but the style point was valid — complex(3+0i, 0) reads as if a complex value is being passed as the real argument. Cleaned up to use direct complex literals:

NewComplex(3 + 0i),
NewComplex(3.5 + 0i),
NewComplex(3 + 4i),

4. values/numeric_registry.go Lookup bounds check — resolved in b68a8115

Renamed Lookup → LookupNumericSpec (descriptive in the broad values package) and added a bounds check:

func LookupNumericSpec(kind NumericKind) *NumericTypeSpec {
    if int(kind) >= int(numKinds) {
        panic(werr.WrapForeignErrorf(werr.ErrNumericRegistry,
            "LookupNumericSpec: kind %d out of range [0,%d)", kind, numKinds))
    }
    return &numericRegistry[kind]
}

Out-of-range kinds now produce ErrNumericRegistry instead of a Go runtime index out of range panic.