💥 fix(charts): ProlateSpheroidal3D.Delta must be a length

[nstarman]

The spec has said so since it was written:

Carries a required field Delta (focal half-length, an AbstractQuantity["length"] with Delta > 0).

Nothing enforced it. check_data compares mu against Delta**2 and never asks what dimension that is, so:

>>> chart = cxc.ProlateSpheroidal3D(Delta=u.StaticQuantity(2.0, "s"))
>>> chart.coord_dimensions
('area', 'area', 'angle')
>>> chart.check_data({"mu": u.Q(9.0, "s2"), ...}, values=True)   # accepted

A chart that declares area and validates s2. #807 worked around it — component_domains declares nothing for a Delta it cannot use — but the hole is in the chart, so this closes it there.

Where each rule is enforced, and why they differ

__post_init__ raises ValueError naming the dimension it got:

ProlateSpheroidal3D.Delta is the focal length and must have dimensions of
length, got s (time).

Positivity stays in check_data, deliberately. A unit is static and readable under jit; Delta.value is a tracer, so > 0 cannot be branched on at construction. The chart is built inside traced code by every pt_map that takes one as an argument, so the dimension check had to be tracer-safe — it is, and there's a test pinning that.

The jaxtyping annotation cannot carry this either. It is not enforced at construction (a non-scalar Delta is accepted today despite Real[..., ""]), and the dimension is not expressible there without narrowing Delta to a single quantity type — which would cost the Quantity/StaticQuantity choice that makes differentiability opt-in per instance.

⚠️ Breaking

A Delta in any other dimension now raises at construction. Such a chart was already broken — its mu bound could not be meaningfully compared against the area its own components declare — so this surfaces existing bugs rather than rejecting working code. No in-repo caller passed a non-length Delta.

Fallout

The strategies were the real users of the looseness. chart_init_kwargs builds parameters from each field's annotation, and Delta's pins no dimension, so it drew seconds as readily as parsecs — 28 tests constructed such charts. There is already a plum dispatch seam for per-chart overrides; this adds the first one, drawing a length in both quantity containers (which one is used is a real distinction here: StaticQuantity contributes no pytree leaves, Quantity contributes one). Magnitude is kept modest and its bounds are powers of two, since Delta is squared to bound mu and floats(width=32) requires exactly-representable bounds.

It also deletes a guard from #807. component_domains no longer asks whether Delta**2 is convertible to an area — a length squared always is. Only the overflow check remains, for a Delta near the float ceiling.

Verification

11691 passed, 311 skipped, 1 xfailed. prek run --all-files clean; nox -s docs succeeds. New tests cover both containers across three length units, four rejected dimensions, the error naming the dimension, and that a dynamic Delta still traces.

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

The change aligns implementation with the authoritative spec, adds focused tests (including jit tracing), and updates Hypothesis strategies to avoid generating now-invalid chart instances.

Pull request overview

This pull request enforces the spec-mandated invariant that ProlateSpheroidal3D.Delta is a length (not merely positive/scalar), closing a unit-consistency hole where the chart could declare ("area", "area", "angle") while validating non-area data.

Changes:

• Add a construction-time dimension check in ProlateSpheroidal3D.__post_init__ rejecting non-length Delta.
• Simplify component_domains(ProlateSpheroidal3D) by removing the “area-convertibility” guard, leaving only the finite-bound (overflow-to-inf) guard.
• Update Hypothesis strategy generation for ProlateSpheroidal3D kwargs and add targeted unit/dimension + tracing tests; document the enforcement split in the spec.

File summaries

File	Description
src/coordinax/_src/charts/d3.py	Enforces Delta length dimension at construction via __post_init__, keeping positivity in check_data.
src/coordinax/_src/charts/register_domains.py	Removes now-redundant unit-convertibility check; retains overflow/inf guard for domain declaration.
packages/coordinaxs.hypothesis/src/coordinaxs/hypothesis/charts/_src/chart_kwargs.py	Adds a chart-specific kwargs strategy override so Hypothesis draws length-valued Delta in either quantity container.
tests/unit/charts/test_prolate_delta_dimension.py	Adds tests for accepted length units/containers, rejected non-length units, error messaging, and jax.jit trace behavior.
tests/unit/charts/test_domain_agreement.py	Updates the Prolate domain test to cover only the remaining “infinite bound” non-declaration case.
docs/spec.md	Documents why dimension is enforced in __post_init__ while positivity remains enforced in check_data.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.91%. Comparing base (d984f00) to head (69fec27).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #812   +/-   ##
=======================================
  Coverage   96.90%   96.91%           
=======================================
  Files         272      272           
  Lines        9414     9433   +19     
=======================================
+ Hits         9123     9142   +19     
  Misses        291      291           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

🟢 Approval recommended

The change enforces a spec-stated invariant with JIT-safe design, updates generators accordingly, and adds focused tests covering both failure modes and tracing behavior.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 0 new
• Review effort level: Lite