brep_kernel/feature_pipeline/

component.rs

//! The scene COMPONENT concept — assemblies build-spec §3 / §10 item 2.
//!
//! A component is a rigid group of solids inserted by an ACOMP feature (one per
//! placed instance). Its record carries the owning feature id, the library part
//! name, the rigid instance pose, the fixed (grounded) flag, and an opaque source
//! metadata slot; its member solids are ordinary scene-resident solids whose
//! entity names are NAMESPACED with the owning feature id.
//!
//! # Namespacing — the prefix wraps, nothing else moves
//!
//! Every entity name of a member solid (the solid name, every `face.name`, every
//! `edge.name` — the only named entities in this kernel; vertices carry no names)
//! is prefixed with `{component_id}:` AT THE COMPONENT BOUNDARY, i.e. when the
//! sub-part's solids enter the assembly scene:
//!
//! ```text
//!   Extrude1_top            ->  ACOMP2:Extrude1_top
//!   Extrude1|Extrude1_top[0]->  ACOMP2:Extrude1|Extrude1_top[0]
//! ```
//!
//! INSIDE the namespace the deterministic-naming rules apply UNCHANGED: the
//! names arrive final from the sub-part's own `register_added` passes
//! (`ensure_unique_face_names` + `stamp_derived_edge_names`) and are NEVER
//! re-derived here. Re-running the derived-edge pass after prefixing would
//! rewrite `ACOMP2:A|B[0]` from the prefixed face names (different sort, embedded
//! prefixes) — do not "fix" this by routing members through `register_added`.
//! Two instances of the same part therefore never collide (distinct feature ids),
//! and a nested assembly's already-namespaced members chain naturally:
//! `ACOMP1:Extrude1_top` wrapped by `ACOMP3` becomes `ACOMP3:ACOMP1:Extrude1_top`.
//!
//! # The feature fence (build-spec §3)
//!
//! Solids from ordinary modeling features never belong to a component and behave
//! exactly as before. Component geometry is valid input for constraints and
//! sketch attach/project ONLY; modeling features must cheaply REJECT it —
//! [`SceneMap::is_component_owned`] / [`reject_component_references`] are that
//! predicate (Wave 2 wires the checks into feature resolution).

use std::collections::BTreeMap;

use crate::feature_pipeline::features::common::{collect_edge_names, collect_face_names};
use crate::feature_pipeline::{AddedSolid, FeatureDescriptor, SceneMap};
use crate::{transform_brep, AffineTransform, BrepSolid};

// ===========================================================================
// The component record
// ===========================================================================

/// One scene component: an ACOMP instance's identity, pose, and member solids.
/// Rides the [`crate::feature_pipeline::FeatureResult`] `components` side-channel
/// into [`SceneMap::apply`], exactly like profiles/frames — the scene's component
/// set is rebuilt from feature results every history run (a projected view,
/// never an owning data structure).
#[derive(Debug, Clone)]
pub struct ComponentRecord {
    /// The owning ACOMP feature id — also the namespace prefix segment.
    pub id: String,
    /// The display / parts-library part name (`M4-bolt` in `M4-bolt (ACOMP3)`).
    pub part_name: String,
    /// The rigid instance pose (part-local snapshot space -> assembly space),
    /// already baked into the member geometry. Kept so a pose UPDATE can apply
    /// the delta `new · old⁻¹` and so the solver can read the current pose.
    pub transform: AffineTransform,
    /// Grounded flag (the feature's `isFixed`; the solver never moves it).
    pub fixed: bool,
    /// Opaque source metadata slot (`sourceKey` / `sourceSignature` / …) for the
    /// parts-library + update-components lanes; the scene never interprets it.
    pub source: serde_json::Value,
    /// Member solid scene names, already namespaced (`{id}:{part solid name}`).
    pub solids: Vec<String>,
}

/// The scene's component set, keyed by owning feature id. `BTreeMap` so
/// iteration (structure tree, BOM) is deterministic.
pub type ComponentMap = BTreeMap<String, ComponentRecord>;

// ===========================================================================
// Namespacing
// ===========================================================================

/// Wrap one entity name with a component prefix: `{component_id}:{name}`.
pub fn namespaced(component_id: &str, name: &str) -> String {
    format!("{component_id}:{name}")
}

/// Prefix every NAMED face/edge of a member solid with the component id (the
/// solid's own scene name is prefixed by the caller — solids carry their name in
/// [`AddedSolid`], not on the BREP). Unnamed entities stay unnamed (they are not
/// scene-resolvable either way).
fn namespace_solid_names(solid: &mut BrepSolid, component_id: &str) {
    for shell in &mut solid.shells {
        for face in &mut shell.faces {
            if let Some(name) = &face.name {
                face.name = Some(namespaced(component_id, name));
            }
        }
    }
    for edge in &mut solid.edges {
        if let Some(name) = &edge.name {
            edge.name = Some(namespaced(component_id, name));
        }
    }
}

/// A component id must be a plain feature id: non-empty, no `:` (the namespace
/// delimiter) and no `|` (the topology-vs-authored name discriminator).
fn validate_component_id(id: &str) -> Result<(), String> {
    if id.is_empty() {
        return Err("component id must not be empty".into());
    }
    if id.contains(':') || id.contains('|') {
        return Err(format!("component id '{id}' must not contain ':' or '|'"));
    }
    Ok(())
}

// ===========================================================================
// Rigid-transform helpers (row-major 4x4, the AffineTransform layout)
// ===========================================================================

/// Require a RIGID map (orthonormal rotation rows, determinant +1). Components
/// move as rigid bodies — a scaling/shearing/reflecting instance pose is a
/// modeling error, rejected loudly (no fallback).
fn require_rigid(transform: &AffineTransform) -> Result<(), String> {
    let m = &transform.elements;
    let rows = [[m[0], m[1], m[2]], [m[4], m[5], m[6]], [m[8], m[9], m[10]]];
    for i in 0..3 {
        for j in i..3 {
            let dot: f64 = (0..3).map(|k| rows[i][k] * rows[j][k]).sum();
            let expected = if i == j { 1.0 } else { 0.0 };
            if (dot - expected).abs() > 1e-8 {
                return Err("component transform must be rigid (rotation + translation)".into());
            }
        }
    }
    if (transform.determinant3() - 1.0).abs() > 1e-8 {
        return Err("component transform must be rigid (no reflection/scale)".into());
    }
    Ok(())
}

/// Row-major product `a · b` (apply `b` first, then `a`).
fn compose(a: &AffineTransform, b: &AffineTransform) -> Result<AffineTransform, String> {
    let (ma, mb) = (&a.elements, &b.elements);
    let mut out = [0.0f64; 16];
    for row in 0..4 {
        for col in 0..4 {
            out[row * 4 + col] = (0..4)
                .map(|k| ma[row * 4 + k] * mb[k * 4 + col])
                .sum();
        }
    }
    AffineTransform::new(out)
}

/// Inverse of a RIGID map: `[Rᵀ | −Rᵀ·t]` (caller has verified rigidity).
fn rigid_inverse(transform: &AffineTransform) -> Result<AffineTransform, String> {
    let m = &transform.elements;
    let r = [[m[0], m[1], m[2]], [m[4], m[5], m[6]], [m[8], m[9], m[10]]];
    let t = [m[3], m[7], m[11]];
    let mut out = [0.0f64; 16];
    for row in 0..3 {
        for col in 0..3 {
            out[row * 4 + col] = r[col][row]; // Rᵀ
        }
        out[row * 4 + 3] = -(0..3).map(|k| r[k][row] * t[k]).sum::<f64>();
    }
    out[15] = 1.0;
    AffineTransform::new(out)
}

// ===========================================================================
// Create / re-pose
// ===========================================================================

/// Build a component from a set of PART-LOCAL solids: rigid-pose each member
/// with `transform`, namespace its entity names with `id`, and register it as a
/// scene-resident solid. Returns the component record plus one [`AddedSolid`]
/// per member — the owning ACOMP feature pushes both into its `FeatureResult`
/// (`added` + `components`), and the record's handles are then owned by that
/// feature's history-cache entry like any other feature output.
///
/// `members` are `(solid name, part-local BREP)` pairs exactly as the sub-part's
/// history produced them (deterministic names final; see the module doc — the
/// prefix wraps them, nothing is re-derived). Two-phase: every member is posed
/// BEFORE anything registers, so a failure never leaks a half-built component.
// Contract surface for the Wave-2 ACOMP feature; exercised by this module's tests.
#[allow(dead_code)]
pub fn create_component(
    id: &str,
    part_name: &str,
    fixed: bool,
    source: serde_json::Value,
    transform: AffineTransform,
    members: Vec<(String, BrepSolid)>,
) -> Result<(ComponentRecord, Vec<AddedSolid>), String> {
    validate_component_id(id)?;
    require_rigid(&transform)?;

    // Phase 1 (fallible): pose + namespace every member.
    let mut posed: Vec<(String, BrepSolid)> = Vec::with_capacity(members.len());
    for (member_name, solid) in &members {
        let mut body = transform_brep(solid, transform, false)
            .map_err(|error| format!("component '{id}': member '{member_name}': {error}"))?;
        namespace_solid_names(&mut body, id);
        posed.push((namespaced(id, member_name), body));
    }

    // Phase 2 (infallible): register.
    let mut added = Vec::with_capacity(posed.len());
    let mut solids = Vec::with_capacity(posed.len());
    for (name, body) in posed {
        let face_names = collect_face_names(&body);
        let edge_names = collect_edge_names(&body);
        let handle = crate::register_solid_value(body);
        solids.push(name.clone());
        added.push(AddedSolid {
            handle,
            name,
            face_names,
            edge_names,
            ..AddedSolid::default()
        });
    }

    Ok((
        ComponentRecord {
            id: id.to_string(),
            part_name: part_name.to_string(),
            transform,
            fixed,
            source,
            solids,
        },
        added,
    ))
}

/// Re-pose a component to a NEW absolute rigid transform: applies the delta
/// `new · old⁻¹` to every member solid IN PLACE (same handles — a rigid map
/// keeps every topology id and name, so the scene's face/edge refs stay valid)
/// and updates the record.
///
/// This is the INTERACTIVE lane (move-gizmo drag, solver preview). The
/// AUTHORITATIVE pose lives on the owning ACOMP feature's `inputParams`
/// transform: a commit must write it back there (the solver pose write-back),
/// which dirties the feature's fingerprint so the next history run re-executes
/// it from the snapshot at the committed pose. Without the write-back, a clean
/// cache replay would serve the mutated geometry against a stale descriptor.
///
/// Two-phase: every member transform is computed before anything commits, so a
/// failure never leaves the component half-posed.
// Contract surface for the Wave-2/3 move + solver lanes; exercised by tests.
#[allow(dead_code)]
pub fn update_component_transform(
    scene: &mut SceneMap,
    id: &str,
    new_transform: AffineTransform,
) -> Result<(), String> {
    require_rigid(&new_transform)?;
    let record = scene
        .components
        .get(id)
        .ok_or_else(|| format!("unknown component '{id}'"))?;
    let delta = compose(&new_transform, &rigid_inverse(&record.transform)?)?;

    // Phase 1 (fallible): resolve + re-pose every member.
    let mut posed: Vec<(u32, BrepSolid)> = Vec::with_capacity(record.solids.len());
    for name in &record.solids {
        let handle = scene
            .solids
            .get(name)
            .copied()
            .ok_or_else(|| format!("component '{id}': member '{name}' is not scene-resident"))?;
        let body = crate::with_registered_solid_str(handle, |solid| {
            transform_brep(solid, delta, false)
        })
        .map_err(|error| format!("component '{id}': member '{name}': {error}"))?;
        posed.push((handle, body));
    }

    // Phase 2: commit under the existing handles, then update the record.
    for (handle, body) in posed {
        crate::replace_registered_solid(handle, body)?;
    }
    scene
        .components
        .get_mut(id)
        .expect("record fetched above")
        .transform = new_transform;
    Ok(())
}

/// The feature fence (build-spec §3): fail with a clear message when any of
/// `names` resolves to component-owned geometry. Modeling features that consume
/// solids/faces/edges call this over their reference names before operating —
/// cross-part feature linking is out of scope and must be rejected cleanly,
/// never silently applied.
pub fn reject_component_references<'a>(
    scene: &SceneMap,
    names: impl IntoIterator<Item = &'a str>,
) -> Result<(), String> {
    for name in names {
        if let Some(record) = scene.owning_component(name) {
            return Err(format!(
                "'{name}' belongs to assembly component '{}' — modeling features cannot consume component geometry",
                record.id
            ));
        }
    }
    Ok(())
}

/// The fence at the DISPATCH altitude — the one place every feature passes
/// through (`execute_feature`), so no per-feature checks are scattered. A
/// reference here is what the pipeline already defines it to be (the
/// `scan_consumed` cache-dependency walk): any descriptor string that
/// exact-matches a scene name. Any such string owned by a component fails the
/// feature before it executes.
///
/// Exempt (the two ALLOWED in-context uses, build-spec §3 — attach + project):
/// SKETCH (plane attach + edge projection), DATUM/PLANE (a datum derived from
/// component geometry), and ACOMP itself (the component's own feature, wired by
/// the parts-library lane). Assembly constraints are not history features, so
/// they never reach this fence. The exemption is type-level, which is safe
/// because none of the exempt types carries a `boolean` param or operand-solid
/// references — re-examine if such a param is ever added to one of them.
pub fn enforce_reference_fence(
    feature_type: &str,
    descriptor: &FeatureDescriptor,
    scene: &SceneMap,
) -> Result<(), String> {
    // Componentless scenes skip the walk entirely — the byte-identical
    // guarantee for every existing modeling document.
    if scene.components.is_empty() {
        return Ok(());
    }
    // Verbatim dispatch alias strings (the dispatch matches exact spellings;
    // "ASSEMBLY COMPONENT" is ACOMP's long dispatch alias in assembly_component.rs).
    if matches!(
        feature_type,
        "S" | "SKETCH" | "D" | "DATUM" | "DATIUM" | "P" | "PLANE" | "ACOMP" | "ASSEMBLY COMPONENT"
    ) {
        return Ok(());
    }
    if let Some(name) = first_component_owned(&descriptor.input_params, scene)
        .or_else(|| first_component_owned(&descriptor.persistent_data, scene))
    {
        return reject_component_references(scene, [name]);
    }
    Ok(())
}

/// The first string anywhere in `value` (recursively, both param sources — the
/// `scan_consumed` walk shape) that names component-owned geometry.
fn first_component_owned<'a>(
    value: &'a serde_json::Value,
    scene: &SceneMap,
) -> Option<&'a str> {
    match value {
        serde_json::Value::String(text) => {
            let trimmed = text.trim();
            (!trimmed.is_empty() && scene.is_component_owned(trimmed)).then_some(trimmed)
        }
        serde_json::Value::Array(items) => {
            items.iter().find_map(|item| first_component_owned(item, scene))
        }
        serde_json::Value::Object(map) => {
            map.values().find_map(|item| first_component_owned(item, scene))
        }
        _ => None,
    }
}

// ===========================================================================
// SceneMap component surface
// ===========================================================================

impl SceneMap {
    /// Resolve a component record by its owning feature id (exact match).
    /// Contract surface for the Wave-2 constraint/selection lanes.
    #[allow(dead_code)]
    pub fn resolve_component(&self, id: &str) -> Option<&ComponentRecord> {
        self.components.get(id)
    }

    /// The component owning an entity name, if any: the BARE component id itself
    /// (a COMPONENT-type selection), or the name's OUTERMOST namespace prefix
    /// (`ACOMP3:ACOMP1:X` is owned by `ACOMP3` at this scene level; `ACOMP1` is
    /// the nested assembly's internal structure). Membership is decided against
    /// the registered component set, never syntactically — authored names like
    /// `S1:PROFILE` have a first segment that is a sketch id, not a component id.
    pub fn owning_component(&self, name: &str) -> Option<&ComponentRecord> {
        if let Some(record) = self.components.get(name) {
            return Some(record);
        }
        let (prefix, _) = name.split_once(':')?;
        self.components.get(prefix)
    }

    /// The feature-fence predicate: does this entity name belong to a component?
    /// Cheap (one map probe + one prefix probe); the dispatch fence
    /// ([`enforce_reference_fence`]) uses it to REJECT component geometry as
    /// modeling-feature input (build-spec §3).
    pub fn is_component_owned(&self, name: &str) -> bool {
        self.owning_component(name).is_some()
    }

    /// Iterate the scene's components in deterministic (id) order — the
    /// structure-tree / BOM projection surface.
    #[allow(dead_code)]
    pub fn iter_components(&self) -> impl Iterator<Item = &ComponentRecord> {
        self.components.values()
    }

    /// A component's member solids as `(scene name, resident handle)`, in the
    /// record's member order. A member missing from the solid map (never the
    /// case for an intact scene) is skipped.
    #[allow(dead_code)]
    pub fn component_solids(&self, id: &str) -> Vec<(String, u32)> {
        let Some(record) = self.components.get(id) else {
            return Vec::new();
        };
        record
            .solids
            .iter()
            .filter_map(|name| self.solids.get(name).map(|&handle| (name.clone(), handle)))
            .collect()
    }

    /// A component's grounded flag (`None` for an unknown id).
    #[allow(dead_code)]
    pub fn component_fixed(&self, id: &str) -> Option<bool> {
        self.components.get(id).map(|record| record.fixed)
    }

    /// Set a component's grounded flag. Scene-view state only — the
    /// authoritative flag is the owning feature's `isFixed` (the Fixed
    /// constraint / tree action writes THERE; this keeps the live scene in
    /// sync between runs). Returns false for an unknown id.
    #[allow(dead_code)]
    pub fn set_component_fixed(&mut self, id: &str, fixed: bool) -> bool {
        match self.components.get_mut(id) {
            Some(record) => {
                record.fixed = fixed;
                true
            }
            None => false,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::feature_pipeline::{
        clear_history_cache, execute_history, FeatureResult, HistoryRequest,
    };

    fn run(request: serde_json::Value) -> crate::feature_pipeline::HistoryResult {
        let request: HistoryRequest =
            serde_json::from_value(request).expect("request deserializes");
        clear_history_cache();
        execute_history(&request)
    }

    fn cube_descriptor(id: &str, sx: f64, sy: f64, sz: f64) -> serde_json::Value {
        serde_json::json!({
            "type": "P.CU",
            "inputParams": { "id": id, "sizeX": sx, "sizeY": sy, "sizeZ": sz },
            "persistentData": {}
        })
    }

    /// A PART-LOCAL source solid with REAL deterministic names: run a one-cube
    /// history (so `register_added` stamped unique faces + derived edges), clone
    /// the resident solid out, then clear the cache (frees its handle).
    fn source_part(id: &str) -> BrepSolid {
        let history = run(serde_json::json!({
            "features": [ cube_descriptor(id, 2.0, 3.0, 4.0) ]
        }));
        let handle = history.results[0].added[0].handle;
        let solid = crate::with_registered_solid_str(handle, |solid| Ok(solid.clone()))
            .expect("resident source solid");
        clear_history_cache();
        solid
    }

    fn identity() -> AffineTransform {
        AffineTransform::new([
            1.0, 0.0, 0.0, 0.0, //
            0.0, 1.0, 0.0, 0.0, //
            0.0, 0.0, 1.0, 0.0, //
            0.0, 0.0, 0.0, 1.0,
        ])
        .unwrap()
    }

    fn translation(x: f64, y: f64, z: f64) -> AffineTransform {
        AffineTransform::new([
            1.0, 0.0, 0.0, x, //
            0.0, 1.0, 0.0, y, //
            0.0, 0.0, 1.0, z, //
            0.0, 0.0, 0.0, 1.0,
        ])
        .unwrap()
    }

    /// Every scene name of an added-solid list: solid + face + edge names.
    fn all_names(added: &[AddedSolid]) -> Vec<String> {
        let mut names = Vec::new();
        for solid in added {
            names.push(solid.name.clone());
            names.extend(solid.face_names.iter().map(|(_, name)| name.clone()));
            names.extend(solid.edge_names.iter().map(|(_, name)| name.clone()));
        }
        names
    }

    /// Apply a component into a scene the way an ACOMP feature result would.
    fn apply_component(scene: &mut SceneMap, record: ComponentRecord, added: Vec<AddedSolid>) {
        let mut result = FeatureResult::empty(record.id.clone(), "ACOMP");
        result.added = added;
        result.components = vec![record];
        scene.apply(&result);
    }

    fn free_added(added: &[AddedSolid]) {
        for solid in added {
            crate::free_registered_solid(solid.handle);
        }
    }

    /// The vertex AABB of a resident solid.
    fn bbox(handle: u32) -> ([f64; 3], [f64; 3]) {
        crate::with_registered_solid_str(handle, |solid| {
            let mut lo = [f64::INFINITY; 3];
            let mut hi = [f64::NEG_INFINITY; 3];
            for vertex in &solid.vertices {
                let p = [vertex.point.x, vertex.point.y, vertex.point.z];
                for k in 0..3 {
                    lo[k] = lo[k].min(p[k]);
                    hi[k] = hi[k].max(p[k]);
                }
            }
            Ok((lo, hi))
        })
        .expect("resident solid bbox")
    }

    // Two components from the SAME source part: zero name collisions, prefixes
    // wrap the unchanged part-local names, and a rebuild with identical inputs
    // reproduces byte-identical name sets.
    #[test]
    fn two_instances_of_one_part_never_collide_and_names_are_stable() {
        let start = crate::registered_solid_count();
        let part = source_part("Part");

        let (record1, added1) = create_component(
            "ACOMP1",
            "bracket",
            true,
            serde_json::json!({ "sourceKey": "bracket" }),
            identity(),
            vec![("Part".into(), part.clone())],
        )
        .expect("component 1");
        let (record2, added2) = create_component(
            "ACOMP2",
            "bracket",
            false,
            serde_json::json!({ "sourceKey": "bracket" }),
            translation(10.0, 0.0, 0.0),
            vec![("Part".into(), part.clone())],
        )
        .expect("component 2");

        // The prefix wraps the part-local names, nothing else moves.
        assert_eq!(added1[0].name, "ACOMP1:Part");
        assert_eq!(added2[0].name, "ACOMP2:Part");
        let faces1: Vec<&str> = added1[0].face_names.iter().map(|(_, n)| n.as_str()).collect();
        assert_eq!(
            faces1,
            vec![
                "ACOMP1:Part_NZ", "ACOMP1:Part_PZ", "ACOMP1:Part_NY",
                "ACOMP1:Part_PY", "ACOMP1:Part_NX", "ACOMP1:Part_PX",
            ],
        );
        // Derived edge names keep their part-local `{A}|{B}[n]` form under ONE
        // prefix (embedded face names untouched — the spec's example shape).
        assert!(
            added1[0]
                .edge_names
                .iter()
                .all(|(_, name)| name.starts_with("ACOMP1:") && name.contains('|')),
            "edge names: {:?}",
            added1[0].edge_names
        );
        assert_eq!(added1[0].edge_names.len(), 12, "cube edge count");

        // Zero collisions across the two instances.
        let names1 = all_names(&added1);
        let names2 = all_names(&added2);
        assert!(
            names1.iter().all(|name| !names2.contains(name)),
            "instances must not share any name"
        );

        // Stability: an identical rebuild reproduces the exact same names.
        let (record1b, added1b) = create_component(
            "ACOMP1",
            "bracket",
            true,
            serde_json::json!({ "sourceKey": "bracket" }),
            identity(),
            vec![("Part".into(), part.clone())],
        )
        .expect("component 1 rebuild");
        assert_eq!(all_names(&added1b), names1, "names stable across rebuilds");
        assert_eq!(record1b.solids, record1.solids);

        assert_eq!(record1.id, "ACOMP1");
        assert_eq!(record1.part_name, "bracket");
        assert!(record1.fixed);
        assert!(!record2.fixed);

        free_added(&added1);
        free_added(&added2);
        free_added(&added1b);
        assert_eq!(crate::registered_solid_count(), start, "no handle leak");
    }

    // Scene ingestion + the whole lookup surface: owning-component parse, the
    // fence predicate, member iteration, fixed access, and component removal.
    #[test]
    fn scene_ingestion_owning_lookup_fence_and_removal() {
        let start = crate::registered_solid_count();
        let part = source_part("Part");
        let (record1, added1) = create_component(
            "ACOMP1", "bracket", false, serde_json::Value::Null,
            identity(), vec![("Part".into(), part.clone())],
        )
        .expect("component 1");
        let (record2, added2) = create_component(
            "ACOMP2", "bracket", true, serde_json::Value::Null,
            translation(10.0, 0.0, 0.0), vec![("Part".into(), part.clone())],
        )
        .expect("component 2");
        let handle1 = added1[0].handle;
        let handle2 = added2[0].handle;

        let mut scene = SceneMap::default();
        apply_component(&mut scene, record1, added1);
        apply_component(&mut scene, record2, added2);

        // Members resolve like ordinary scene solids/faces.
        assert_eq!(scene.resolve_solid("ACOMP1:Part"), Some(handle1));
        assert!(scene.resolve_face("ACOMP2:Part_PZ").is_some());

        // Owning-component lookup: bare id, solid, face, and edge names.
        assert_eq!(scene.owning_component("ACOMP1").unwrap().id, "ACOMP1");
        assert_eq!(scene.owning_component("ACOMP1:Part").unwrap().id, "ACOMP1");
        assert_eq!(scene.owning_component("ACOMP2:Part_PZ").unwrap().id, "ACOMP2");
        let edge_name = scene
            .resolve_solid("ACOMP1:Part")
            .and_then(|_| {
                scene.edges.keys().find(|name| name.starts_with("ACOMP1:")).cloned()
            })
            .expect("a namespaced edge");
        assert_eq!(scene.owning_component(&edge_name).unwrap().id, "ACOMP1");

        // The fence predicate: component-owned vs plain names.
        assert!(scene.is_component_owned("ACOMP1"));
        assert!(scene.is_component_owned("ACOMP2:Part_NX"));
        assert!(!scene.is_component_owned("Part_NX"));
        assert!(!scene.is_component_owned("S1:PROFILE"));
        assert!(reject_component_references(&scene, ["Part_NX"]).is_ok());
        let rejected = reject_component_references(&scene, ["Part_NX", "ACOMP2:Part_NX"]);
        assert!(
            rejected.as_ref().is_err_and(|error| error.contains("ACOMP2")),
            "fence must name the owning component: {rejected:?}"
        );

        // Deterministic iteration + member handles + fixed access.
        let ids: Vec<&str> = scene.iter_components().map(|r| r.id.as_str()).collect();
        assert_eq!(ids, vec!["ACOMP1", "ACOMP2"]);
        assert_eq!(
            scene.component_solids("ACOMP1"),
            vec![("ACOMP1:Part".to_string(), handle1)]
        );
        assert_eq!(scene.component_fixed("ACOMP1"), Some(false));
        assert_eq!(scene.component_fixed("ACOMP2"), Some(true));
        assert!(scene.set_component_fixed("ACOMP1", true));
        assert_eq!(scene.component_fixed("ACOMP1"), Some(true));
        assert!(!scene.set_component_fixed("ghost", true));

        // Removing a component id (a replace/delete result) unmaps the record
        // AND its members; the other component is untouched.
        let mut removal = FeatureResult::empty("ACOMP1", "ACOMP");
        removal.removed = vec!["ACOMP1".to_string()];
        scene.apply(&removal);
        assert!(scene.resolve_component("ACOMP1").is_none());
        assert!(scene.resolve_solid("ACOMP1:Part").is_none());
        assert!(scene.resolve_face("ACOMP1:Part_PZ").is_none());
        assert!(!scene.is_component_owned("ACOMP1:Part"));
        assert_eq!(scene.resolve_solid("ACOMP2:Part"), Some(handle2));

        crate::free_registered_solid(handle1);
        crate::free_registered_solid(handle2);
        assert_eq!(crate::registered_solid_count(), start, "no handle leak");
    }

    // A transform update re-poses member GEOMETRY in place (same handle, moved
    // vertices) and is ABSOLUTE: successive updates never accumulate.
    #[test]
    fn transform_update_reposes_member_geometry_absolutely() {
        let start = crate::registered_solid_count();
        let part = source_part("Part"); // spans 0..2, 0..3, 0..4
        let (record, added) = create_component(
            "ACOMP1", "bracket", false, serde_json::Value::Null,
            identity(), vec![("Part".into(), part)],
        )
        .expect("component");
        let handle = added[0].handle;
        let pz_face = added[0]
            .face_names
            .iter()
            .find(|(_, name)| name == "ACOMP1:Part_PZ")
            .map(|(id, _)| *id)
            .expect("_PZ face");

        let mut scene = SceneMap::default();
        apply_component(&mut scene, record, added);

        update_component_transform(&mut scene, "ACOMP1", translation(5.0, 0.0, 0.0))
            .expect("re-pose");
        let (lo, hi) = bbox(handle);
        assert!((lo[0] - 5.0).abs() < 1e-9 && (hi[0] - 7.0).abs() < 1e-9, "x {lo:?}..{hi:?}");

        // Absolute pose semantics: a second update REPLACES, never accumulates.
        update_component_transform(&mut scene, "ACOMP1", translation(2.0, 0.0, 1.0))
            .expect("second re-pose");
        let (lo, hi) = bbox(handle);
        assert!((lo[0] - 2.0).abs() < 1e-9 && (hi[0] - 4.0).abs() < 1e-9, "x {lo:?}..{hi:?}");
        assert!((lo[2] - 1.0).abs() < 1e-9 && (hi[2] - 5.0).abs() < 1e-9, "z {lo:?}..{hi:?}");

        // Same handle, same names: the scene's face ref still resolves and the
        // record carries the committed pose.
        let face = scene.resolve_face("ACOMP1:Part_PZ").expect("face still mapped");
        assert_eq!(face.handle, handle);
        assert_eq!(face.face_id, pz_face);
        let posed = scene.resolve_component("ACOMP1").unwrap().transform.elements;
        assert_eq!([posed[3], posed[7], posed[11]], [2.0, 0.0, 1.0]);

        // Unknown component / non-rigid transform are loud errors.
        assert!(update_component_transform(&mut scene, "ghost", identity()).is_err());
        let scaled = AffineTransform::new([
            2.0, 0.0, 0.0, 0.0, //
            0.0, 2.0, 0.0, 0.0, //
            0.0, 0.0, 2.0, 0.0, //
            0.0, 0.0, 0.0, 1.0,
        ])
        .unwrap();
        assert!(update_component_transform(&mut scene, "ACOMP1", scaled).is_err());

        crate::free_registered_solid(handle);
        assert_eq!(crate::registered_solid_count(), start, "no handle leak");
    }

    // Nested assemblies chain prefixes: wrapping an already-namespaced member
    // yields `ACOMP3:ACOMP1:...`, owned by the OUTER component at this level.
    #[test]
    fn nested_component_prefixes_chain() {
        let start = crate::registered_solid_count();
        let part = source_part("Part");
        // The inner assembly's instance (as its own document built it).
        let (_, inner_added) = create_component(
            "ACOMP1", "bracket", false, serde_json::Value::Null,
            translation(1.0, 0.0, 0.0), vec![("Part".into(), part)],
        )
        .expect("inner component");
        let inner_solid =
            crate::with_registered_solid_str(inner_added[0].handle, |solid| Ok(solid.clone()))
                .expect("inner resident");
        let inner_name = inner_added[0].name.clone();
        free_added(&inner_added);

        // Inserting that assembly into a parent wraps ONE more prefix.
        let (record, added) = create_component(
            "ACOMP3", "sub-assembly", false, serde_json::Value::Null,
            identity(), vec![(inner_name, inner_solid)],
        )
        .expect("outer component");
        assert_eq!(added[0].name, "ACOMP3:ACOMP1:Part");
        assert!(added[0]
            .face_names
            .iter()
            .any(|(_, name)| name == "ACOMP3:ACOMP1:Part_PZ"));

        // At the parent scene level the owner is the OUTERMOST component.
        let mut scene = SceneMap::default();
        let handle = added[0].handle;
        apply_component(&mut scene, record, added);
        assert_eq!(
            scene.owning_component("ACOMP3:ACOMP1:Part_PZ").unwrap().id,
            "ACOMP3"
        );
        assert!(scene.resolve_component("ACOMP1").is_none(), "inner id is not a scene component");

        crate::free_registered_solid(handle);
        assert_eq!(crate::registered_solid_count(), start, "no handle leak");
    }

    // Invalid inputs are loud errors, and nothing leaks on the error path.
    #[test]
    fn create_component_rejects_bad_ids_and_non_rigid_transforms() {
        let start = crate::registered_solid_count();
        let part = source_part("Part");
        for bad_id in ["", "A:B", "A|B"] {
            assert!(
                create_component(
                    bad_id, "x", false, serde_json::Value::Null,
                    identity(), vec![("Part".into(), part.clone())],
                )
                .is_err(),
                "id '{bad_id}' must be rejected"
            );
        }
        let scaled = AffineTransform::new([
            1.0, 0.0, 0.0, 0.0, //
            0.0, 3.0, 0.0, 0.0, //
            0.0, 0.0, 1.0, 0.0, //
            0.0, 0.0, 0.0, 1.0,
        ])
        .unwrap();
        assert!(
            create_component(
                "ACOMP1", "x", false, serde_json::Value::Null,
                scaled, vec![("Part".into(), part)],
            )
            .is_err(),
            "non-rigid transform must be rejected"
        );
        assert_eq!(crate::registered_solid_count(), start, "error paths leak nothing");
    }

    // The componentless path is BYTE-IDENTICAL to today: a plain modeling
    // fixture (cube + subtract, exercising derived `{A}|{B}[n]` edge names)
    // produces exactly the established names, none of them component-owned.
    #[test]
    fn componentless_scenes_keep_todays_names() {
        let start = crate::registered_solid_count();
        // Fixture 1: a lone cube — the full pinned name set.
        let history = run(serde_json::json!({
            "features": [ cube_descriptor("cube1", 2.0, 3.0, 4.0) ]
        }));
        let added = &history.results[0].added[0];
        let mut scene = SceneMap::default();
        for result in &history.results {
            scene.apply(result);
        }
        assert!(scene.components.is_empty(), "no components in a modeling scene");
        let faces: Vec<&str> = added.face_names.iter().map(|(_, n)| n.as_str()).collect();
        assert_eq!(
            faces,
            vec!["cube1_NZ", "cube1_PZ", "cube1_NY", "cube1_PY", "cube1_NX", "cube1_PX"],
        );
        let edges: Vec<&str> = added.edge_names.iter().map(|(_, n)| n.as_str()).collect();
        assert_eq!(
            edges,
            vec![
                "cube1_NX|cube1_NZ[0]", "cube1_NZ|cube1_PY[0]", "cube1_NZ|cube1_PX[0]",
                "cube1_NY|cube1_NZ[0]", "cube1_NY|cube1_PZ[0]", "cube1_PX|cube1_PZ[0]",
                "cube1_PY|cube1_PZ[0]", "cube1_NX|cube1_PZ[0]", "cube1_NY|cube1_PX[0]",
                "cube1_NX|cube1_NY[0]", "cube1_NX|cube1_PY[0]", "cube1_PX|cube1_PY[0]",
            ],
        );
        for name in all_names(std::slice::from_ref(added)) {
            assert!(!scene.is_component_owned(&name), "'{name}' must be componentless");
        }

        // Fixture 2: cube-subtract-cube (boolean-propagated + derived names).
        let mut tool = cube_descriptor("B", 4.0, 4.0, 4.0);
        tool["inputParams"]["boolean"] = serde_json::json!({
            "operation": "SUBTRACT", "targets": ["A"], "mergeCoplanarFaces": true });
        let history = run(serde_json::json!({
            "features": [ cube_descriptor("A", 10.0, 10.0, 10.0), tool ]
        }));
        let cut = &history.results[1].added[0];
        assert_eq!(cut.name, "A");
        let mut cut_names = all_names(std::slice::from_ref(cut));
        cut_names.sort();
        assert_eq!(
            cut_names,
            vec![
                "A", "A_NX", "A_NX|A_NY[0]", "A_NX|A_NZ[0]", "A_NX|A_PY[0]", "A_NX|A_PZ[0]",
                "A_NX|B_PY[0]", "A_NX|B_PZ[0]", "A_NY", "A_NY|A_NZ[0]", "A_NY|A_PX[0]",
                "A_NY|A_PZ[0]", "A_NY|B_PX[0]", "A_NY|B_PZ[0]", "A_NZ", "A_NZ|A_PX[0]",
                "A_NZ|A_PY[0]", "A_NZ|B_PX[0]", "A_NZ|B_PY[0]", "A_PX", "A_PX|A_PY[0]",
                "A_PX|A_PZ[0]", "A_PY", "A_PY|A_PZ[0]", "A_PZ", "B_PX", "B_PX|B_PY[0]",
                "B_PX|B_PZ[0]", "B_PY", "B_PY|B_PZ[0]", "B_PZ",
            ],
        );

        let mut scene = SceneMap::default();
        for result in &history.results {
            scene.apply(result);
        }
        for name in all_names(std::slice::from_ref(cut)) {
            assert!(!scene.is_component_owned(&name), "'{name}' must be componentless");
        }
        clear_history_cache();
        assert_eq!(crate::registered_solid_count(), start, "no handle leak");
    }
}