No exact 3D curve for a spiral with an elevation law, so an alignment centreline cannot be composed

[GeneralPawz]

Problem

Curve2 can carry a transition spiral exactly; Curve3 cannot.

pub enum Curve2 { Line, Circle, Ellipse, Polyline, BSpline, Intrinsic }
pub enum Curve3 { Line, Circle, Ellipse, Polyline, BSpline }

Curve2::Intrinsic holds a CurvatureLaw anchored to a start frame over
an arc length, so a clothoid, a Helmert curve and a sine-corrected
transition are all exact values rather than approximations. Curve3 has no
counterpart, and CurveRelation composes existing nodes (Composite,
Trimmed, Offset, SurfaceCurve, ParameterCurve) without offering a
way to combine a planar curve with an independent elevation law.

Why it matters

A road or rail centreline is authored as two independent laws: a planar
horizontal layout carrying the spirals, and a vertical profile giving
elevation as a function of distance along that plan. The 3D centreline is
their composition, and it is the curve every downstream question resolves
against.

With no exact 3D form, a consumer holding an exact Intrinsic2 plan plus an
exact vertical law has three options, and all three are bad:

• approximate the spiral as a BSpline3, discarding the exactness the
  kernel deliberately preserves in 2D
• keep plan and profile separate and make every consumer recompose them,
  which is the operation the graph exists to own
• refuse, which is what we do today

The information is exact at the boundary and is being lost on the way in --
the same argument as #90.

Concretely, in ifc-alignment (IFC4x3): horizontal layouts lower to an
exact composite Curve2 today, including clothoid, Helmert and sine
families. Vertical segments lower separately. Nothing composes them, so
IfcGradientCurve and IfcSegmentedReferenceCurve are unimplemented, and
a product positioned along an alignment cannot be placed in space.

This is a representation gap, not a request for road semantics. What a
centreline means, what a station is, and whether a gradient is acceptable
all stay with the consumer.

Possible shapes

Not a prescription -- the kernel owns this choice:

1. Curve3::Intrinsic -- a 3D natural-equation curve carrying curvature
   and torsion laws. Most general; also the largest change, and torsion is
   not what an alignment actually states.
2. A CurveRelation variant composing an existing planar curve node with
   an elevation law along its arc length. Closer to how the data is
   authored, and reuses the exact 2D values already supported.
3. An elevation law type usable with the existing Composite machinery.

Option 2 looks closest to the existing design, since CurveRelation
already composes rather than re-encodes, but that is a preference from the
consumer side, not a requirement.

Done when

• a planar curve carrying an exact transition spiral can be combined with
  an elevation law into a single 3D curve value, without approximating
  either input
• the composition survives a round trip through the graph
• a point and a frame can be evaluated at a given distance along the
  composed curve
• validation refuses a composition whose plan and elevation cover
  different arc-length domains, rather than silently clamping or
  extrapolating
• the distinction between horizontal length, projected length and 3D length
  is preserved rather than collapsed

Verified against

crates/representations/analytic/curve/src/lib.rs on main at the time of
writing, and the v0.1.8 tag that openbimrs/ifc currently pins. The
Curve3 variant list is unchanged between the two.

Reported from openbimrs/ifc, where ifc-alignment is the blocked
consumer. Not urgent for us: alignment authoring does not depend on it, so
we are proceeding there and treating 3D composition as a typed refusal
until this lands.

[GeneralPawz]

Landed in ca4381e (ADR 0060).

Shape chosen: option 2. `Curve3::Elevated(Elevated3)` holds a boxed `Curve2` plan plus an `ElevationLaw`. Composition, not re-encoding — either half comes back unchanged.

Two things surfaced while reading the code that changed the work:

`Intrinsic2` had no evaluator at all. It documents that position does not integrate in closed form, which is why this method exists and an `evaluate` does not, and `evaluate2` has no `Intrinsic` arm. So criterion 3 was unmet in 2D too — a 3D composition alone would not have delivered it. `arc_length.rs` now provides `intrinsic_point`/`intrinsic_tangent`; the 3D path is a thin layer over them.

Height is a function of plan distance, not 3D arc length. They diverge by `sqrt(1 + g^2)` wherever grade is non-zero. Measured: a 120 m curve at 2% entry grade is 12.5 mm longer in 3D, which misreads the profile by 0.35 mm — systematic and compounding, so the convention is named in the type rather than left to callers.

Heading stays exact in closed form (reusing `turning_over`); only position is quadratured, Gauss-Legendre 8-point subdivided by total turning and bounded so a malformed law refuses rather than hangs. Same bargain as evaluating `sin`: the value is exact, the readout is to tolerance.

Done when:

• ✅ exact spiral + exact elevation compose with neither approximated
• ✅ survives a round trip — stored as an ordinary `GeometryNode::Curve3`, validated through `GeometryGraphBuilder::finish`, no special case in the graph
• ✅ point and tangent evaluate at a given distance

Evidence: clothoid position pinned against an independently computed Fresnel series (not another run of the quadrature) to better than 1e-9; constant curvature checked against the elementary quarter-arc. 1586 workspace tests pass. Mutation 5/5 killed: grade dropped from the tangent, `sqrt(1+g^2)` removed, spiral plan refused, Horner degenerated to a sum, piecewise piece not rebased to its own zero.

A B-spline plan is refused: its parameter is not arc length, so pairing one would silently mean something other than what the law states.

Torsion is still not representable. An alignment does not state torsion, so option 1 stays open for a real need rather than built speculatively. `IfcGradientCurve` / `IfcSegmentedReferenceCurve` now have a target representation; lowering stays with the consumer.

---

Unrelated find while gating: e680aa6 .. 4a2751d left `pub mod application` ungated. 4a2751d inserted `ray_index` between the `#[cfg(feature = "application")]` and its `pub mod`, so the gate bound `ray_index` instead. The workspace build hides it — feature unification pulls the deps in anyway — and only `cargo build -p axiolid` in isolation, as the gate runs it, fails. Fixed in 40249dd.