brep_kernel/edit/direct_edit/

face_offset_sphere.rs

use super::*;

// ---------------------------------------------------------------------------
// Push a SPHERICAL analytic face by OFFSETTING its carrier to a concentric
// sphere (backlog #4a Sphere × Plane through-centre + #4b off-centre / sphere).
//
// The methodology mirrors `offset_ruled_face` (a face is a TRIMMED region of an
// infinite carrier surface; to push it we replace the carrier by its offset and
// re-derive the trim against the fixed neighbour carriers):
//
//   * The exact offset of a sphere is a CONCENTRIC sphere of radius r ± δ. It is
//     realised here as the exact uniform scale of the carrier about the sphere
//     centre by k = r_new / r — an AFFINE map, so the scaled surface is byte-for-
//     byte the same rational parameterisation (same knots/weights/seam azimuth/
//     poles), only radially grown. This is the *exact* sphere offset the backlog
//     item calls for; it is NOT the `offset_surface` sample-and-fit, which was
//     tried first and does NOT re-recognise as a sphere for a full-sphere face
//     (its Greville fit degenerates at the poles → `analytic() == None`). The
//     affine scale keeps the pushed face's OWN-ONLY (seam meridian + pole) and
//     THROUGH-CENTRE-rim pcurves valid pointwise: because S′(u,v) = c + k·(S − c),
//     each such edge, scaled about c by the SAME k, lands on S′ at its OWN
//     unchanged pcurve.
//
//   * RIM classification per boundary edge (honest refusal, never a bad solid):
//       - PLANE through the centre → SCALE (4a): a uniform scale about c maps a
//         through-centre plane onto ITSELF, so the scaled great-circle rim IS the
//         exact S′ ∩ plane, no azimuth/seam mismatch.
//       - PLANE off-centre, or a SPHERE neighbour → RECOMPUTE (4b): the scaled
//         rim would leave the fixed carrier, so the rim edge is re-derived as
//         S′ ∩ neighbour. Off-centre small circles: `intersect_plane_quadric`
//         gives radius √((r±δ)²−h²); sphere × sphere: `intersect_sphere_sphere`
//         (both via the public `intersect_analytic_pair`). The rim's pushed-face
//         pcurve is rebuilt on S′; a SEAM-crossing rim (its closure vertex is
//         shared with an own-only meridian — the axis-perpendicular cap case)
//         also rebuilds that meridian as the v-subrange of the offset meridian
//         (an iso-curve preserves the v-parameter exactly, keeping the straight
//         (u,v) pcurve synchronised) and moves its closure vertex to the new
//         latitude. Seam-aligned circle construction is used there so the rim
//         starts on the u = 0 seam.
//       - coaxial cylinder / cone → RECOMPUTE: the exact latitude circle is
//         selected from the coaxial-revolution intersector and the ruled
//         neighbour is extended/retrimmed over the relocated rim.
//       - non-coaxial cylinder / cone, general revolution / torus / free-form
//         → refused.
//     Refused too: a seam-crossing rim on an OBLIQUE plane or a SPHERE neighbour,
//     a non-closed / multi-edge RECOMPUTED rim, a vanished cap (grown sphere no
//     longer reaches the plane / spheres separated or tangent), and a push that
//     collapses or inverts the solid.
//
//   * An OPEN rim on the EXACT-SCALE path is supported, and its corners are
//     carried. A spherical pocket in a box CORNER has three quarter-circle rims,
//     one per box plane, all three through the centre; the scale moves each
//     arc's endpoint radially and the box edge that ends there has its trim slid
//     to follow. That slide is a re-parameterisation, not a re-solve: both
//     planes of such a corner pass through the sphere centre (which is what put
//     the rim on this path), so their intersection line does too and the scale
//     maps the corner along it exactly. A corner that does NOT land on its own
//     fixed edge, or a slide that would collapse or invert that edge's trim,
//     refuses — the open-rim analogue of the recomputed path's closed-rim gate.
// ---------------------------------------------------------------------------

/// Push a SPHERICAL face along its outward normal by `distance` (positive grows
/// the solid) by replacing its carrier with the concentric offset sphere and
/// re-trimming its neighbours: planar caps through the centre keep their exact-
/// scale great-circle rim, while off-centre planes, spheres, and coaxial ruled
/// neighbours have their rim re-derived as S′ ∩ neighbour.
///
/// An OPEN rim (several arcs, as a pocket in a box corner has) is supported on
/// the exact-scale path, with the fixed edges that end on its corners re-trimmed
/// to follow them.
///
/// Refused cleanly (never a bad solid): non-coaxial cylinder/cone neighbours,
/// general-revolution/torus/free-form neighbours, seam-crossing oblique or
/// sphere-neighbour rims, non-closed RECOMPUTED rims, a rim corner that leaves
/// its own fixed edge or collapses that edge's trim, a vanished cap, and a push
/// that collapses/inverts the solid.
pub fn offset_sphere_face(
    solid: &BrepSolid,
    face_id: u64,
    distance: f64,
) -> Result<BrepSolid, String> {
    if !distance.is_finite() {
        return Err("offset_sphere_face: distance must be finite".into());
    }
    let scale = solid_model_scale(solid);
    let tolerance = (scale * 1e-7).max(1e-9);
    let plane_tolerance = (scale * 1e-6).max(1e-7);

    let (pshell, pface) = find_face(solid, face_id)
        .ok_or_else(|| format!("offset_sphere_face: no face {face_id}"))?;
    let pushed = &solid.shells[pshell].faces[pface];
    let Some(AnalyticSurface::Sphere { frame, radius }) = pushed.surface.analytic() else {
        return Err("offset_sphere_face: the pushed face is not a sphere".into());
    };
    let center = frame.origin;
    let axis = frame.axis;
    let seam_x = frame.x_axis;
    let seam_y = frame.y_axis;
    let radius = *radius;
    if radius <= tolerance {
        return Err("offset_sphere_face: degenerate sphere radius".into());
    }

    // Sign the push: `distance` is measured along the face's OUTWARD normal. For
    // a convex ball the outward normal is radial (s = +1) so the radius grows; a
    // spherical POCKET's outward normal points inward (s = −1) so a positive push
    // (more material) SHRINKS the cavity. Either way r_new = r + distance·s.
    let [u0, u1] = pushed.surface.domain_u()?;
    let [v0, v1] = pushed.surface.domain_v()?;
    let (um, vm) = (0.5 * (u0 + u1), 0.5 * (v0 + v1));
    let point = pushed.surface.evaluate(um, vm)?;
    let mut normal = pushed.surface.normal(um, vm)?;
    if !pushed.same_sense {
        normal = normal.scale(-1.0);
    }
    let radial = point.sub(center);
    if radial.length() <= tolerance {
        return Err("offset_sphere_face: degenerate radial direction".into());
    }
    let outward_sign = if normal.dot(radial) >= 0.0 { 1.0 } else { -1.0 };
    let radius_new = radius + distance * outward_sign;
    if radius_new <= tolerance {
        return Err(
            "offset_sphere_face: the push collapses the sphere to or past its centre — refusing"
                .into(),
        );
    }

    // S′ = exact concentric offset = uniform scale of the carrier about the
    // centre by k. An affine map, so the parameterisation is preserved exactly.
    let k = radius_new / radius;
    let scale_about_center = AffineTransform::new([
        k, 0.0, 0.0, (1.0 - k) * center.x,
        0.0, k, 0.0, (1.0 - k) * center.y,
        0.0, 0.0, k, (1.0 - k) * center.z,
        0.0, 0.0, 0.0, 1.0,
    ])?;
    let s_prime = transform_surface(&pushed.surface, scale_about_center)?;
    // Defensive: confirm the offset is the concentric sphere we expect.
    match s_prime.analytic() {
        Some(AnalyticSurface::Sphere { frame, radius }) => {
            if frame.origin.sub(center).length() > plane_tolerance
                || (radius - radius_new).abs() > plane_tolerance.max(radius_new * 1e-9)
            {
                return Err("offset_sphere_face: offset carrier is not the expected \
                            concentric sphere — refusing"
                    .into());
            }
        }
        _ => {
            return Err(
                "offset_sphere_face: offset carrier did not re-recognise as a sphere — refusing"
                    .into(),
            )
        }
    }

    // Edge -> incident faces, to classify the pushed face's boundary edges into
    // OWN-ONLY edges (seam meridians + degenerate poles — intrinsic to the sphere)
    // and RIM edges shared with a fixed neighbour.
    let mut faces_of_edge: HashMap<u64, Vec<u64>> = HashMap::default();
    for shell in &solid.shells {
        for face in &shell.faces {
            for loop_record in &face.loops {
                for coedge in &loop_record.coedges {
                    faces_of_edge
                        .entry(coedge.edge_id)
                        .or_default()
                        .push(face.id);
                }
            }
        }
    }
    let edge_by_id: HashMap<u64, &EdgeRecord> =
        solid.edges.iter().map(|edge| (edge.id, edge)).collect();

    // The v-parameter domain of the offset sphere (== the source domain; the
    // uniform scale preserves the parameterisation exactly).
    let [dv0, dv1] = s_prime.domain_v()?;

    // Classify. A rim neighbour is one of:
    //   * PLANE through the centre → exact-scale path (the landed 4a behaviour):
    //     the scaled great-circle rim stays on the fixed plane.
    //   * PLANE off-centre / SPHERE / coaxial CYLINDER or CONE → RECOMPUTE:
    //     the scaled rim leaves the fixed carrier, so re-derive S′ ∩ neighbour.
    //   * non-coaxial ruled / general revolution / torus / free-form → refused.
    enum RimKind {
        OffCentrePlane(Plane),
        NeighbourSphere,
        CoaxialRuled,
    }
    let mut edges_to_scale: HashSet<u64> = HashSet::default();
    let mut through_centre_caps: HashSet<u64> = HashSet::default();
    let mut own_only_edges: Vec<u64> = Vec::new();
    let mut all_boundary_vertices: HashSet<u64> = HashSet::default();
    let mut raw_rims: Vec<(u64, u64, RimKind)> = Vec::new();

    for loop_record in &pushed.loops {
        for coedge in &loop_record.coedges {
            let edge = *edge_by_id
                .get(&coedge.edge_id)
                .ok_or_else(|| format!("offset_sphere_face: missing edge {}", coedge.edge_id))?;
            all_boundary_vertices.insert(edge.start_vertex_id);
            all_boundary_vertices.insert(edge.end_vertex_id);

            let incident = faces_of_edge.get(&edge.id).cloned().unwrap_or_default();
            if incident.iter().all(|f| *f == face_id) {
                own_only_edges.push(edge.id); // Seam meridian or degenerate pole.
                continue;
            }
            let neighbour = *incident
                .iter()
                .find(|f| **f != face_id)
                .ok_or_else(|| format!("offset_sphere_face: edge {} has no neighbour", edge.id))?;
            let (nshell, nface) = find_face(solid, neighbour)
                .ok_or_else(|| format!("offset_sphere_face: missing neighbour {neighbour}"))?;
            let neighbour_surface = &solid.shells[nshell].faces[nface].surface;
            match neighbour_surface.analytic() {
                Some(AnalyticSurface::Plane { .. }) => {
                    let plane =
                        plane_of_surface(neighbour_surface, plane_tolerance, "offset_sphere_face")?;
                    if center.sub(plane.origin).dot(plane.normal).abs() <= plane_tolerance {
                        // Through the centre: the exact-scale great-circle path.
                        through_centre_caps.insert(neighbour);
                        edges_to_scale.insert(edge.id);
                    } else {
                        raw_rims.push((edge.id, neighbour, RimKind::OffCentrePlane(plane)));
                    }
                }
                Some(AnalyticSurface::Sphere { .. }) => {
                    raw_rims.push((edge.id, neighbour, RimKind::NeighbourSphere));
                }
                Some(AnalyticSurface::RuledRevolution { .. }) => {
                    if !super::face_offset::ruled_neighbour_is_coaxial(
                        neighbour_surface,
                        center,
                        axis,
                        scale,
                    ) {
                        return Err("offset_sphere_face: a cylinder/cone rim neighbour is \
                                    NON-coaxial (only coaxial sphere × ruled intersections are \
                                    supported) — refusing"
                            .into());
                    }
                    raw_rims.push((edge.id, neighbour, RimKind::CoaxialRuled));
                }
                Some(AnalyticSurface::Torus { .. }) => {
                    return Err("offset_sphere_face: a toroidal rim neighbour is deferred \
                                (torus is untouched in this slice)"
                        .into());
                }
                _ => {
                    return Err("offset_sphere_face: a rim neighbour is not a supported plane, \
                                sphere, or coaxial cylinder/cone (general revolution and \
                                free-form neighbours are deferred in this slice)"
                        .into());
                }
            }
        }
    }

    // Each recomputed rim must be a single CLOSED edge (start == end vertex); its
    // closure vertex sits where the rim crosses the sphere seam.
    let mut closure_vertices: HashSet<u64> = HashSet::default();
    for (edge_id, _, _) in &raw_rims {
        let edge = *edge_by_id.get(edge_id).unwrap();
        if edge.start_vertex_id != edge.end_vertex_id {
            return Err(
                "offset_sphere_face: a recomputed rim is not a single closed edge \
                        (multi-edge / open rims are deferred in this slice)"
                    .into(),
            );
        }
        closure_vertices.insert(edge.start_vertex_id);
    }

    // Own-only seam meridians whose end lands on a recomputed rim's closure vertex
    // must be rebuilt (their rim end moves to the new latitude). Uncoupled seam
    // meridians and poles just scale.
    let mut coupled_meridians: HashSet<u64> = HashSet::default();
    for own in &own_only_edges {
        let e = *edge_by_id.get(own).unwrap();
        if e.degenerate {
            edges_to_scale.insert(*own);
            continue;
        }
        if closure_vertices.contains(&e.start_vertex_id)
            || closure_vertices.contains(&e.end_vertex_id)
        {
            coupled_meridians.insert(*own);
        } else {
            edges_to_scale.insert(*own);
        }
    }
    // Every boundary vertex scales EXCEPT the relocated rim-closure vertices.
    let vertices_to_scale: HashSet<u64> = all_boundary_vertices
        .iter()
        .copied()
        .filter(|v| !closure_vertices.contains(v))
        .collect();

    // --- Build the recomputed rims (geometry only; applied below) ----------
    struct RimBuild {
        edge_id: u64,
        neighbour_id: u64,
        neighbour_is_sphere: bool,
        closure_vertex: u64,
        circle: NurbsCurve,
        closure_point: Vec3,
        v_rim: f64,
        pushed_pcurve: NurbsCurve,
    }
    let mut rim_builds: Vec<RimBuild> = Vec::new();
    for (edge_id, neighbour, kind) in &raw_rims {
        let edge = *edge_by_id.get(edge_id).unwrap();
        let closure_vertex = edge.start_vertex_id;
        let seam_coupled = coupled_meridians.iter().any(|m| {
            let e = *edge_by_id.get(m).unwrap();
            e.start_vertex_id == closure_vertex || e.end_vertex_id == closure_vertex
        });

        let mut circle = if seam_coupled {
            // A seam-crossing rim shares its closure vertex with a meridian, so
            // the new circle MUST start exactly on the seam. Build it in the
            // sphere's own frame (seam-aligned by construction). Only an
            // axis-perpendicular (latitude) plane keeps the rim a fixed-u circle;
            // oblique seam-crossing caps and sphere neighbours are refused.
            match kind {
                RimKind::OffCentrePlane(plane) => {
                    if plane.normal.dot(axis).abs() < 1.0 - 1e-6 {
                        return Err(
                            "offset_sphere_face: a seam-crossing rim on an OBLIQUE plane is \
                                    deferred in this slice (only axis-perpendicular caps)"
                                .into(),
                        );
                    }
                    let a = plane.origin.sub(center).dot(axis);
                    let rr2 = radius_new * radius_new - a * a;
                    if rr2 <= tolerance * tolerance {
                        return Err(
                            "offset_sphere_face: the push pulls the grown sphere off its cap \
                                    plane (the cap vanishes) — refusing"
                                .into(),
                        );
                    }
                    crate::make_arc(
                        center.add(axis.scale(a)),
                        seam_x,
                        seam_y,
                        rr2.sqrt(),
                        0.0,
                        std::f64::consts::TAU,
                    )?
                }
                RimKind::NeighbourSphere => {
                    return Err(
                        "offset_sphere_face: a sphere neighbour whose rim crosses the \
                                pushed sphere's seam is deferred in this slice"
                            .into(),
                    )
                }
                RimKind::CoaxialRuled => {
                    // A coaxial ruled neighbour meets the sphere in latitude
                    // circles. The analytic intersector below constructs them
                    // in the pushed sphere's revolution frame, so the selected
                    // circle starts on this same seam and can move the coupled
                    // meridian exactly.
                    let (ns, nf) = find_face(solid, *neighbour).unwrap();
                    let neighbour_surface = &solid.shells[ns].faces[nf].surface;
                    let curves = intersect_analytic_pair(&s_prime, neighbour_surface, tolerance)
                        .filter(|curves| !curves.is_empty())
                        .ok_or_else(|| {
                            "offset_sphere_face: the grown sphere no longer meets its coaxial \
                             cylinder/cone neighbour — refusing"
                                .to_string()
                        })?;
                    let old_mid = edge.curve.evaluate(0.5 * (edge.t0 + edge.t1))?;
                    nearest_circle(&curves, old_mid)?
                }
            }
        } else {
            let (ns, nf) = find_face(solid, *neighbour).unwrap();
            let neighbour_surface = &solid.shells[ns].faces[nf].surface;
            let curves = intersect_analytic_pair(&s_prime, neighbour_surface, tolerance)
                .filter(|curves| !curves.is_empty())
                .ok_or_else(|| {
                    "offset_sphere_face: the grown sphere no longer meets a neighbour (the cap \
                     vanishes / tangent / separated) — refusing"
                        .to_string()
                })?;
            let old_mid = edge.curve.evaluate(0.5 * (edge.t0 + edge.t1))?;
            nearest_circle(&curves, old_mid)?
        };

        // Match the new rim's traversal to the old edge so the preserved coedge
        // `forward` flags keep the loop winding consistent.
        let closure_old = edge.curve.evaluate(edge.t0)?;
        let old_tan = edge
            .curve
            .evaluate(edge.t0 + 0.01 * (edge.t1 - edge.t0))?
            .sub(closure_old);
        let [c0, c1] = circle.domain()?;
        let new_start = circle.evaluate(c0)?;
        let new_tan = circle.evaluate(c0 + 0.01 * (c1 - c0))?.sub(new_start);
        if old_tan.dot(new_tan) < 0.0 {
            circle = circle.reversed()?;
        }
        let closure_point = circle.evaluate(circle.domain()?[0])?;
        let pushed_pcurve = build_pcurve_on_surface(&s_prime, &circle)?;
        // The rim's v on the offset sphere (constant for a latitude rim; only the
        // seam-coupled meridian rebuild consumes it).
        let [q0, q1] = pushed_pcurve.domain()?;
        let v_rim = pushed_pcurve.evaluate(0.5 * (q0 + q1))?.y;

        rim_builds.push(RimBuild {
            edge_id: *edge_id,
            neighbour_id: *neighbour,
            neighbour_is_sphere: matches!(kind, RimKind::NeighbourSphere),
            closure_vertex,
            circle,
            closure_point,
            v_rim,
            pushed_pcurve,
        });
    }

    // The offset sphere's u = 0 seam meridian (parameterised by v exactly: an
    // iso-curve preserves the surface v-parameter, so a straight (u, v) pcurve
    // stays synchronised with it — a fresh `make_arc` would not).
    let iso_meridian = s_prime.iso_curve_u(0.0)?;

    // --- Apply to a fresh clone (the input is never mutated) ---------------
    let mut result = solid.clone();

    // Scale the intrinsic own-only edges + any through-centre great-circle rims.
    for edge in &mut result.edges {
        if edges_to_scale.contains(&edge.id) {
            edge.curve = transform_curve(&edge.curve, scale_about_center)?;
        }
    }
    // Recomputed rim edges take their new circle.
    for rb in &rim_builds {
        if let Some(edge) = result.edges.iter_mut().find(|e| e.id == rb.edge_id) {
            let [d0, d1] = rb.circle.domain()?;
            edge.curve = rb.circle.clone();
            edge.t0 = d0;
            edge.t1 = d1;
        }
    }
    // Rebuild each seam-coupled own edge as the matching v-subrange of the
    // offset meridian. The fixed endpoint can be a pole or another trim split.
    for mer in &coupled_meridians {
        let e = *edge_by_id.get(mer).unwrap();
        let cv = if closure_vertices.contains(&e.start_vertex_id) {
            e.start_vertex_id
        } else {
            e.end_vertex_id
        };
        let v_rim = rim_builds
            .iter()
            .find(|rb| rb.closure_vertex == cv)
            .map(|rb| rb.v_rim)
            .ok_or_else(|| {
                "offset_sphere_face: a seam meridian is not paired with a rim — refusing"
                    .to_string()
            })?;
        let closure_at_start = e.start_vertex_id == cv;
        let fixed_vertex = if closure_at_start {
            e.end_vertex_id
        } else {
            e.start_vertex_id
        };
        let fixed_old = solid
            .vertices
            .iter()
            .find(|v| v.id == fixed_vertex)
            .map(|v| v.point)
            .ok_or_else(|| format!("offset_sphere_face: missing seam vertex {fixed_vertex}"))?;
        let fixed_new = scale_about_center.point(fixed_old);
        let fixed_projection = project_point_to_curve(&iso_meridian, fixed_new)?;
        if fixed_projection.distance > plane_tolerance {
            return Err(format!(
                "offset_sphere_face: a coupled own-edge is not on the sphere seam \
                 (off by {:.3e}) — refusing",
                fixed_projection.distance
            ));
        }
        let v_start = if closure_at_start {
            v_rim
        } else {
            fixed_projection.u
        };
        let v_end = if closure_at_start {
            fixed_projection.u
        } else {
            v_rim
        };
        let (curve, t0, t1) = if v_start <= v_end {
            (iso_meridian.clone(), v_start, v_end)
        } else {
            (
                iso_meridian.reversed()?,
                dv0 + dv1 - v_start,
                dv0 + dv1 - v_end,
            )
        };
        if let Some(edge) = result.edges.iter_mut().find(|x| x.id == *mer) {
            edge.curve = curve;
            edge.t0 = t0;
            edge.t1 = t1;
        }
    }

    // Vertices: scale the intrinsic ones, relocate the rim-closure ones.
    for vertex in &mut result.vertices {
        if vertices_to_scale.contains(&vertex.id) {
            vertex.point = scale_about_center.point(vertex.point);
        }
    }
    for rb in &rim_builds {
        if let Some(v) = result.vertices.iter_mut().find(|v| v.id == rb.closure_vertex) {
            v.point = rb.closure_point;
        }
    }

    // The pushed face rides the offset carrier. Own-only + through-centre pcurves
    // are preserved (scale-invariant in (u, v)); recomputed rims and coupled
    // meridians get fresh pcurves.
    {
        let pface_rec = &mut result.shells[pshell].faces[pface];
        for loop_record in &mut pface_rec.loops {
            for coedge in &mut loop_record.coedges {
                if let Some(rb) = rim_builds.iter().find(|rb| rb.edge_id == coedge.edge_id) {
                    let mut pcurve = rb.pushed_pcurve.clone();
                    if !coedge.forward {
                        pcurve = pcurve.reversed()?;
                    }
                    coedge.pcurve = pcurve;
                } else if coupled_meridians.contains(&coedge.edge_id) {
                    let e = *edge_by_id.get(&coedge.edge_id).unwrap();
                    let cv = if closure_vertices.contains(&e.start_vertex_id) {
                        e.start_vertex_id
                    } else {
                        e.end_vertex_id
                    };
                    let v_rim = rim_builds
                        .iter()
                        .find(|rb| rb.closure_vertex == cv)
                        .map(|rb| rb.v_rim)
                        .unwrap();
                    let closure_at_pcurve_start = (e.start_vertex_id == cv) == coedge.forward;
                    coedge.pcurve =
                        patch_meridian_pcurve(&coedge.pcurve, v_rim, closure_at_pcurve_start)?;
                }
            }
        }
    }
    result.shells[pshell].faces[pface].surface = s_prime;

    // A coaxial ruled neighbour has its own straight seam meridian ending at
    // the shared rim's relocated closure vertex. Rebuild that seam between its
    // current endpoints before extending/retrimming the neighbour carrier.
    let result_vertex: HashMap<u64, Vec3> =
        result.vertices.iter().map(|v| (v.id, v.point)).collect();
    let mut ruled_seams: HashSet<u64> = HashSet::default();
    for rb in &rim_builds {
        let (ns, nf) = find_face(&result, rb.neighbour_id)
            .ok_or_else(|| format!("offset_sphere_face: missing neighbour {}", rb.neighbour_id))?;
        if !matches!(
            result.shells[ns].faces[nf].surface.analytic(),
            Some(AnalyticSurface::RuledRevolution { .. })
        ) {
            continue;
        }
        for loop_record in &result.shells[ns].faces[nf].loops {
            for coedge in &loop_record.coedges {
                let edge = *edge_by_id.get(&coedge.edge_id).ok_or_else(|| {
                    format!("offset_sphere_face: missing edge {}", coedge.edge_id)
                })?;
                let incident = faces_of_edge.get(&edge.id).cloned().unwrap_or_default();
                let is_seam = incident.iter().all(|f| *f == rb.neighbour_id);
                let touches_rim = closure_vertices.contains(&edge.start_vertex_id)
                    || closure_vertices.contains(&edge.end_vertex_id);
                if is_seam && touches_rim {
                    ruled_seams.insert(edge.id);
                }
            }
        }
    }
    let rebuilt_ruled_seams: HashSet<u64> = ruled_seams.iter().copied().collect();
    for seam_id in ruled_seams {
        let edge = *edge_by_id
            .get(&seam_id)
            .ok_or_else(|| format!("offset_sphere_face: missing ruled seam {seam_id}"))?;
        let curve = make_line(
            result_vertex[&edge.start_vertex_id],
            result_vertex[&edge.end_vertex_id],
        )?;
        if let Some(out) = result
            .edges
            .iter_mut()
            .find(|candidate| candidate.id == seam_id)
        {
            let [t0, t1] = curve.domain()?;
            out.curve = curve;
            out.t0 = t0;
            out.t1 = t1;
        }
    }

    // --- FIXED edges that END on a relocated rim corner --------------------
    //
    // Reported 2026-09-01 ("Push face fails"): a spherical pocket in a box
    // CORNER — three quarter-circle rims, each on a box plane through the
    // sphere centre — pushed inward produced a solid the validator rejected
    // with `edge 1 curve start does not match vertex 1 (gap=1.5)`.
    //
    // Why nothing caught it. A recomputed rim must be a single CLOSED edge
    // (the guard a hundred lines up); the EXACT-SCALE path a through-centre
    // plane takes has no such guard, because a closed great circle has no
    // endpoint to leave behind. An OPEN rim arc has two, and each is also the
    // end of a FIXED edge of the two neighbour planes — the box's own axis
    // edge. The push scales the corner radially; that edge's CURVE does not
    // move (a plane × plane line the push does not touch) but its TRIM must
    // follow the corner, or the solid carries an edge whose curve no longer
    // reaches its own vertex.
    //
    // The slide is a re-parameterisation, not a re-solve, and provably so: a
    // corner of an exact-scale rim is shared by two planes that BOTH pass
    // through the sphere centre (that is what put the rim on this path), so
    // their intersection line passes through the centre and the uniform scale
    // about the centre maps the corner along it exactly. The projection below
    // is the PROOF of that, not a fit — a corner that does not land on its own
    // fixed edge (a rim whose neighbour is off-centre, or a corner against a
    // curved carrier) refuses instead of being nudged.
    let mut relocated: HashMap<u64, Vec3> = HashMap::default();
    for vertex in &result.vertices {
        let Some(old) = solid.vertices.iter().find(|o| o.id == vertex.id) else {
            continue;
        };
        if vertex.point.sub(old.point).length() > tolerance {
            relocated.insert(vertex.id, vertex.point);
        }
    }
    let already_rebuilt: HashSet<u64> = edges_to_scale
        .iter()
        .copied()
        .chain(rim_builds.iter().map(|rb| rb.edge_id))
        .chain(coupled_meridians.iter().copied())
        .chain(rebuilt_ruled_seams.iter().copied())
        .collect();
    let mut resized_edges: HashSet<u64> = HashSet::default();
    for edge in &mut result.edges {
        if edge.degenerate || already_rebuilt.contains(&edge.id) {
            continue;
        }
        for at_start in [true, false] {
            let vertex_id = if at_start {
                edge.start_vertex_id
            } else {
                edge.end_vertex_id
            };
            let Some(&target) = relocated.get(&vertex_id) else {
                continue;
            };
            let projection = project_point_to_curve(&edge.curve, target)?;
            if projection.distance > 10.0 * tolerance {
                return Err(format!(
                    "offset_sphere_face: the push moves rim corner (vertex {vertex_id}) OFF \
                     fixed edge {} by {:.3e} — a rim corner that leaves its own side edge \
                     needs the corner re-solved against the neighbour carriers, which is \
                     deferred — refusing",
                    edge.id, projection.distance
                ));
            }
            let [d0, d1] = edge.curve.domain()?;
            let span = (d1 - d0).max(1e-12);
            let fixed_t = if at_start { edge.t1 } else { edge.t0 };
            let old_t = if at_start { edge.t0 } else { edge.t1 };
            let new_t = projection.u;
            if (new_t - fixed_t) * (old_t - fixed_t) <= 0.0
                || (new_t - fixed_t).abs() <= 1e-7 * span
            {
                return Err(format!(
                    "offset_sphere_face: the push collapses or inverts the trim of fixed edge \
                     {} at rim corner (vertex {vertex_id}) — refusing",
                    edge.id
                ));
            }
            if at_start {
                edge.t0 = new_t;
            } else {
                edge.t1 = new_t;
            }
            resized_edges.insert(edge.id);
        }
    }

    // Re-trim the neighbours around their new rims.
    let final_edges: HashMap<u64, EdgeRecord> =
        result.edges.iter().map(|e| (e.id, e.clone())).collect();
    for rb in &rim_builds {
        let (ns, nf) = find_face(&result, rb.neighbour_id)
            .ok_or_else(|| format!("offset_sphere_face: missing neighbour {}", rb.neighbour_id))?;
        if rb.neighbour_is_sphere {
            // A fixed sphere neighbour: only the shared rim coedge's pcurve moves.
            let nsurf = result.shells[ns].faces[nf].surface.clone();
            for loop_record in &mut result.shells[ns].faces[nf].loops {
                for coedge in &mut loop_record.coedges {
                    if coedge.edge_id == rb.edge_id {
                        let mut pcurve = build_pcurve_on_surface(&nsurf, &rb.circle)?;
                        if !coedge.forward {
                            pcurve = pcurve.reversed()?;
                        }
                        coedge.pcurve = pcurve;
                    }
                }
            }
        } else if matches!(
            result.shells[ns].faces[nf].surface.analytic(),
            Some(AnalyticSurface::RuledRevolution { .. })
        ) {
            super::face_offset::retrim_offset_ruled_face(
                &mut result,
                rb.neighbour_id,
                &final_edges,
                tolerance,
            )?;
        } else {
            let plane = plane_of_surface(
                &result.shells[ns].faces[nf].surface,
                plane_tolerance,
                "offset_sphere_face",
            )?;
            retrim_planar_face(
                &mut result.shells[ns].faces[nf],
                &plane,
                &final_edges,
                scale,
                "offset_sphere_face",
            )?;
            refit_subrange_pcurves(
                &mut result.shells[ns].faces[nf],
                &final_edges,
                tolerance,
            )?;
        }
    }
    // Through-centre planar caps re-trim around their grown great-circle rims.
    for cap in &through_centre_caps {
        let (cshell, cface) = find_face(&result, *cap)
            .ok_or_else(|| format!("offset_sphere_face: missing cap {cap}"))?;
        let plane = plane_of_surface(
            &result.shells[cshell].faces[cface].surface,
            plane_tolerance,
            "offset_sphere_face",
        )?;
        retrim_planar_face(
            &mut result.shells[cshell].faces[cface],
            &plane,
            &final_edges,
            scale,
            "offset_sphere_face",
        )?;
        refit_subrange_pcurves(
            &mut result.shells[cshell].faces[cface],
            &final_edges,
            tolerance,
        )?;
    }
    // Any OTHER face carrying an edge whose trim the corner slide moved keeps
    // its carrier — only the pcurve of that one coedge has to be re-fitted over
    // the new `[t0, t1]`.
    for shell in &mut result.shells {
        for face in &mut shell.faces {
            if face
                .loops
                .iter()
                .flat_map(|l| &l.coedges)
                .any(|c| resized_edges.contains(&c.edge_id))
            {
                refit_touched_pcurves(
                    face,
                    &final_edges,
                    &resized_edges,
                    true,
                    tolerance,
                    "offset_sphere_face",
                )?;
            }
        }
    }

    let issues = result.validate();
    if !issues.is_empty() {
        return Err(format!(
            "offset_sphere_face: pushed solid failed validation: {issues:?}"
        ));
    }
    if let (Ok(before), Ok(after)) = (solid_signed_volume(solid), solid_signed_volume(&result)) {
        if before * after <= 0.0 {
            return Err("offset_sphere_face: the push inverts the solid — refusing".into());
        }
    }
    Ok(result)
}

/// `retrim_planar_face` rebuilds every pcurve with [`PcurveFit::WholeCurve`],
/// which maps an edge's WHOLE curve onto the fresh carrier. That is right for a
/// full-domain edge and WRONG for an edge that is a strict SUBRANGE of its own
/// curve: `validate()` samples a pcurve over its whole domain against the edge
/// over `[t0, t1]`, so the pcurve of a partially-trimmed edge reads as a
/// deviation the size of the trimmed-off overhang. `move_faces` has always
/// paired its planar re-trim with this pass (`face_move.rs`, the
/// `refit_touched_pcurves` call after `retrim_planar_face`); the sphere push
/// did not, which is what made a spherical pocket in a box CORNER fail
/// validation with `max deviation 5.000000` — exactly the length of box edge
/// the original sphere had trimmed away.
///
/// `only_subrange = true`, so a face whose edges are all full-domain — every
/// shape the corpus covers — keeps byte-identical pcurves.
fn refit_subrange_pcurves(
    face: &mut FaceRecord,
    edges: &HashMap<u64, EdgeRecord>,
    tolerance: f64,
) -> Result<(), String> {
    let face_edges: HashSet<u64> = face
        .loops
        .iter()
        .flat_map(|loop_record| loop_record.coedges.iter().map(|c| c.edge_id))
        .collect();
    refit_touched_pcurves(
        face,
        edges,
        &face_edges,
        true,
        tolerance,
        "offset_sphere_face",
    )
}

/// The intersection circle whose parameter-midpoint is nearest `reference`
/// (branch selection when S′ ∩ neighbour returns more than one component).
fn nearest_circle(curves: &[NurbsCurve], reference: Vec3) -> Result<NurbsCurve, String> {
    let mut best: Option<(f64, &NurbsCurve)> = None;
    for curve in curves {
        let [d0, d1] = curve.domain()?;
        let mid = curve.evaluate(0.5 * (d0 + d1))?;
        let distance = mid.sub(reference).length();
        if best.map(|(known, _)| distance < known).unwrap_or(true) {
            best = Some((distance, curve));
        }
    }
    best.map(|(_, curve)| curve.clone())
        .ok_or_else(|| "offset_sphere_face: the sphere ∩ neighbour intersection is empty".into())
}

/// Move a seam-meridian pcurve's RIM endpoint to the new latitude `v_new`,
/// keeping its pole endpoint and constant u. The pcurve is a straight (u, v)
/// parameter line; the pole endpoint is the one whose v is at a domain end
/// (0 or 1); the other endpoint is the rim that the offset relocated.
fn patch_meridian_pcurve(
    pcurve: &NurbsCurve,
    v_new: f64,
    closure_at_start: bool,
) -> Result<NurbsCurve, String> {
    let [q0, q1] = pcurve.domain()?;
    let start = pcurve.evaluate(q0)?;
    let end = pcurve.evaluate(q1)?;
    let (v_start, v_end) = if closure_at_start {
        (v_new, end.y)
    } else {
        (start.y, v_new)
    };
    make_line(
        Vec3::new(start.x, v_start, 0.0),
        Vec3::new(end.x, v_end, 0.0),
    )
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{make_sphere_brep, AnalyticSurface};

    fn sphere_face_id(solid: &BrepSolid) -> u64 {
        solid
            .shells
            .iter()
            .flat_map(|shell| &shell.faces)
            .find(|face| {
                matches!(
                    face.surface.analytic(),
                    Some(AnalyticSurface::Sphere { .. })
                )
            })
            .expect("a spherical face")
            .id
    }

    fn sphere_radius(solid: &BrepSolid) -> f64 {
        solid
            .shells
            .iter()
            .flat_map(|shell| &shell.faces)
            .find_map(|face| match face.surface.analytic() {
                Some(AnalyticSurface::Sphere { radius, .. }) => Some(*radius),
                _ => None,
            })
            .expect("a spherical radius")
    }

    // Radius, measured off the given axis, of the rim edge shared between the
    // spherical face and a PLANAR neighbour (the small-circle cap rim).
    fn rim_radius_off_axis(solid: &BrepSolid, axis_point: Vec3, axis: Vec3) -> f64 {
        let mut faces_of_edge: std::collections::HashMap<u64, Vec<u64>> = Default::default();
        let mut kind: std::collections::HashMap<u64, &'static str> = Default::default();
        for shell in &solid.shells {
            for face in &shell.faces {
                let k = match face.surface.analytic() {
                    Some(AnalyticSurface::Sphere { .. }) => "sphere",
                    Some(AnalyticSurface::Plane { .. }) => "plane",
                    _ => "other",
                };
                kind.insert(face.id, k);
                for lp in &face.loops {
                    for ce in &lp.coedges {
                        faces_of_edge.entry(ce.edge_id).or_default().push(face.id);
                    }
                }
            }
        }
        for edge in &solid.edges {
            if edge.degenerate {
                continue;
            }
            let incident = faces_of_edge.get(&edge.id).cloned().unwrap_or_default();
            let has_sphere = incident.iter().any(|f| kind.get(f) == Some(&"sphere"));
            let has_plane = incident.iter().any(|f| kind.get(f) == Some(&"plane"));
            if has_sphere && has_plane {
                let point = edge.curve.evaluate(0.5 * (edge.t0 + edge.t1)).unwrap();
                let delta = point.sub(axis_point);
                let radial = delta.sub(axis.scale(delta.dot(axis)));
                return radial.length();
            }
        }
        panic!("no sphere×plane rim edge found");
    }


    // --- open (multi-arc) rims: the corners the exact-scale path must carry ---

    /// The 2026-09-01 inbox report's shape, at the direct entry: a sphere
    /// SUBTRACTED at a box's own corner, so the cavity is a spherical OCTANT
    /// whose rim is three quarter-circle arcs — one on each of the three box
    /// planes meeting there, all three through the sphere centre, so all three
    /// take the exact-scale path.
    fn box_corner_pocket(size: f64, radius: f64) -> BrepSolid {
        let block = crate::make_box_brep(Vec3::default(), size, size, size).unwrap();
        let ball =
            make_sphere_brep(Vec3::default(), radius, Vec3::new(0.0, 0.0, 1.0)).unwrap();
        crate::boolean_operation(
            &block,
            &ball,
            crate::BooleanOperation::Subtract,
            &crate::BooleanOptions {
                merge_coplanar_faces: true,
                ..crate::BooleanOptions::default()
            },
        )
        .expect("box − corner ball")
    }

    /// Every edge's trimmed curve must reach the vertex it is registered
    /// against. The reported failure was three box edges whose curve still
    /// started `gap = 1.5` — the push distance — away from their own corner.
    fn every_edge_reaches_its_vertices(solid: &BrepSolid) {
        for edge in &solid.edges {
            if edge.degenerate {
                continue;
            }
            for (parameter, vertex_id) in [
                (edge.t0, edge.start_vertex_id),
                (edge.t1, edge.end_vertex_id),
            ] {
                let point = edge.curve.evaluate(parameter).expect("edge evaluates");
                let vertex = solid
                    .vertices
                    .iter()
                    .find(|v| v.id == vertex_id)
                    .unwrap_or_else(|| panic!("missing vertex {vertex_id}"));
                let gap = point.sub(vertex.point).length();
                assert!(
                    gap < 1e-9,
                    "edge {} does not reach vertex {vertex_id}: gap {gap}",
                    edge.id
                );
            }
        }
    }

    /// An OPEN rim — three arcs, not one closed circle — pushed both ways. The
    /// exact-scale path carries each arc's corner radially and the box edge that
    /// ends there must follow. The oracle is independent of the kernel's
    /// geometry: a spherical OCTANT cavity changing from `r` to `r′` moves
    /// exactly `(π/6)(r³ − r′³)` of material, whatever else is in the part.
    #[test]
    fn push_a_spherical_pocket_in_a_box_corner_carries_its_rim_corners() {
        let (size, radius) = (20.0_f64, 5.0_f64);
        let solid = box_corner_pocket(size, radius);
        assert!(solid.validate().is_empty(), "fixture: {:?}", solid.validate());
        // Fixture guard: the rim really is OPEN — three arcs, no closed circle.
        let face = sphere_face_id(&solid);
        let rim: Vec<&EdgeRecord> = solid
            .shells
            .iter()
            .flat_map(|shell| &shell.faces)
            .filter(|f| f.id == face)
            .flat_map(|f| &f.loops)
            .flat_map(|l| &l.coedges)
            .filter_map(|c| solid.edges.iter().find(|e| e.id == c.edge_id))
            .collect();
        assert_eq!(rim.len(), 3, "an octant cavity has three rim arcs");
        assert!(
            rim.iter().all(|e| e.start_vertex_id != e.end_vertex_id),
            "every rim arc must be OPEN — a closed rim never reaches this path"
        );
        let before = solid_signed_volume(&solid).unwrap().abs();

        for distance in [1.5_f64, -1.5, 3.0, -3.0] {
            let pushed = offset_sphere_face(&solid, face, distance)
                .unwrap_or_else(|e| panic!("pocket push {distance}: {e}"));
            let issues = pushed.validate();
            assert!(issues.is_empty(), "push {distance} is invalid: {issues:?}");
            every_edge_reaches_its_vertices(&pushed);
            // A pocket's outward normal points INTO the solid, so a positive
            // push (more material) SHRINKS the cavity.
            let shrunk = radius - distance;
            assert!(
                (sphere_radius(&pushed) - shrunk).abs() < 1e-9,
                "push {distance}: radius {} vs {shrunk}",
                sphere_radius(&pushed)
            );
            let gained = solid_signed_volume(&pushed).unwrap().abs() - before;
            let expected =
                std::f64::consts::PI / 6.0 * (radius.powi(3) - shrunk.powi(3));
            // `solid_signed_volume` integrates a spherical patch numerically, so
            // the oracle is compared RELATIVELY. Measured here: 8.7e-4 on 43.0,
            // 1.6e-3 on 78.3, 1.2e-3 on 61.3, 4.1e-3 on 202.6 — a flat 2e-5
            // relative, so 1e-4 is a 5x margin over the quadrature and three
            // orders tighter than any heal error: a corner left behind moves
            // whole units of material, not thousandths.
            assert!(
                (gained - expected).abs() < 1e-4 * expected.abs(),
                "push {distance}: gained {gained}, expected {expected}"
            );
            assert_eq!(pushed.edges.len(), solid.edges.len(), "topology untouched");
            assert_eq!(
                pushed.vertices.len(),
                solid.vertices.len(),
                "topology untouched"
            );
        }
        assert!(solid.validate().is_empty(), "the input is never mutated");
    }

    /// The bound on the same push, and the guard that states it. Growing the
    /// pocket slides each rim corner along its box edge toward the FAR end; at
    /// `r = size` the corner reaches that end and the box edge's trim collapses.
    /// The push just inside the bound still works, which is what makes this a
    /// bound and not a blanket refusal.
    #[test]
    fn growing_a_corner_pocket_until_its_rim_corner_reaches_the_far_end_refuses() {
        let (size, radius) = (20.0_f64, 5.0_f64);
        let solid = box_corner_pocket(size, radius);
        let face = sphere_face_id(&solid);
        // Just inside: r = 19.5 on a 20 box.
        let ok = offset_sphere_face(&solid, face, -(size - radius - 0.5))
            .expect("a pocket that still leaves a sliver of box edge heals");
        assert!(ok.validate().is_empty(), "{:?}", ok.validate());
        every_edge_reaches_its_vertices(&ok);
        // At and past it: r >= 20, so the corner lands on (or past) the far
        // vertex of every box axis edge.
        // Exactly at the far end (r = 20 on a 20 box): the corner lands ON the
        // box edge's other vertex, so the trim collapses.
        let collapse = offset_sphere_face(&solid, face, -(size - radius))
            .expect_err("a rim corner exactly at the far end must refuse");
        assert!(
            collapse.contains("collapses or inverts the trim of fixed edge"),
            "expected the trim-collapse guard, got: {collapse}"
        );
        // Past it: the scaled corner is no longer ON the box edge at all, which
        // is the guard that keeps the slide a re-parameterisation rather than a
        // nudge onto the nearest point of a curve it has left.
        for over in [0.5_f64, 5.0] {
            let error = offset_sphere_face(&solid, face, -(size - radius) - over)
                .expect_err("a rim corner past the end of its own edge must refuse");
            assert!(
                error.contains("moves rim corner") && error.contains("OFF fixed edge"),
                "expected the corner-off-its-edge guard, got: {error}"
            );
        }
        assert!(solid.validate().is_empty(), "the input is never mutated");
    }

    // A FULL sphere pushed OUT (radius grows) and IN (radius shrinks): the carrier
    // becomes a concentric sphere, no neighbours, and the volume is exactly the
    // ball volume on the new radius. The pure-scale base case.
    #[test]
    fn push_full_sphere_changes_radius() {
        for (d, r_new) in [(2.0_f64, 7.0_f64), (-2.0, 3.0)] {
            let sphere =
                make_sphere_brep(Vec3::default(), 5.0, Vec3::new(0.0, 0.0, 1.0)).unwrap();
            let face = sphere_face_id(&sphere);
            let pushed = offset_sphere_face(&sphere, face, d)
                .unwrap_or_else(|e| panic!("push full sphere by {d}: {e}"));
            let issues = pushed.validate();
            assert!(issues.is_empty(), "validate {d}: {issues:?}");
            assert!(
                (sphere_radius(&pushed) - r_new).abs() < 1e-9,
                "radius after push {d}: got {}, want {r_new}",
                sphere_radius(&pushed)
            );
            let got = solid_signed_volume(&pushed).unwrap().abs();
            let expected = 4.0 / 3.0 * std::f64::consts::PI * r_new.powi(3);
            assert!(
                (got - expected).abs() < 1e-2,
                "ball volume {got}, want {expected}"
            );
        }
    }

    // A HEMISPHERICAL POCKET: a box with a half-sphere cavity whose rim is a
    // great circle on the box's top face (a plane through the sphere centre).
    // Pushing the spherical face +δ GROWS the solid (fills the cavity → the
    // pocket radius shrinks by δ); −δ deepens it. The top face (multi-loop, the
    // rim is an internal loop) re-trims around the grown great circle.
    #[test]
    fn push_hemispherical_pocket_resizes_the_cavity() {
        let r = 5.0f64;
        for (d, r_new) in [(1.0_f64, 4.0_f64), (-1.0, 6.0)] {
            let block = crate::make_box_brep(Vec3::new(0.0, 0.0, 0.0), 20.0, 20.0, 10.0).unwrap();
            let ball =
                make_sphere_brep(Vec3::new(10.0, 10.0, 10.0), r, Vec3::new(0.0, 0.0, 1.0)).unwrap();
            let options = crate::BooleanOptions {
                merge_coplanar_faces: true,
                ..crate::BooleanOptions::default()
            };
            let pocket = crate::boolean_operation(
                &block,
                &ball,
                crate::BooleanOperation::Subtract,
                &options,
            )
            .unwrap();
            let v0 = solid_signed_volume(&pocket).unwrap().abs();
            let face = sphere_face_id(&pocket);

            let pushed = offset_sphere_face(&pocket, face, d)
                .unwrap_or_else(|e| panic!("push pocket by {d}: {e}"));
            let issues = pushed.validate();
            assert!(issues.is_empty(), "validate {d}: {issues:?}");
            assert!(
                (sphere_radius(&pushed) - r_new).abs() < 1e-6,
                "pocket radius after push {d}: got {}, want {r_new}",
                sphere_radius(&pushed)
            );
            // The cavity is a hemisphere (2/3 π r³). Growing the solid by +d
            // shrinks the cavity from r to r_new, adding 2/3 π (r³ − r_new³).
            let got = solid_signed_volume(&pushed).unwrap().abs();
            let cavity_before = 2.0 / 3.0 * std::f64::consts::PI * r.powi(3);
            let cavity_after = 2.0 / 3.0 * std::f64::consts::PI * r_new.powi(3);
            let expected = v0 + (cavity_before - cavity_after);
            assert!(
                (got - expected).abs() < 1e-2,
                "pocket push {d}: volume {got}, want {expected}"
            );
        }
    }

    // Pushing a full sphere IN by its whole radius (or past it) must refuse, not
    // emit a degenerate/inverted solid.
    #[test]
    fn push_full_sphere_through_centre_refuses() {
        let sphere = make_sphere_brep(Vec3::default(), 5.0, Vec3::new(0.0, 0.0, 1.0)).unwrap();
        let face = sphere_face_id(&sphere);
        let err = offset_sphere_face(&sphere, face, -5.0).expect_err("collapse must refuse");
        assert!(err.contains("centre") || err.contains("refus"), "unexpected: {err}");
    }

    // The off-centre small-circle cap (rim plane above the sphere centre): the
    // fixed box-top plane (z=10) cuts the sphere off-centre by h=3. Building the
    // pocket keeps the LOWER cap (south pole), so its outward normal points into
    // the void → a positive push SHRINKS the cavity (r_new = r − d). After the
    // push the rim is the small circle where z=10 meets the grown sphere, radius
    // √(r_new² − h²); the seam meridian rebuilds to the new latitude.
    #[test]
    fn push_offcentre_spherical_cap_resizes() {
        let r = 5.0f64;
        let h = 3.0f64; // plane z=10, centre z=7.
        for (d, r_new) in [(1.0_f64, 4.0_f64), (-1.0, 6.0)] {
            let block = crate::make_box_brep(Vec3::new(0.0, 0.0, 0.0), 20.0, 20.0, 10.0).unwrap();
            let ball =
                make_sphere_brep(Vec3::new(10.0, 10.0, 7.0), r, Vec3::new(0.0, 0.0, 1.0)).unwrap();
            let options = crate::BooleanOptions {
                merge_coplanar_faces: true,
                ..crate::BooleanOptions::default()
            };
            let pocket = crate::boolean_operation(
                &block,
                &ball,
                crate::BooleanOperation::Subtract,
                &options,
            )
            .unwrap();
            let face = sphere_face_id(&pocket);
            let pushed = offset_sphere_face(&pocket, face, d)
                .unwrap_or_else(|e| panic!("push off-centre cap by {d}: {e}"));
            let issues = pushed.validate();
            assert!(issues.is_empty(), "validate {d}: {issues:?}");
            assert!(
                (sphere_radius(&pushed) - r_new).abs() < 1e-6,
                "off-centre cap radius after push {d}: got {}, want {r_new}",
                sphere_radius(&pushed)
            );
            // The rim is the small circle where z=10 meets the grown sphere.
            let want_rim = (r_new * r_new - h * h).sqrt();
            let got_rim = rim_radius_off_axis(
                &pushed,
                Vec3::new(10.0, 10.0, 0.0),
                Vec3::new(0.0, 0.0, 1.0),
            );
            assert!(
                (got_rim - want_rim).abs() < 1e-6,
                "rim radius after push {d}: got {got_rim}, want {want_rim}"
            );
        }
    }

    // Off-centre cap with the rim plane BELOW the centre: box bottom z=0, ball
    // centre z=3, radius 5 (the ball pokes through the bottom, h=3). The kept cap
    // now contains the NORTH pole (z=8), so the seam meridian runs pole→rim with
    // its pole at v=1 — exercising the reversed iso-meridian subrange and the
    // north-pole detection that the above-centre fixture never touches.
    #[test]
    fn push_offcentre_northern_cap_resizes() {
        let r = 5.0f64;
        let h = 3.0f64; // plane z=0, centre z=3.
        for (d, r_new) in [(1.0_f64, 4.0_f64), (-1.0, 6.0)] {
            let block = crate::make_box_brep(Vec3::new(0.0, 0.0, 0.0), 20.0, 20.0, 10.0).unwrap();
            let ball =
                make_sphere_brep(Vec3::new(10.0, 10.0, 3.0), r, Vec3::new(0.0, 0.0, 1.0)).unwrap();
            let options = crate::BooleanOptions {
                merge_coplanar_faces: true,
                ..crate::BooleanOptions::default()
            };
            let pocket = crate::boolean_operation(
                &block,
                &ball,
                crate::BooleanOperation::Subtract,
                &options,
            )
            .unwrap();
            let face = sphere_face_id(&pocket);
            let pushed = offset_sphere_face(&pocket, face, d)
                .unwrap_or_else(|e| panic!("push northern off-centre cap by {d}: {e}"));
            let issues = pushed.validate();
            assert!(issues.is_empty(), "validate {d}: {issues:?}");
            assert!(
                (sphere_radius(&pushed) - r_new).abs() < 1e-6,
                "northern cap radius after push {d}: got {}, want {r_new}",
                sphere_radius(&pushed)
            );
            let want_rim = (r_new * r_new - h * h).sqrt();
            let got_rim = rim_radius_off_axis(
                &pushed,
                Vec3::new(10.0, 10.0, 0.0),
                Vec3::new(0.0, 0.0, 1.0),
            );
            assert!(
                (got_rim - want_rim).abs() < 1e-6,
                "northern rim radius after push {d}: got {got_rim}, want {want_rim}"
            );
        }
    }

    // Pushing the off-centre cap OUT far enough that the grown sphere no longer
    // reaches the fixed plane (r_new = 2.5 < h = 3) must refuse cleanly.
    #[test]
    fn push_offcentre_cap_vanish_refuses() {
        let block = crate::make_box_brep(Vec3::new(0.0, 0.0, 0.0), 20.0, 20.0, 10.0).unwrap();
        let ball =
            make_sphere_brep(Vec3::new(10.0, 10.0, 7.0), 5.0, Vec3::new(0.0, 0.0, 1.0)).unwrap();
        let options = crate::BooleanOptions {
            merge_coplanar_faces: true,
            ..crate::BooleanOptions::default()
        };
        let pocket =
            crate::boolean_operation(&block, &ball, crate::BooleanOperation::Subtract, &options)
                .unwrap();
        let face = sphere_face_id(&pocket);
        // Positive push SHRINKS the pocket sphere; d=2.5 → r_new=2.5 < h=3.
        let err = offset_sphere_face(&pocket, face, 2.5).expect_err("a vanished cap must refuse");
        assert!(
            err.contains("vanish") || err.contains("collapse") || err.contains("centre"),
            "unexpected refusal: {err}"
        );
    }

    // SPHERE × SPHERE: the union of two overlapping balls; each spherical face's
    // rim neighbour is the OTHER sphere. Pushing one sphere out grows its radius,
    // moving the intersection circle to intersect_sphere_sphere(grown, fixed).
    // Both spheres re-trim around the new circle.
    #[test]
    fn push_sphere_with_sphere_neighbour_resizes() {
        for (d, r_new) in [(1.0_f64, 7.0_f64), (-1.0, 5.0)] {
            let a = make_sphere_brep(Vec3::new(0.0, 0.0, 0.0), 6.0, Vec3::new(0.0, 0.0, 1.0)).unwrap();
            let b = make_sphere_brep(Vec3::new(8.0, 0.0, 0.0), 6.0, Vec3::new(0.0, 0.0, 1.0)).unwrap();
            let options = crate::BooleanOptions {
                merge_coplanar_faces: true,
                ..crate::BooleanOptions::default()
            };
            let uni =
                crate::boolean_operation(&a, &b, crate::BooleanOperation::Union, &options).unwrap();
            // Push sphere A (centred at the origin).
            let face = uni
                .shells
                .iter()
                .flat_map(|shell| &shell.faces)
                .filter(|f| matches!(f.surface.analytic(), Some(AnalyticSurface::Sphere { .. })))
                .find(|f| {
                    matches!(
                        f.surface.analytic(),
                        Some(AnalyticSurface::Sphere { frame, .. }) if frame.origin.length() < 1e-6
                    )
                })
                .expect("sphere A face")
                .id;
            let pushed = offset_sphere_face(&uni, face, d)
                .unwrap_or_else(|e| panic!("push sphere-neighbour by {d}: {e}"));
            let issues = pushed.validate();
            assert!(issues.is_empty(), "validate {d}: {issues:?}");
            // Sphere A's carrier grew to r_new; the fixed B is unchanged (r=6).
            let radii: Vec<f64> = pushed
                .shells
                .iter()
                .flat_map(|shell| &shell.faces)
                .filter_map(|f| match f.surface.analytic() {
                    Some(AnalyticSurface::Sphere { radius, .. }) => Some(*radius),
                    _ => None,
                })
                .collect();
            assert!(
                radii.iter().any(|r| (r - r_new).abs() < 1e-6),
                "grown sphere radius {r_new} not found in {radii:?}"
            );
            assert!(
                radii.iter().any(|r| (r - 6.0).abs() < 1e-6),
                "fixed sphere radius 6 not found in {radii:?}"
            );
        }
    }

    // SPHERE × CYLINDER: a coaxial stem emerging from a ball gives the retained
    // spherical face one cylindrical rim neighbour. Pushing the sphere moves
    // that exact latitude circle and axially re-trims the fixed cylinder wall.
    #[test]
    fn push_sphere_with_coaxial_cylinder_neighbour_resizes() {
        for (d, r_new) in [(0.5_f64, 5.5_f64), (-0.5, 4.5)] {
            let ball = make_sphere_brep(Vec3::default(), 5.0, Vec3::new(0.0, 0.0, 1.0)).unwrap();
            let cylinder = crate::make_cylinder_brep(
                Vec3::new(0.0, 0.0, 3.0),
                Vec3::new(0.0, 0.0, 1.0),
                2.0,
                5.0,
            )
            .unwrap();
            let joined = crate::boolean_operation(
                &ball,
                &cylinder,
                crate::BooleanOperation::Union,
                &crate::BooleanOptions::default(),
            )
            .unwrap();
            let face = sphere_face_id(&joined);
            let pushed = offset_sphere_face(&joined, face, d)
                .unwrap_or_else(|e| panic!("push sphere×cylinder by {d}: {e}"));
            assert!(pushed.validate().is_empty());
            assert!((sphere_radius(&pushed) - r_new).abs() < 1e-6);
            // The cylinder r=2 cuts the grown sphere at z=√(r²−4).
            let want_z = (r_new * r_new - 4.0).sqrt();
            let rim_z = pushed
                .edges
                .iter()
                .filter(|edge| edge.start_vertex_id == edge.end_vertex_id && !edge.degenerate)
                .map(|edge| edge.curve.evaluate(0.5 * (edge.t0 + edge.t1)).unwrap().z)
                .min_by(|a, b| (a - want_z).abs().total_cmp(&(b - want_z).abs()))
                .expect("closed sphere×cylinder rim");
            assert!(
                (rim_z - want_z).abs() < 1e-6,
                "rim z={rim_z}, want {want_z}"
            );
        }
    }

    // SPHERE × CONE uses the same coaxial profile intersector but exercises a
    // sloped ruled generatrix and axial carrier extension.
    #[test]
    fn push_sphere_with_coaxial_cone_neighbour_resizes() {
        for (d, r_new) in [(0.35_f64, 5.35_f64), (-0.35, 4.65)] {
            let ball = make_sphere_brep(Vec3::default(), 5.0, Vec3::new(0.0, 0.0, 1.0)).unwrap();
            let cone = crate::make_cone_brep(
                Vec3::new(0.0, 0.0, 3.0),
                Vec3::new(0.0, 0.0, 1.0),
                2.0,
                1.0,
                5.0,
            )
            .unwrap();
            let joined = crate::boolean_operation(
                &ball,
                &cone,
                crate::BooleanOperation::Union,
                &crate::BooleanOptions::default(),
            )
            .unwrap();
            let face = sphere_face_id(&joined);
            let pushed = offset_sphere_face(&joined, face, d)
                .unwrap_or_else(|e| panic!("push sphere×cone by {d}: {e}"));
            let issues = pushed.validate();
            assert!(issues.is_empty(), "validate {d}: {issues:?}");
            assert!((sphere_radius(&pushed) - r_new).abs() < 1e-6);
            assert!(pushed.shells.iter().flat_map(|s| &s.faces).any(|face| {
                matches!(
                    face.surface.analytic(),
                    Some(AnalyticSurface::RuledRevolution { rho0, rho1, .. })
                        if (rho0 - rho1).abs() > 1e-6
                )
            }));
        }
    }

    // A parallel-offset cylinder has a non-circular spatial intersection with
    // the sphere. Keep that outside this exact coaxial slice and refuse before
    // mutating topology.
    #[test]
    fn push_sphere_with_noncoaxial_cylinder_neighbour_refuses() {
        let ball = make_sphere_brep(Vec3::default(), 5.0, Vec3::new(0.0, 0.0, 1.0)).unwrap();
        let cylinder =
            crate::make_cylinder_brep(Vec3::new(1.0, 0.0, 3.0), Vec3::new(0.0, 0.0, 1.0), 2.0, 5.0)
                .unwrap();
        let joined = crate::boolean_operation(
            &ball,
            &cylinder,
            crate::BooleanOperation::Union,
            &crate::BooleanOptions::default(),
        )
        .unwrap();
        let face = sphere_face_id(&joined);
        let err = offset_sphere_face(&joined, face, 0.25)
            .expect_err("non-coaxial sphere×cylinder must refuse");
        assert!(err.contains("NON-coaxial"), "unexpected refusal: {err}");
        assert!(joined.validate().is_empty(), "the input solid was mutated");
    }

    #[test]
    fn push_sphere_off_coaxial_cylinder_refuses_cleanly() {
        let ball = make_sphere_brep(Vec3::default(), 5.0, Vec3::new(0.0, 0.0, 1.0)).unwrap();
        let cylinder =
            crate::make_cylinder_brep(Vec3::new(0.0, 0.0, 3.0), Vec3::new(0.0, 0.0, 1.0), 2.0, 5.0)
                .unwrap();
        let joined = crate::boolean_operation(
            &ball,
            &cylinder,
            crate::BooleanOperation::Union,
            &crate::BooleanOptions::default(),
        )
        .unwrap();
        let face = sphere_face_id(&joined);
        // r'=1.5 cannot meet the fixed r=2 cylinder, but does not collapse the
        // sphere itself. This must be a typed separation refusal.
        let err = offset_sphere_face(&joined, face, -3.5)
            .expect_err("separated sphere×cylinder must refuse");
        assert!(
            err.contains("no longer meets") || err.contains("refus"),
            "unexpected refusal: {err}"
        );
    }
}