brep_kernel/feature_pipeline/features/

import3d.rs

//! IMPORT3D — Import 3D Model (STEP). Ported from the retired `Import3dModelFeature`.
//!
//! Three headless sources, tried in order:
//! 0. **`inputParams.nativeBrep`** — a native [`crate::snapshot_solids`] payload
//!    (`io/snapshot.rs`): the exact solids of an earlier import, already carrying
//!    their final IMPORT3D names. Tried FIRST and EXCLUSIVE — a feature carrying
//!    it must not also carry `stepText`/`igesText` (an error, not a precedence
//!    puzzle). The solids register VERBATIM under their stored names: re-deriving
//!    them would break every scene-metadata record and every constraint keyed to a
//!    face name. This is the lane a STEP-assembly part document rides on (see
//!    `docs/developer/kernel-plans/step-assembly-import.md` §3.2), and the reason
//!    the snapshot container is a DURABLE format, not a cache (§6 there, and the
//!    `io/snapshot.rs` module doc).
//! 1. **`inputParams.stepText`** — the raw ISO-10303-21 document, baked in by the
//!    toolbar Import lane ([`crate`]'s host: `EngineState::import_step_feature`).
//!    Runs the exact Rust STEP importer
//!    ([`crate::import_step_with_appearance`] — the colour-carrying form).
//! 2. **`persistentData.importCache`** (`kind == "step-brep"`) — SUPERSEDED by
//!    `nativeBrep`. The JS-era persisted EXACT BREP records of a previous import
//!    (`serializeBrepSolid` was the serde `BrepSolid` JSON, so records deserialize
//!    directly) — verbose and unversioned. NOTHING in the Rust tree writes it; the
//!    reader stays only so a JS-era saved model still opens. New payloads go in
//!    `nativeBrep`.
//!
//! Name fidelity (contract rule 2, byte-matching `Import3dModelFeature`):
//! - Body names (`importedSolidNames`): a single body keeps the feature name;
//!   several get `{feature}_SOLID_{N}` with N 1-based, zero-padded to
//!   `max(2, digits(count))`.
//! - Faces (`importedBodyFaceNames` / the single-body fallback): a MULTI-body
//!   import names EVERY face `{bodyName}_Face_{f}` positionally (shell/face
//!   order) so faces stay unique across bodies; a SINGLE body prepends the
//!   (unique) feature name — `{feature}_{stepName}`, or `{feature}_Face_{f}` where
//!   the STEP file left the face unnamed — so two separate imports never share a
//!   face name (the cross-solid name-uniqueness guard's collision class). Edge
//!   names re-derive from the face names, so the derived edges are namespaced too.
//!
//! COLOUR rides the same names. What a STEP file's presentation entities assign
//! (`io/step_import/styles.rs`) is stamped here as a `{"color": "#RRGGBB"}`
//! scene-metadata record on the FINAL body/face names — see `io/appearance.rs`
//! for the convention, [`stamp_appearance`] for the write, and
//! [`native_import_payload_with_appearance`] for the lane that seals it into a
//! part payload. The stamp is a NON-overwriting merge, so a colour edited in the
//! caller's info panel survives a history replay.
//!
//! ONE convention, ONE implementation: [`stamp_imported_names`] holds it, and
//! every lane that names imported bodies goes through it — the live import lanes
//! (via [`add_named_bodies`]) and the payload encoder [`native_import_payload`].
//! Names are stamped ONCE, at import, and then frozen in the payload; a later
//! change here does NOT retro-rename already-imported parts, which is the point
//! (a constraint keyed to a face name survives reload).
//!
//! The failed-import base64 retry lane (`persistentData.failedImportFile`) is
//! not yet migrated — it errors loudly rather than silently skipping.

use crate::feature_pipeline::features::common;
use crate::feature_pipeline::{scene_metadata, AddedSolid, FeatureContext, FeatureResult};
use crate::{
    import_iges, import_step_with_appearance, restore_solids, BodyAppearance, BrepSolid,
    ImportedColor, COLOR_METADATA_KEY,
};

pub fn execute(ctx: &FeatureContext) -> FeatureResult {
    match build(ctx) {
        Ok(result) => result,
        Err(error) => ctx.fail(error),
    }
}

fn build(ctx: &FeatureContext) -> Result<FeatureResult, String> {
    let feature_name = if ctx.id.is_empty() {
        "IMPORT3D".to_string()
    } else {
        ctx.id.clone()
    };

    // 0. Native payload — the exact solids of an earlier import, names frozen in.
    //    EXCLUSIVE by design (see the module doc): a document carrying both this
    //    and a text source is malformed, and answering it with a precedence rule
    //    would silently drop one of the two. Keyed on PRESENCE, not on a
    //    successful `as_str`, so a non-string `nativeBrep` errors here instead of
    //    falling through to a different source.
    if let Some(native) = ctx.param("nativeBrep").filter(|value| !value.is_null()) {
        if ctx.param("stepText").is_some() || ctx.param("igesText").is_some() {
            return Err(
                "import3d: `nativeBrep` is exclusive — a feature carrying it must not also carry `stepText`/`igesText`"
                    .into(),
            );
        }
        let payload = native
            .as_str()
            .ok_or("import3d: param `nativeBrep` must be a base64 snapshot string")?;
        return restore_native_bodies(ctx, payload);
    }

    // 1. Fresh STEP text (baked into `stepText` by the toolbar Import lane).
    if let Some(step_text) = ctx.param("stepText").and_then(|v| v.as_str()) {
        if step_text.contains("ISO-10303-21") {
            let (solids, appearances) = import_step_with_appearance(step_text)
                .map_err(|error| format!("import3d: STEP import failed: {error}"))?;
            if solids.is_empty() {
                return Err("import3d: STEP file contained no importable solids".into());
            }
            return Ok(add_named_bodies(ctx, solids, &appearances, &feature_name));
        }
        return Err(
            "import3d: only STEP (ISO-10303-21) files are supported (STL/3MF mesh import was removed)"
                .into(),
        );
    }

    // 1b. Fresh IGES text (baked into `igesText` by the toolbar Import lane).
    if let Some(iges_text) = ctx.param("igesText").and_then(|v| v.as_str()) {
        let solids = import_iges(iges_text)
            .map_err(|error| format!("import3d: IGES import failed: {error}"))?;
        if solids.is_empty() {
            return Err("import3d: IGES file contained no importable solids".into());
        }
        return Ok(add_named_bodies(ctx, solids, &[], &feature_name));
    }

    // 2. Persisted exact-BREP records from a previous import.
    let cache = ctx.persistent.get("importCache");
    if let Some(cache) = cache {
        let kind = cache.get("kind").and_then(|v| v.as_str()).unwrap_or("");
        if kind == "step-brep" {
            let records = cache
                .get("kernelSolidRecords")
                .and_then(|v| v.as_array())
                .ok_or("import3d: importCache has no kernelSolidRecords")?;
            let mut solids = Vec::with_capacity(records.len());
            for (index, record) in records.iter().enumerate() {
                let solid: BrepSolid = serde_json::from_value(record.clone()).map_err(|error| {
                    format!("import3d: kernel record {index} failed to deserialize: {error}")
                })?;
                solids.push(solid);
            }
            if solids.is_empty() {
                return Err("import3d: importCache is empty".into());
            }
            return Ok(add_named_bodies(ctx, solids, &[], &feature_name));
        }
        return Err(format!(
            "import3d: unsupported importCache kind '{kind}' (only 'step-brep')"
        ));
    }

    // A failed-import retry payload without a cache is a not-yet-migrated lane.
    if ctx.persistent.get("failedImportFile").is_some() {
        return Err(
            "import3d: the failed-import base64 retry lane is not yet migrated to the Rust pipeline"
                .into(),
        );
    }

    Err(
        "import3d: no model data (no `nativeBrep`/`stepText` param and no `importCache`)".into(),
    )
}

/// Restore a native payload and register its solids VERBATIM — the `nativeBrep`
/// lane. Nothing about the names is re-derived: they were stamped once, when the
/// geometry was first imported, and every scene-metadata record and every
/// constraint attached to a face is keyed to exactly those strings. (This is
/// `component::create_component`'s phase 2 for the same reason — see its module
/// doc: "do not `fix` this by routing members through `register_added`".)
///
/// The payload's captured metadata records are merged back into the scene store
/// UN-namespaced, exactly as they were captured: an IMPORT3D feature is not a
/// component boundary, so there is no instance prefix to apply. The ACOMP lane
/// namespaces on insert if this document is later used as a part.
fn restore_native_bodies(ctx: &FeatureContext, payload: &str) -> Result<FeatureResult, String> {
    let restored = restore_solids(payload)
        .map_err(|error| format!("import3d: native payload did not decode: {error}"))?;
    if restored.solids.is_empty() {
        return Err("import3d: native payload contained no solids".into());
    }
    let mut result = FeatureResult::empty(ctx.id.clone(), ctx.feature_type.clone());
    for solid in restored.solids {
        result.added.push(register_verbatim(solid.solid, &solid.name));
    }
    // Overwriting: the payload's records ARE the part's metadata. The pipeline's
    // own `sourceFeatureId` seed runs after this feature returns and is
    // NON-overwriting, so a face keeps the producing-feature id it was imported
    // with rather than picking up this feature's.
    for (name, record) in restored.metadata {
        scene_metadata::merge_record(&name, &record, true);
    }
    Ok(result)
}

/// [`common::register_added`] WITHOUT its two name-deriving passes: collect the
/// names the solid already carries and make it scene-resident.
///
/// The container groups are EMPTY, and that is the right answer rather than a
/// stub: a group is the un-keyed alias a PROFILE-SWEPT feature publishes for its
/// per-loop face families (`{cap_base}_START` standing for every
/// `{cap_base}:L{id}_START` — see [`common::register_added_grouped`]). Imported
/// geometry has no sketch loops behind it, so there is no family to alias; its
/// names arrived stamped from outside and are already the final, unique ones.
fn register_verbatim(solid: BrepSolid, name: &str) -> AddedSolid {
    let face_names = common::collect_face_names(&solid);
    let edge_names = common::collect_edge_names(&solid);
    let handle = crate::register_solid_value(solid);
    AddedSolid {
        handle,
        name: name.to_string(),
        face_names,
        edge_names,
        face_groups: Vec::new(),
        edge_groups: Vec::new(),
    }
}

/// Stamp the established naming convention onto the imported bodies, register
/// them, and stamp whatever COLOUR the file carried onto those same names.
///
/// `appearances` is parallel to `solids` (see [`crate::BodyAppearance`]); pass
/// `&[]` from a lane whose format has no colour, which stamps nothing.
fn add_named_bodies(
    ctx: &FeatureContext,
    mut solids: Vec<BrepSolid>,
    appearances: &[BodyAppearance],
    feature_name: &str,
) -> FeatureResult {
    let body_names = stamp_imported_names(&mut solids, feature_name);
    let mut result = FeatureResult::empty(ctx.id.clone(), ctx.feature_type.clone());
    for (index, (solid, body_name)) in solids.into_iter().zip(body_names).enumerate() {
        // Colour is stamped AFTER `register_added`, which is where the names
        // become final (it dedupes face names before deriving the edge names).
        let added = common::register_added(solid, &body_name);
        if let Some(appearance) = appearances.get(index) {
            stamp_appearance(&added.name, &added.face_names, appearance);
        }
        result.added.push(added);
    }
    result
}

/// Write an imported body's colours into the scene-metadata store, keyed by the
/// FINAL names — the one place the `{"color": "#RRGGBB"}` convention of
/// `io/appearance.rs` is written.
///
/// `face_names` is `(face_id, name)` in shell/face order
/// ([`common::collect_face_names`]), the same order `appearance.faces` is
/// indexed by. A length disagreement means the two walks have drifted, so
/// nothing per-face is stamped rather than colouring the wrong faces — the body
/// colour, which is not positional, still lands.
///
/// Merged NON-overwriting: a history replay re-runs this feature, and a colour
/// the user has since edited in the info panel must survive it.
fn stamp_appearance(body_name: &str, face_names: &[(u64, String)], appearance: &BodyAppearance) {
    if let Some(color) = appearance.body {
        stamp_color(body_name, color);
    }
    if appearance.faces.is_empty() || appearance.faces.len() != face_names.len() {
        return;
    }
    for ((_, face_name), color) in face_names.iter().zip(&appearance.faces) {
        if let Some(color) = color {
            stamp_color(face_name, *color);
        }
    }
}

fn stamp_color(name: &str, color: ImportedColor) {
    let mut record = serde_json::Map::new();
    record.insert(
        COLOR_METADATA_KEY.to_string(),
        serde_json::Value::String(color.to_hex()),
    );
    scene_metadata::merge_record(name, &record, false);
}

/// The naming half of [`add_named_bodies`]: stamp body + face names onto
/// `solids` IN PLACE and return the body name chosen for each, WITHOUT
/// registering anything. Shared by the live import lanes and the payload encoder
/// [`native_import_payload`], so an imported part is named identically however it
/// arrived (kernel-plan `step-assembly-import.md` §3.1).
fn stamp_imported_names(solids: &mut [BrepSolid], feature_name: &str) -> Vec<String> {
    let body_names = imported_solid_names(solids.len(), feature_name);
    let multi_body = solids.len() > 1;
    let mut chosen = Vec::with_capacity(solids.len());
    for (index, solid) in solids.iter_mut().enumerate() {
        let body_name = body_names
            .get(index)
            .cloned()
            .unwrap_or_else(|| feature_name.to_string());
        let mut face_index = 0usize;
        for shell in &mut solid.shells {
            for face in &mut shell.faces {
                if multi_body {
                    // Multi-body: EVERY face namespaced under its body.
                    face.name = Some(format!("{body_name}_Face_{face_index}"));
                } else {
                    // Single body: prepend the (unique) feature name so faces never
                    // collide with ANOTHER import's faces — two single-body imports
                    // both stamped bare `Face_N` before, which the cross-solid
                    // name-uniqueness guard flags. Keep any STEP-authored name as the
                    // stem, else the positional `Face_N` fallback. (`body_name` IS the
                    // feature name here — see `imported_solid_names`.) Edge names are
                    // re-derived from these face names downstream, so namespacing the
                    // faces namespaces the derived edges too.
                    let stem = face
                        .name
                        .as_deref()
                        .map(str::trim)
                        .filter(|name| !name.is_empty())
                        .map(str::to_string)
                        .unwrap_or_else(|| format!("Face_{face_index}"));
                    face.name = Some(format!("{body_name}_{stem}"));
                }
                face_index += 1;
            }
        }
        chosen.push(body_name);
    }
    chosen
}

/// `importedSolidNames` port: 1 body keeps the feature name; several get a
/// stable, zero-padded `{feature}_SOLID_0N` suffix.
fn imported_solid_names(count: usize, feature_name: &str) -> Vec<String> {
    if count == 0 {
        return Vec::new();
    }
    if count == 1 {
        return vec![feature_name.to_string()];
    }
    let digits = count.to_string().len().max(2);
    (1..=count)
        .map(|index| format!("{feature_name}_SOLID_{index:0width$}", width = digits))
        .collect()
}

/// Encode `solids` as a native IMPORT3D payload: stamp the names this feature
/// would stamp under `feature_name`, then seal them into the `io/snapshot`
/// container. The result is exactly what the `nativeBrep` source above reads
/// back, so a part is named identically however it arrived — imported live from
/// a text source, or restored from a payload built here.
///
/// GENERIC, not STEP-specific: any producer of finished `BrepSolid`s that wants
/// them to become an IMPORT3D part document uses this (the STEP-assembly import
/// lane is the first caller — kernel-plan `step-assembly-import.md` §3.1/§3.2).
///
/// The two passes after the stamping are `register_added`'s name-FINALIZING half
/// ([`common::ensure_unique_face_names`] + [`common::stamp_derived_edge_names`]),
/// applied HERE rather than at restore time: the `nativeBrep` lane registers
/// verbatim, so whatever the payload carries IS the final name set. Without them
/// a payload's edge names would be the importer's raw ones while the `stepText`
/// lane's are the derived `{faceA}|{faceB}[n]` — the same geometry under two
/// different name sets, which is exactly what this helper exists to prevent.
///
/// The payload is byte-deterministic for identical input (`snapshot_solids`), so
/// two encodings of the same part collapse to ONE parts-library entry.
pub fn native_import_payload(feature_name: &str, solids: &[BrepSolid]) -> Result<String, String> {
    native_import_payload_with_appearance(feature_name, solids, &[])
}

/// [`native_import_payload`] carrying the import's COLOURS into the payload.
///
/// `appearances` is parallel to `solids` (see [`crate::BodyAppearance`]); `&[]`
/// is the colourless case and makes this identical to [`native_import_payload`].
///
/// The colours are stamped into the AMBIENT scene-metadata store just before
/// `snapshot_solids`, which is exactly how they get INTO the payload — the
/// snapshot captures each stamped name's own record alongside the geometry. So a
/// caller that runs this inside a `crate::IsolatedSceneMetadata` bracket (the
/// STEP-assembly part-document lane does, and must) gets the colours sealed into
/// the part and discarded from the live document, which is the whole point of
/// that bracket: the part carries its own metadata, the open document is not
/// touched.
pub fn native_import_payload_with_appearance(
    feature_name: &str,
    solids: &[BrepSolid],
    appearances: &[BodyAppearance],
) -> Result<String, String> {
    if solids.is_empty() {
        return Err("import3d: native payload needs at least one solid".into());
    }
    let mut bodies = solids.to_vec();
    let body_names = stamp_imported_names(&mut bodies, feature_name);
    for solid in &mut bodies {
        common::ensure_unique_face_names(solid);
        common::stamp_derived_edge_names(solid);
    }
    // Names are FINAL from here, so this is where colour can be keyed to them.
    for (index, (solid, body_name)) in bodies.iter().zip(&body_names).enumerate() {
        if let Some(appearance) = appearances.get(index) {
            stamp_appearance(body_name, &common::collect_face_names(solid), appearance);
        }
    }
    let named: Vec<(&str, &BrepSolid)> = body_names
        .iter()
        .map(String::as_str)
        .zip(bodies.iter())
        .collect();
    crate::snapshot_solids(&named)
}


/// Context-bar applicability ([`crate::feature_pipeline::context_offer`]):
/// never offered from a selection (no reference inputs).
pub fn context_applicable(_probe: &crate::feature_pipeline::SelectionProbe) -> bool {
    false
}

/// This feature's kernel-owned definition (name + parameter schema), kept
/// WITH the feature code — the caller's feature editor requests it via `feature_schemas_json`
/// (see `feature_pipeline/schema.rs`, which aggregates every feature's
/// `schema()` into the catalogue).
///
/// Only `id` is exposed: an IMPORT3D feature is created by an import lane that
/// bakes its payload in — the toolbar Import lane
/// ([`EngineState::import_step_feature`] / `import_iges_feature`) writes the raw
/// document text into `inputParams.stepText` / `igesText`, and the native lane
/// ([`native_import_payload`], the STEP-assembly part document) writes
/// `inputParams.nativeBrep`. None of the three is form-editable, so none is
/// exposed. (The former `fileToImport` "file" param was a JS-era vestige: nothing
/// produced or consumed it and no form builder rendered it.)
pub fn schema() -> serde_json::Value {
    serde_json::json!({
    "type": "IMPORT3D",
    "shortName": "IMPORT3D",
    "longName": "Import 3D Model",
    "displayBuilder": false,
    "inputParamsSchema": {
        "id": {
            "type": "string",
            "default_value": null,
            "hint": "unique identifier for the import feature"
        }
    }
})
}

#[cfg(test)]
mod tests {
    use crate::feature_pipeline::scene_metadata::{
        scene_metadata_get_own_json, scene_metadata_load_json, scene_metadata_set_json,
    };
    use crate::feature_pipeline::{execute_history, HistoryRequest, HistoryResult};
    use crate::{encode_solid, native_import_payload, restore_solids, BrepSolid, Vec3};

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

    fn volume(handle: u32) -> f64 {
        crate::with_registered_solid_str(handle, |solid| {
            crate::solid_mass_properties(solid).map(|p| p.volume)
        })
        .expect("mass properties")
    }

    #[test]
    fn step_text_round_trip_imports_named_solid() {
        // export_step(box) → the pipeline imports it back: exact round-trip.
        let solid = crate::make_box_brep(Vec3::new(0.0, 0.0, 0.0), 4.0, 3.0, 2.0).unwrap();
        let step_text =
            crate::export_step(&[solid], "part", "MM", "2026-01-01T00:00:00Z").unwrap();

        let history = run(serde_json::json!({
            "expressions": "", "configurator": {},
            "features": [{ "type": "IMPORT3D",
                "inputParams": { "id": "Imp", "stepText": step_text },
                "persistentData": {}, "timestamp": null }]
        }));
        let result = &history.results[0];
        assert!(result.error.is_none(), "import error: {:?}", result.error);
        let added = &result.added[0];
        assert_eq!(added.name, "Imp", "single body keeps the feature name");
        let got = volume(added.handle);
        assert!((got - 24.0).abs() < 1e-6, "imported volume {got}, expected 24");
        // Single-body face names are prepended with the feature name so a second
        // import never collides; the fallback stem stays `Face_N`.
        assert!(
            added.face_names.iter().any(|(_, n)| n == "Imp_Face_0"),
            "feature-prefixed face names: {:?}",
            added.face_names
        );
        crate::feature_pipeline::clear_history_cache();
    }

    #[test]
    fn two_single_body_imports_do_not_collide_on_face_names() {
        // Regression: importing the SAME box twice used to leave both resident
        // solids with bare `Face_0..` (and the edges derived from them), which the
        // cross-solid name-uniqueness guard flags. Feature-name prefixing keeps
        // each import's faces (and derived edges) unique — no collision error.
        let solid = crate::make_box_brep(Vec3::new(0.0, 0.0, 0.0), 4.0, 3.0, 2.0).unwrap();
        let step_text =
            crate::export_step(&[solid], "part", "MM", "2026-01-01T00:00:00Z").unwrap();

        let history = run(serde_json::json!({
            "expressions": "", "configurator": {},
            "features": [
                { "type": "IMPORT3D",
                  "inputParams": { "id": "ImpA", "stepText": step_text },
                  "persistentData": {}, "timestamp": null },
                { "type": "IMPORT3D",
                  "inputParams": { "id": "ImpB", "stepText": step_text },
                  "persistentData": {}, "timestamp": null }
            ]
        }));
        for result in &history.results {
            assert!(
                result.error.is_none(),
                "import `{}` errored (expected no name collision): {:?}",
                result.id,
                result.error
            );
        }
        let names_a: std::collections::BTreeSet<_> =
            history.results[0].added[0].face_names.iter().map(|(_, n)| n.clone()).collect();
        let names_b: std::collections::BTreeSet<_> =
            history.results[1].added[0].face_names.iter().map(|(_, n)| n.clone()).collect();
        assert!(
            names_a.is_disjoint(&names_b),
            "the two imports must not share any face name: A={names_a:?} B={names_b:?}"
        );
        crate::feature_pipeline::clear_history_cache();
    }

    #[test]
    fn import_cache_records_replay_with_multi_body_names() {
        // Two serde BrepSolid records in importCache → {id}_SOLID_01/_02 with
        // body-prefixed face names.
        let a = crate::make_box_brep(Vec3::new(0.0, 0.0, 0.0), 1.0, 1.0, 1.0).unwrap();
        let b = crate::make_box_brep(Vec3::new(5.0, 0.0, 0.0), 2.0, 2.0, 2.0).unwrap();
        let records = serde_json::json!([
            serde_json::to_value(&a).unwrap(),
            serde_json::to_value(&b).unwrap(),
        ]);

        let history = run(serde_json::json!({
            "expressions": "", "configurator": {},
            "features": [{ "type": "IMPORT3D",
                "inputParams": { "id": "Imp" },
                "persistentData": { "importCache": {
                    "version": 3, "kind": "step-brep", "kernelSolidRecords": records,
                    "updatedAt": "2026-01-01T00:00:00.000Z" } },
                "timestamp": null }]
        }));
        let result = &history.results[0];
        assert!(result.error.is_none(), "cache replay error: {:?}", result.error);
        assert_eq!(result.added.len(), 2);
        assert_eq!(result.added[0].name, "Imp_SOLID_01");
        assert_eq!(result.added[1].name, "Imp_SOLID_02");
        assert!(
            result.added[1]
                .face_names
                .iter()
                .all(|(_, n)| n.starts_with("Imp_SOLID_02_Face_")),
            "multi-body faces namespaced: {:?}",
            result.added[1].face_names
        );
        let got = volume(result.added[1].handle);
        assert!((got - 8.0).abs() < 1e-6, "second body volume {got}, expected 8");
        crate::feature_pipeline::clear_history_cache();
    }

    // -----------------------------------------------------------------------
    // The native payload lane: `native_import_payload` (A1) + the `nativeBrep`
    // source (A2) — kernel-plan `step-assembly-import.md` §3.1/§3.2.
    // -----------------------------------------------------------------------

    fn boxes(count: usize) -> Vec<BrepSolid> {
        (0..count)
            .map(|index| {
                let offset = index as f64 * 10.0;
                crate::make_box_brep(
                    Vec3::new(offset, 0.0, 0.0),
                    1.0 + index as f64,
                    2.0,
                    3.0,
                )
                .unwrap()
            })
            .collect()
    }

    fn face_names(solid: &BrepSolid) -> Vec<String> {
        super::common::collect_face_names(solid)
            .into_iter()
            .map(|(_, name)| name)
            .collect()
    }

    fn edge_names(solid: &BrepSolid) -> Vec<String> {
        super::common::collect_edge_names(solid)
            .into_iter()
            .map(|(_, name)| name)
            .collect()
    }

    /// The naming ORACLE: the SAME solids through a live import lane. The
    /// `importCache` source is `add_named_bodies` with no importer in front of
    /// it, so what it registers is exactly what a `stepText` import registers
    /// for those solids — and therefore exactly what the payload must carry.
    fn names_through_the_live_lane(
        feature: &str,
        solids: &[BrepSolid],
    ) -> Vec<(String, Vec<String>, Vec<String>)> {
        let records: Vec<serde_json::Value> = solids
            .iter()
            .map(|solid| serde_json::to_value(solid).unwrap())
            .collect();
        let history = run(serde_json::json!({
            "expressions": "", "configurator": {},
            "features": [{ "type": "IMPORT3D",
                "inputParams": { "id": feature },
                "persistentData": { "importCache": {
                    "version": 3, "kind": "step-brep", "kernelSolidRecords": records,
                    "updatedAt": "2026-01-01T00:00:00.000Z" } },
                "timestamp": null }]
        }));
        let result = &history.results[0];
        assert!(result.error.is_none(), "oracle lane error: {:?}", result.error);
        let names = result
            .added
            .iter()
            .map(|added| {
                (
                    added.name.clone(),
                    added.face_names.iter().map(|(_, n)| n.clone()).collect(),
                    added.edge_names.iter().map(|(_, n)| n.clone()).collect(),
                )
            })
            .collect();
        crate::feature_pipeline::clear_history_cache();
        names
    }

    /// A payload's solids must restore to the INPUT geometry, bit for bit,
    /// under the names the live lane would have stamped. Runs both naming
    /// branches: one body (feature name + `{feature}_{stem}` faces) and several
    /// (`{feature}_SOLID_0N` + `{body}_Face_{f}`).
    #[test]
    fn native_payload_restores_the_input_solids_with_the_import3d_names() {
        for count in [1usize, 2] {
            // Deterministic store state: `snapshot_solids` captures whatever
            // records the thread's store holds for the stamped names.
            scene_metadata_load_json("{}").unwrap();
            let solids = boxes(count);
            let payload = native_import_payload("Imp", &solids).expect("payload encodes");
            let restored = restore_solids(&payload).expect("payload restores");
            assert_eq!(restored.solids.len(), count, "{count}-body payload");

            let oracle = names_through_the_live_lane("Imp", &solids);
            assert_eq!(oracle.len(), count);
            for (index, entry) in restored.solids.iter().enumerate() {
                // Geometry: the payload transports the INPUT solid unchanged
                // (the flat `f64` codec round-trips every coordinate bit-exact).
                let (want, _) = encode_solid(&solids[index]).expect("encode input");
                let (got, _) = encode_solid(&entry.solid).expect("encode restored");
                assert_eq!(got, want, "body {index} geometry must be bit-identical");
                // Names: identical to the live lane's, body/face/edge alike.
                let (body, faces, edges) = &oracle[index];
                assert_eq!(&entry.name, body, "body name");
                assert_eq!(&face_names(&entry.solid), faces, "face names");
                assert_eq!(&edge_names(&entry.solid), edges, "edge names");
            }
            // Spot-check the convention itself, so a change to BOTH lanes at
            // once still trips a test.
            if count == 1 {
                assert_eq!(restored.solids[0].name, "Imp");
                assert!(face_names(&restored.solids[0].solid).iter().all(|n| n.starts_with("Imp_")));
            } else {
                assert_eq!(restored.solids[0].name, "Imp_SOLID_01");
                assert_eq!(restored.solids[1].name, "Imp_SOLID_02");
                assert!(face_names(&restored.solids[1].solid)
                    .iter()
                    .all(|n| n.starts_with("Imp_SOLID_02_Face_")));
            }
            scene_metadata_load_json("{}").unwrap();
        }
    }

    /// The part-document shape of kernel-plan §3.2, executed end to end: one
    /// IMPORT3D feature whose only input is `nativeBrep`.
    #[test]
    fn native_brep_document_round_trips_through_the_pipeline() {
        scene_metadata_load_json("{}").unwrap();
        let solids = boxes(2);
        let payload = native_import_payload("IMPORT3D1", &solids).expect("payload encodes");
        // A metadata record stamped on the part's face must ride along in the
        // payload and land back in the store when the document executes.
        let restored = restore_solids(&payload).expect("payload restores");
        let face = face_names(&restored.solids[0].solid)[0].clone();
        scene_metadata_set_json(&face, r#"{"material":"steel"}"#).unwrap();
        let payload = native_import_payload("IMPORT3D1", &solids).expect("payload re-encodes");
        scene_metadata_load_json("{}").unwrap();

        let history = run(serde_json::json!({
            "expressions": "", "configurator": {},
            "features": [{ "type": "IMPORT3D",
                "inputParams": { "id": "IMPORT3D1", "nativeBrep": payload },
                "persistentData": {}, "timestamp": null }]
        }));
        let result = &history.results[0];
        assert!(result.error.is_none(), "native import error: {:?}", result.error);
        assert_eq!(result.added.len(), 2);
        assert_eq!(result.added[0].name, "IMPORT3D1_SOLID_01");
        assert_eq!(result.added[1].name, "IMPORT3D1_SOLID_02");
        let got = volume(result.added[1].handle);
        assert!((got - 12.0).abs() < 1e-9, "second body volume {got}, expected 12");
        let record: serde_json::Value =
            serde_json::from_str(&scene_metadata_get_own_json(&face)).unwrap();
        assert_eq!(record["material"], "steel", "captured record must be merged back");
        crate::feature_pipeline::clear_history_cache();
        scene_metadata_load_json("{}").unwrap();
    }

    /// Names come out of the PAYLOAD, never re-derived from the feature id: a
    /// part keeps the names it was imported with wherever its document is
    /// executed (a library entry's heal runs it under a different id).
    #[test]
    fn native_brep_registers_the_stored_names_verbatim() {
        scene_metadata_load_json("{}").unwrap();
        let solids = boxes(1);
        let payload = native_import_payload("Bracket", &solids).expect("payload encodes");
        let history = run(serde_json::json!({
            "expressions": "", "configurator": {},
            "features": [{ "type": "IMPORT3D",
                "inputParams": { "id": "IMPORT3D7", "nativeBrep": payload },
                "persistentData": {}, "timestamp": null }]
        }));
        let result = &history.results[0];
        assert!(result.error.is_none(), "native import error: {:?}", result.error);
        assert_eq!(result.added[0].name, "Bracket", "stored body name wins");
        assert!(
            result.added[0].face_names.iter().all(|(_, n)| n.starts_with("Bracket_")),
            "stored face names must survive verbatim: {:?}",
            result.added[0].face_names
        );
        crate::feature_pipeline::clear_history_cache();
        scene_metadata_load_json("{}").unwrap();
    }

    /// A payload that does not decode surfaces as this feature's OWN result
    /// error — a reported, inspectable outcome, never a panic and never damage
    /// to the features that already ran. (The history still stops at the first
    /// erroring feature, as it does for any feature error; it is the IMPORT
    /// lane above the kernel that counts a failed part and carries on.)
    #[test]
    fn corrupt_native_payload_is_a_clean_feature_error() {
        scene_metadata_load_json("{}").unwrap();
        let payload = native_import_payload("Imp", &boxes(1)).expect("payload encodes");
        // Flip one base64 character: the container checksum must catch it.
        let mut corrupt: Vec<char> = payload.chars().collect();
        corrupt[20] = if corrupt[20] == 'A' { 'B' } else { 'A' };
        let corrupt: String = corrupt.into_iter().collect();
        assert_ne!(corrupt, payload, "the flip must actually change the payload");

        let history = run(serde_json::json!({
            "expressions": "", "configurator": {},
            "features": [
                { "type": "IMPORT3D",
                  "inputParams": { "id": "Good", "nativeBrep": payload },
                  "persistentData": {}, "timestamp": null },
                { "type": "IMPORT3D",
                  "inputParams": { "id": "Bad", "nativeBrep": corrupt },
                  "persistentData": {}, "timestamp": null }
            ]
        }));
        assert_eq!(history.results.len(), 2, "both features produced a result");
        assert!(
            history.results[0].error.is_none(),
            "the healthy import must still stand: {:?}",
            history.results[0].error
        );
        assert_eq!(history.results[0].added.len(), 1);
        let error = history.results[1].error.as_deref().unwrap_or_default();
        assert!(
            error.contains("native payload did not decode"),
            "expected the clean decode error, got {error:?}"
        );
        assert!(history.results[1].added.is_empty(), "a failed import adds nothing");
        crate::feature_pipeline::clear_history_cache();

        // Garbage that is not a container at all is the same clean error.
        let history = run(serde_json::json!({
            "expressions": "", "configurator": {},
            "features": [{ "type": "IMPORT3D",
                "inputParams": { "id": "Bad", "nativeBrep": "not-a-payload" },
                "persistentData": {}, "timestamp": null }]
        }));
        assert!(
            history.results[0]
                .error
                .as_deref()
                .unwrap_or_default()
                .contains("native payload did not decode"),
            "expected the clean decode error, got {:?}",
            history.results[0].error
        );
        crate::feature_pipeline::clear_history_cache();
        scene_metadata_load_json("{}").unwrap();
    }

    /// EXACTLY ONE source: a feature carrying both a payload and a text source
    /// is malformed, and silently preferring one would drop the other.
    #[test]
    fn native_brep_with_a_text_source_is_an_error() {
        scene_metadata_load_json("{}").unwrap();
        let solids = boxes(1);
        let payload = native_import_payload("Imp", &solids).expect("payload encodes");
        let step_text =
            crate::export_step(&solids, "part", "MM", "2026-01-01T00:00:00Z").unwrap();

        let history = run(serde_json::json!({
            "expressions": "", "configurator": {},
            "features": [{ "type": "IMPORT3D",
                "inputParams": { "id": "Imp", "nativeBrep": payload, "stepText": step_text },
                "persistentData": {}, "timestamp": null }]
        }));
        let error = history.results[0].error.as_deref().unwrap_or_default();
        assert!(
            error.contains("exclusive"),
            "expected the one-source error, got {error:?}"
        );
        assert!(history.results[0].added.is_empty(), "nothing imports on a conflict");
        crate::feature_pipeline::clear_history_cache();

        // A present-but-non-string payload errors HERE rather than falling
        // through to a different source.
        let history = run(serde_json::json!({
            "expressions": "", "configurator": {},
            "features": [{ "type": "IMPORT3D",
                "inputParams": { "id": "Imp", "nativeBrep": 42 },
                "persistentData": {}, "timestamp": null }]
        }));
        assert!(
            history.results[0]
                .error
                .as_deref()
                .unwrap_or_default()
                .contains("must be a base64 snapshot string"),
            "expected the type error, got {:?}",
            history.results[0].error
        );
        crate::feature_pipeline::clear_history_cache();
        scene_metadata_load_json("{}").unwrap();
    }

    /// A1O — imported STEP COLOUR reaches the name-keyed metadata store, both
    /// per body and per face, and rides the native payload back.
    ///
    /// Two REAL corpus fixtures, one per styling target:
    /// * `freecad_partdesign_body.step` styles its MANIFOLD_SOLID_BREP grey
    ///   (`COLOUR_RGB 0.8`) AND pairs it with a near-black CURVE_STYLE — so the
    ///   body must come out `#CCCCCC`, never the curve's `#191919`.
    /// * `io1-ug-214.stp` over-rides ONE ADVANCED_FACE with a
    ///   `DRAUGHTING_PRE_DEFINED_COLOUR('red')` fill while its solid carries a
    ///   boundary-only style — so exactly one face is `#FF0000` and the body has
    ///   no colour at all.
    #[test]
    fn step_colours_land_on_the_metadata_records_and_survive_the_payload() {
        const BODY_COLOURED: &str = include_str!(concat!(
            env!("CARGO_MANIFEST_DIR"),
            "/tests/fixtures/step-import/freecad_partdesign_body.step"
        ));
        const FACE_COLOURED: &str = include_str!(concat!(
            env!("CARGO_MANIFEST_DIR"),
            "/tests/fixtures/step-import/io1-ug-214.stp"
        ));
        let color_of = |name: &str| -> Option<String> {
            serde_json::from_str::<serde_json::Value>(&scene_metadata_get_own_json(name))
                .unwrap()
                .get("color")
                .and_then(|value| value.as_str())
                .map(str::to_string)
        };

        // --- per-body, through the live `stepText` lane ---------------------
        scene_metadata_load_json("{}").unwrap();
        let history = run(serde_json::json!({
            "expressions": "", "configurator": {},
            "features": [{ "type": "IMPORT3D",
                "inputParams": { "id": "Imp", "stepText": BODY_COLOURED },
                "persistentData": {}, "timestamp": null }]
        }));
        let added = &history.results[0].added[0];
        assert_eq!(
            color_of(&added.name).as_deref(),
            Some("#CCCCCC"),
            "the solid's FILL_AREA colour, not its CURVE_STYLE colour"
        );
        assert!(
            added.face_names.iter().all(|(_, name)| color_of(name).is_none()),
            "a per-body colour must not be fanned out onto the faces"
        );
        crate::feature_pipeline::clear_history_cache();

        // --- per-face, and the payload round trip ---------------------------
        scene_metadata_load_json("{}").unwrap();
        let history = run(serde_json::json!({
            "expressions": "", "configurator": {},
            "features": [{ "type": "IMPORT3D",
                "inputParams": { "id": "Imp", "stepText": FACE_COLOURED },
                "persistentData": {}, "timestamp": null }]
        }));
        let added = &history.results[0].added[0];
        assert_eq!(color_of(&added.name), None, "boundary style is not a body colour");
        let red: Vec<&String> = added
            .face_names
            .iter()
            .map(|(_, name)| name)
            .filter(|name| color_of(name).as_deref() == Some("#FF0000"))
            .collect();
        assert_eq!(red.len(), 1, "exactly one over-ridden face is red: {red:?}");
        let red_face = red[0].clone();
        crate::feature_pipeline::clear_history_cache();

        // The native payload lane must carry the SAME colour: encode the same
        // import into a part document, wipe the store, execute it, and the
        // record must be back on the same face name.
        let (solids, appearances) =
            crate::import_step_with_appearance(FACE_COLOURED).expect("fixture imports");
        scene_metadata_load_json("{}").unwrap();
        let payload = crate::native_import_payload_with_appearance("Imp", &solids, &appearances)
            .expect("payload encodes");
        scene_metadata_load_json("{}").unwrap();
        let history = run(serde_json::json!({
            "expressions": "", "configurator": {},
            "features": [{ "type": "IMPORT3D",
                "inputParams": { "id": "Imp", "nativeBrep": payload },
                "persistentData": {}, "timestamp": null }]
        }));
        assert!(history.results[0].error.is_none(), "{:?}", history.results[0].error);
        assert_eq!(
            color_of(&red_face).as_deref(),
            Some("#FF0000"),
            "the colour must ride the snapshot into the part document"
        );
        crate::feature_pipeline::clear_history_cache();
        scene_metadata_load_json("{}").unwrap();
    }

    /// A colour the USER edited in the info panel outlives a history replay:
    /// the import stamp is a non-overwriting merge, not an assignment.
    #[test]
    fn a_user_edited_colour_survives_a_re_execution() {
        const BODY_COLOURED: &str = include_str!(concat!(
            env!("CARGO_MANIFEST_DIR"),
            "/tests/fixtures/step-import/freecad_partdesign_body.step"
        ));
        scene_metadata_load_json("{}").unwrap();
        let request = serde_json::json!({
            "expressions": "", "configurator": {},
            "features": [{ "type": "IMPORT3D",
                "inputParams": { "id": "Imp", "stepText": BODY_COLOURED },
                "persistentData": {}, "timestamp": null }]
        });
        let history = run(request.clone());
        let name = history.results[0].added[0].name.clone();
        // `r##` — a `"#` inside a plain `r#"…"#` would close the literal early.
        scene_metadata_set_json(&name, r##"{"color":"#123456"}"##).unwrap();
        run(request);
        let record: serde_json::Value =
            serde_json::from_str(&scene_metadata_get_own_json(&name)).unwrap();
        assert_eq!(record["color"], "#123456", "the user's edit must win");
        crate::feature_pipeline::clear_history_cache();
        scene_metadata_load_json("{}").unwrap();
    }

    #[test]
    fn import_without_source_errors_loudly() {
        let history = run(serde_json::json!({
            "expressions": "", "configurator": {},
            "features": [{ "type": "IMPORT3D", "inputParams": { "id": "Imp" },
                "persistentData": {}, "timestamp": null }]
        }));
        assert!(
            history.results[0].error.as_deref().unwrap_or("").contains("no model data"),
            "expected the no-source error, got {:?}",
            history.results[0].error
        );
    }
}