brep_kernel/feature_pipeline/

mod.rs

//! The Rust feature-history execution engine — the load-bearing CONTRACT that
//! per-feature migration agents fill in (migration-plan Stage 4/5 foundation).
//!
//! # The three contract rules (do not break these — the fan-out depends on them)
//!
//! 1. **Resolution happens inside the loop, by name.** [`execute_history`] keeps a
//!    live [`SceneMap`] (`solid_name -> handle`, `face_name -> (handle, face_id)`,
//!    `edge_name -> (handle, edge_id)`) and UPDATES it as each feature executes. A
//!    feature resolves its `reference_selection` params against that map by
//!    EXACT-MATCH (no scoring heuristic). A miss is a structured `unresolved`
//!    entry in the [`FeatureResult`] (the caller repairs + re-dispatches later), never a
//!    panic.
//! 2. **Name fidelity is the gate.** Output face/edge/solid names must BYTE-MATCH
//!    the established conventions (saved part files + every `reference_selection` store
//!    these strings). Each feature replicates the established naming exactly.
//! 3. **The descriptor IS the existing serialized `inputParams` shape** —
//!    `{ type, inputParams, persistentData, timestamp }` (see `PartHistory`
//!    `toSerializable`). `inputParams` is a JSON object; numeric params may be
//!    literals OR expression strings (evaluated against the shared [`Env`]).
//!
//! # Handle / registry discipline
//!
//! The scene-map owns handles (`u32`). Each op does its OWN short
//! `SOLID_REGISTRY` borrow internally (via the `crate::*_registered_solid*`
//! helpers) and NEVER holds a borrow across a feature execution. The engine calls
//! the underlying Rust fns directly (`crate::make_box_brep`, `crate::make_sphere_brep`,
//! `crate::boolean_operation`, …), not the `*_json` wasm wrappers, so names live on
//! the resident solids throughout. A leaked handle is a wasm32 OOM (4 GB ceiling),
//! so removed scene-resident solids are freed and features free their own
//! consumed intermediates.

use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use wasm_bindgen::prelude::*;

use crate::{NurbsCurve, Vec3};

mod expression;
#[path = "features/mod.rs"]
mod features;
pub(crate) mod scene_metadata;
mod schema;
// The kernel-owned feature-schema catalogue, reachable by NATIVE Rust consumers
// (the engine-native egui UI in brep-app, via a brep-render re-export) — the same
// definitions the wasm `feature_schemas_json` export serves the caller's feature registry.
pub use schema::feature_schema_catalogue;
#[path = "sheet_metal/mod.rs"]
mod sheet_metal;

pub use expression::Env;

// ===========================================================================
// Descriptor — the serialized `{ type, inputParams, persistentData, timestamp }`
// ===========================================================================

/// One feature as serialized by `PartHistory.toSerializable`. Permissive: unknown
/// fields are ignored, so an entire saved part file's `features[]` deserializes
/// as-is. `input_params` stays a `serde_json::Value` (an object) so features read
/// their own params with their own type knowledge (which params are numeric).
// `persistent_data` / `timestamp` are contract pass-throughs (round-tripped for
// features that need them, e.g. hole/pattern persistent state); not read yet.
#[allow(dead_code)]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FeatureDescriptor {
    #[serde(rename = "type", default)]
    pub feature_type: String,
    #[serde(rename = "inputParams", default)]
    pub input_params: serde_json::Value,
    #[serde(rename = "persistentData", default)]
    pub persistent_data: serde_json::Value,
    /// Opaque pass-through (any shape) so one odd saved file cannot fail the parse.
    #[serde(default)]
    pub timestamp: Option<serde_json::Value>,
}

/// The `execute_history_json` request: the expression source, the configurator
/// state, and the ordered feature list. Permissive — a whole saved part file
/// parses as a request (extra top-level fields ignored).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct HistoryRequest {
    #[serde(default, deserialize_with = "de_string_lenient")]
    pub expressions: String,
    #[serde(default)]
    pub configurator: serde_json::Value,
    #[serde(default)]
    pub features: Vec<FeatureDescriptor>,
    /// Stop AFTER executing the feature with this id (the editor's "stop at the
    /// expanded feature"). The features past the stop stay in the request so the
    /// incremental cache RETAINS their entries — expanding/collapsing a panel
    /// must not thrash the cache (marshal-side truncation would free them).
    #[serde(default, rename = "stopAtId")]
    pub stop_at_id: Option<String>,
    /// Stop BEFORE executing the feature with this id.
    #[serde(default, rename = "stopBeforeId")]
    pub stop_before_id: Option<String>,
    /// Render level-of-detail factor for DISPLAY tessellation (the app's "LOD
    /// factor" setting). `execute_history` ignores it — it rides on the request
    /// only because the request is the serialized run boundary the display runner
    /// receives, and the runner scales its per-solid chord tolerance by it
    /// (higher = coarser mesh). Defaults to `1.0` (the "Normal" preset) so a saved
    /// file / seed request with no `displayLod` tessellates exactly as before.
    #[serde(default = "default_display_lod", rename = "displayLod")]
    pub display_lod: f64,
}

/// The "Normal" render LOD — the [`HistoryRequest::display_lod`] serde default.
fn default_display_lod() -> f64 {
    1.0
}

/// Accept `null`/missing as `""` for a string field (saved files sometimes store
/// `expressions: null`).
fn de_string_lenient<'de, D>(deserializer: D) -> Result<String, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let value = Option::<String>::deserialize(deserializer)?;
    Ok(value.unwrap_or_default())
}

// ===========================================================================
// Result — the per-feature output contract the caller consumes
// ===========================================================================

/// A solid produced by a feature: its resident handle, its solid name, and its
/// named faces/edges (`(topology_id, name)`). the caller tessellates/pulls names via the
/// handle; the scene-map registers the names for downstream reference resolution.
#[derive(Debug, Clone, Serialize)]
pub struct AddedSolid {
    pub handle: u32,
    pub name: String,
    pub face_names: Vec<(u64, String)>,
    /// Edge names propagated/authored on the solid. Present so edge-selecting
    /// features (fillet/chamfer) can resolve "the edge of the extrude above"
    /// against the scene-map — the pinned example in contract rule 1.
    pub edge_names: Vec<(u64, String)>,
}

/// The output of one feature execution.
#[derive(Debug, Clone, Serialize)]
pub struct FeatureResult {
    pub id: String,
    pub feature_type: String,
    pub added: Vec<AddedSolid>,
    /// Names of prior solids this feature consumed/superseded (removed from the
    /// scene-map; their handles are freed by the loop).
    pub removed: Vec<String>,
    /// Set on a hard failure. `execute_history` records it and HALTS the
    /// remaining features (mirrors the abort-on-error loop). Never a panic.
    pub error: Option<String>,
    /// `reference_selection` names this feature could not resolve against the
    /// scene-map. NOT an error/halt — the caller runs a snapshot-repair pass and
    /// re-dispatches (migration-plan Stage 5 gate).
    pub unresolved: Vec<String>,
    /// True when this result was REPLAYED from the incremental history cache (the
    /// feature and everything it references are unchanged since the last run).
    /// The handles are the same resident solids — the caller can skip re-tessellation.
    pub reused: bool,
    /// Sketch profiles this feature produced (a SKETCH feature emits one under
    /// its name; solid features emit none). INTERNAL side-channel: `#[serde(skip)]`
    /// so it never crosses the wasm boundary to the caller — [`SceneMap::apply`] ingests it
    /// into `scene.profiles` for downstream profile-consumers (extrude/revolve/…).
    #[serde(skip)]
    pub profiles: Vec<(String, SketchProfile)>,
    /// Named plane frames this feature produced (DATUM emits three, PLANE one).
    /// Same INTERNAL `#[serde(skip)]` side-channel — ingested into `scene.frames`
    /// so a later SKETCH can resolve its plane by name, fully headless.
    #[serde(skip)]
    pub frames: Vec<(String, Frame)>,
    /// Named axis lines this feature produced (a SKETCH emits one per line
    /// geometry). Same INTERNAL `#[serde(skip)]` side-channel — ingested into
    /// `scene.axes` so a later revolve/sweep can resolve its axis by name.
    #[serde(skip)]
    pub axes: Vec<(String, Axis)>,
    /// Named path chains this feature produced (a SKETCH publishes its ordered
    /// open/closed geometry chain). Same INTERNAL `#[serde(skip)]` side-channel —
    /// ingested into `scene.paths` for sweep/path_sweep/rib trajectory resolution.
    #[serde(skip)]
    pub paths: Vec<(String, Vec<NurbsCurve>)>,
    /// Named world points this feature produced (a SKETCH publishes every point
    /// as `{sketchId}:P{pid}`). Same side-channel — ingested into `scene.points`
    /// for hole-center / placement resolution.
    #[serde(skip)]
    pub points: Vec<(String, Vec3)>,
}

impl FeatureResult {
    /// An empty successful result (no solids, no error) — the shape a non-solid
    /// pass-through feature returns.
    pub fn empty(id: impl Into<String>, feature_type: impl Into<String>) -> Self {
        Self {
            id: id.into(),
            feature_type: feature_type.into(),
            added: Vec::new(),
            removed: Vec::new(),
            error: None,
            unresolved: Vec::new(),
            reused: false,
            profiles: Vec::new(),
            frames: Vec::new(),
            axes: Vec::new(),
            paths: Vec::new(),
            points: Vec::new(),
        }
    }

    /// A hard failure. Halts the history loop.
    pub fn error(
        id: impl Into<String>,
        feature_type: impl Into<String>,
        message: impl Into<String>,
    ) -> Self {
        let mut result = Self::empty(id, feature_type);
        result.error = Some(message.into());
        result
    }

    /// A non-solid construction feature (datum/plane/sketch/spline/port/helix):
    /// a descriptor pass-through with no resident handle. The loop continues.
    pub fn pass_through(id: impl Into<String>, feature_type: impl Into<String>) -> Self {
        Self::empty(id, feature_type)
    }

    /// A solid-producing (or no-kernel) feature not yet ported to Rust. Halts the
    /// loop with a clear message — replaced when a fan-out agent implements the
    /// feature's `features/<feat>.rs`.
    pub fn not_yet_migrated(id: impl Into<String>, feature_type: impl Into<String>) -> Self {
        let feature_type = feature_type.into();
        let message = format!("feature type '{feature_type}' is not yet migrated to the Rust pipeline");
        Self::error(id, feature_type, message)
    }
}

/// The whole-history output.
#[derive(Debug, Clone, Serialize)]
pub struct HistoryResult {
    pub results: Vec<FeatureResult>,
    /// Per-feature wall-clock execution time `(feature id, milliseconds)` in run
    /// order — the lightweight timing surface the engine-native history tree's
    /// "N ms" readout consumes. A REUSED (cache-replayed) feature records `0.0`
    /// (its geometry was not re-executed this run). INTERNAL side-channel:
    /// `#[serde(skip)]` so it never changes the caller-facing `execute_history_json`
    /// shape; brep-render reads it natively via the re-exported struct.
    #[serde(skip)]
    pub timings: Vec<(String, f64)>,
}

// ===========================================================================
// SceneMap — the live name -> handle/topology index maintained across the loop
// ===========================================================================

// `handle` + `face_id`/`edge_id` are the contract the caller (and edge-selecting
// fan-out features) read to resolve a selection to a resident topology entity.
#[allow(dead_code)]
#[derive(Debug, Clone, Copy)]
pub struct FaceRef {
    pub handle: u32,
    pub face_id: u64,
}

#[allow(dead_code)]
#[derive(Debug, Clone, Copy)]
pub struct EdgeRef {
    pub handle: u32,
    pub edge_id: u64,
}

/// A solved sketch's extracted profile, placed in 3D. Produced by the SKETCH
/// pipeline feature and consumed BY NAME by the profile-consumers (extrude,
/// revolve, loft, sweep, rib, sheet-metal tab/contour-flange) — the exact-BREP
/// replacement for the old "marshal the resolved curves into `inputParams`".
///
/// The closed loops are grouped into disjoint REGIONS by even-odd containment
/// depth: a depth-EVEN loop is a region's OUTER boundary, a depth-ODD loop is a
/// hole of the region whose outer directly contains it (so an island inside a
/// hole is its own region). Each region is `[outer, holes…]`; consumers build
/// one solid per region and UNION them — the established multi-region behavior.
/// The plane frame (`origin` + orthonormal `x_axis`/`y_axis`/`z_axis`) is resolved
/// LIVE in Rust from the sketch's plane reference (DATUM/PLANE feature frame or a
/// resident face), falling back to the persisted `basis`; the loop curves are
/// emitted in WORLD space via that frame, so `z_axis` is the natural extrude
/// direction / a revolve-plane hint.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct SketchProfile {
    pub origin: Vec3,
    pub x_axis: Vec3,
    pub y_axis: Vec3,
    pub z_axis: Vec3,
    /// Disjoint regions, each `[outer, holes…]` (containment-classified).
    pub regions: Vec<Vec<ProfileLoop>>,
}

/// One closed boundary of a [`SketchProfile`]: head-to-tail world-space curves plus
/// the per-curve source edge name (`{sketchId}:G{gid}`, parallel to `curves`). The
/// profile-consumers stamp sidewall names from `edge_names` (extrude → `{name}_E`).
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct ProfileLoop {
    pub curves: Vec<NurbsCurve>,
    pub edge_names: Vec<Option<String>>,
}

/// An orthonormal placement frame — a named plane (DATUM/PLANE feature) or a
/// resolved sketch plane. `z_axis` is the plane normal.
#[derive(Debug, Clone, Copy, serde::Serialize, serde::Deserialize)]
pub struct Frame {
    pub origin: Vec3,
    pub x_axis: Vec3,
    pub y_axis: Vec3,
    pub z_axis: Vec3,
}

impl Frame {
    /// Derive an orthonormal frame from an origin + plane normal via the worldUp
    /// convention, the
    /// SINGLE source of truth for how a sketch/plane reference becomes in-plane
    /// axes: `refUp = |n·(0,1,0)| > 0.9 ? (1,0,0) : (0,1,0)`;
    /// `x = norm(refUp × n)`; `y = norm(n × x)`; `z = n`. The referenced object's
    /// own x/y are intentionally ignored — only its (origin, normal) matter.
    pub fn from_origin_normal(origin: Vec3, normal: Vec3) -> Result<Self, String> {
        let z_axis = normal.normalized()?;
        let world_up = Vec3::new(0.0, 1.0, 0.0);
        let ref_up = if z_axis.dot(world_up).abs() > 0.9 {
            Vec3::new(1.0, 0.0, 0.0)
        } else {
            world_up
        };
        let x_axis = ref_up.cross(z_axis).normalized()?;
        let y_axis = z_axis.cross(x_axis).normalized()?;
        Ok(Frame {
            origin,
            x_axis,
            y_axis,
            z_axis,
        })
    }

    /// Map a plane-local `(u, v)` into world space: `origin + u·x + v·y`.
    pub fn to_3d(&self, u: f64, v: f64) -> Vec3 {
        self.origin
            .add(self.x_axis.scale(u))
            .add(self.y_axis.scale(v))
    }
}

/// A named world-space line — a revolve/sweep axis. Published by SKETCH features
/// (every sketch line geometry, construction included) and resolvable from a
/// resident solid edge, so an `axis`/path reference resolves fully headless.
#[derive(Debug, Clone, Copy, serde::Serialize, serde::Deserialize)]
pub struct Axis {
    pub point: Vec3,
    pub direction: Vec3,
}

/// The live scene-map. Exact-match resolution only (contract rule 1).
#[derive(Debug, Clone, Default)]
pub struct SceneMap {
    pub solids: HashMap<String, u32>,
    pub faces: HashMap<String, FaceRef>,
    pub edges: HashMap<String, EdgeRef>,
    /// Sketch name -> its extracted profile. Populated by SKETCH features; read by
    /// profile-consumers via [`SceneMap::resolve_profile`].
    pub profiles: HashMap<String, SketchProfile>,
    /// Plane name -> its frame. Populated by DATUM/PLANE features; read by SKETCH
    /// (and PLANE datum-refs) via [`SceneMap::resolve_frame`] for headless plane
    /// resolution (fully headless).
    pub frames: HashMap<String, Frame>,
    /// Axis name -> its world line. Populated by SKETCH line geometries; read by
    /// revolve/sweep via [`SceneMap::resolve_axis`].
    pub axes: HashMap<String, Axis>,
    /// Path name -> its ordered world curve chain (open or closed). Populated by
    /// SKETCH features; read by sweep/path_sweep/rib via [`SceneMap::resolve_path`].
    pub paths: HashMap<String, Vec<NurbsCurve>>,
    /// Point name -> its world position. Populated by SKETCH features
    /// (`{sketchId}:P{pid}`); read by hole placement via [`SceneMap::resolve_point`].
    pub points: HashMap<String, Vec3>,
}

impl SceneMap {
    /// Resolve a solid name to its resident handle (exact match).
    pub fn resolve_solid(&self, name: &str) -> Option<u32> {
        self.solids.get(name).copied()
    }

    /// Resolve a face name to its `(handle, face_id)` (exact match).
    pub fn resolve_face(&self, name: &str) -> Option<FaceRef> {
        self.faces.get(name).copied()
    }

    /// Resolve an edge name to its `(handle, edge_id)` (exact match). Contract
    /// surface for edge-selecting fan-out features (fillet/chamfer); no
    /// implemented feature consumes it yet.
    #[allow(dead_code)]
    pub fn resolve_edge(&self, name: &str) -> Option<EdgeRef> {
        self.edges.get(name).copied()
    }

    /// Resolve a profile reference name to the sketch profile it names. Tries the
    /// exact name first, then the name with a trailing `:PROFILE` stripped — a
    /// sketch is selectable both by its group name (`{id}`) and by its profile
    /// face name (`{id}:PROFILE`); both must resolve to
    /// the one profile stored under `{id}`.
    pub fn resolve_profile(&self, name: &str) -> Option<&SketchProfile> {
        if let Some(profile) = self.profiles.get(name) {
            return Some(profile);
        }
        name.strip_suffix(":PROFILE")
            .and_then(|base| self.profiles.get(base))
    }

    /// Resolve a named plane frame (exact match), for sketch/plane resolution.
    pub fn resolve_frame(&self, name: &str) -> Option<Frame> {
        self.frames.get(name).copied()
    }

    /// Resolve a named axis line (exact match), for revolve/sweep.
    pub fn resolve_axis(&self, name: &str) -> Option<Axis> {
        self.axes.get(name).copied()
    }

    /// Resolve a named path chain (exact match; also strips a trailing `:PROFILE`),
    /// for sweep/path_sweep/rib trajectories.
    pub fn resolve_path(&self, name: &str) -> Option<&Vec<NurbsCurve>> {
        if let Some(path) = self.paths.get(name) {
            return Some(path);
        }
        name.strip_suffix(":PROFILE")
            .and_then(|base| self.paths.get(base))
    }

    /// Resolve a named world point (exact match), for hole/placement centers.
    /// Contract surface consumed by the spline/hole placement tests; kept as the
    /// documented point-resolution API even where no shipping feature reads it
    /// yet (mirrors `resolve_edge`).
    #[allow(dead_code)]
    pub fn resolve_point(&self, name: &str) -> Option<Vec3> {
        self.points.get(name).copied()
    }

    /// Apply a feature's effect: removals first (a boolean result reuses a removed
    /// target's name), then additions. Removal only unmaps NAMES — it never frees
    /// the handle. Handles are owned by the incremental history cache (each by the
    /// entry of the feature that produced it) and die exactly when that entry is
    /// invalidated; freeing here would kill a clean upstream feature's cached
    /// solid the moment a downstream boolean consumed it.
    fn apply(&mut self, result: &FeatureResult) {
        for name in &result.removed {
            if let Some(handle) = self.solids.remove(name) {
                // Purge the removed solid's face/edge entries (names only).
                self.faces.retain(|_, face| face.handle != handle);
                self.edges.retain(|_, edge| edge.handle != handle);
            }
            // A removed name not in the map is a silent no-op (established semantics).
        }
        // Ingest any sketch profiles this feature produced (SKETCH features only).
        for (name, profile) in &result.profiles {
            self.profiles.insert(name.clone(), profile.clone());
        }
        // Ingest any named plane frames (DATUM/PLANE features).
        for (name, frame) in &result.frames {
            self.frames.insert(name.clone(), *frame);
        }
        // Ingest any named axis lines (SKETCH line geometries).
        for (name, axis) in &result.axes {
            self.axes.insert(name.clone(), *axis);
        }
        // Ingest any named path chains (SKETCH geometry chains).
        for (name, path) in &result.paths {
            self.paths.insert(name.clone(), path.clone());
        }
        // Ingest any named world points (SKETCH points).
        for (name, point) in &result.points {
            self.points.insert(name.clone(), *point);
        }
        for added in &result.added {
            self.solids.insert(added.name.clone(), added.handle);
            for (face_id, name) in &added.face_names {
                self.faces.insert(
                    name.clone(),
                    FaceRef {
                        handle: added.handle,
                        face_id: *face_id,
                    },
                );
            }
            for (edge_id, name) in &added.edge_names {
                self.edges.insert(
                    name.clone(),
                    EdgeRef {
                        handle: added.handle,
                        edge_id: *edge_id,
                    },
                );
            }
        }
    }
}

// ===========================================================================
// FeatureContext — everything a feature's `execute(ctx)` needs
// ===========================================================================

/// The read-only context handed to each feature's `execute`. Features resolve
/// their `reference_selection` params against `scene` and read numeric params via
/// [`FeatureContext::number`] (which evaluates expression strings against `env`).
pub struct FeatureContext<'a> {
    pub id: String,
    pub feature_type: String,
    pub params: &'a serde_json::Value,
    /// The feature's `persistentData` (round-tripped from the saved part file).
    /// The SKETCH feature reads its `sketch` + `basis` here (the scene-computed
    /// plane frame stays caller-side per directive §1 and is marshaled in via this).
    pub persistent: &'a serde_json::Value,
    pub env: &'a Env,
    pub scene: &'a SceneMap,
}

impl<'a> FeatureContext<'a> {
    /// The raw param value (an object field of `inputParams`), if present.
    pub fn param(&self, key: &str) -> Option<&serde_json::Value> {
        self.params.get(key)
    }

    /// A numeric param: a JSON number passes through; a JSON string is evaluated
    /// as an expression against the shared env; anything else is an error. This is
    /// how a feature declares which of its params are numeric (the engine has no
    /// per-feature schema).
    pub fn number(&self, key: &str) -> Result<f64, String> {
        match self.param(key) {
            Some(serde_json::Value::Number(number)) => number
                .as_f64()
                .ok_or_else(|| format!("param `{key}` is not a finite number")),
            Some(serde_json::Value::String(source)) => self
                .env
                .eval(source)
                .map_err(|error| format!("param `{key}`: {error}")),
            Some(other) => Err(format!(
                "param `{key}` must be a number or expression string, found {other}"
            )),
            None => Err(format!("missing required param `{key}`")),
        }
    }

    /// A string param (read verbatim — never expression-evaluated; used for ids
    /// and `reference_selection` names). Contract surface for fan-out features;
    /// the two implemented features read the id via `ctx.id` directly.
    #[allow(dead_code)]
    pub fn string(&self, key: &str) -> Option<String> {
        match self.param(key) {
            Some(serde_json::Value::String(text)) => Some(text.clone()),
            _ => None,
        }
    }

    /// A convenience [`FeatureResult::error`] carrying this feature's id + type.
    pub fn fail(&self, message: impl Into<String>) -> FeatureResult {
        FeatureResult::error(self.id.clone(), self.feature_type.clone(), message)
    }
}

// ===========================================================================
// Dispatch — a match on `feature_type` to the owning `features/<feat>.rs`
// ===========================================================================

/// Extract the feature id from `inputParams` (`id`, falling back to the
/// non-enumerable `featureID`). The solid + all face/edge names are prefixed
/// with this id, so name fidelity depends on it.
fn extract_id(params: &serde_json::Value) -> String {
    for key in ["id", "featureID"] {
        if let Some(serde_json::Value::String(text)) = params.get(key) {
            if !text.is_empty() {
                return text.clone();
            }
        }
    }
    String::new()
}

/// Resolve one feature descriptor to a [`FeatureResult`] against the current
/// scene. Each stub's arm calls its own `features::<feat>::execute` so a fan-out
/// agent implementing a feature touches ONLY that file — never this dispatch.
pub fn execute_feature(
    descriptor: &FeatureDescriptor,
    env: &Env,
    scene: &SceneMap,
) -> FeatureResult {
    let id = extract_id(&descriptor.input_params);
    let feature_type = descriptor.feature_type.clone();
    let ctx = FeatureContext {
        id: id.clone(),
        feature_type: feature_type.clone(),
        params: &descriptor.input_params,
        persistent: &descriptor.persistent_data,
        env,
        scene,
    };
    // Alias resolution mirrors the caller's feature registry, which matches short name,
    // LONG name, and class name (all uppercased) — saved files and tests use
    // long-name type strings like "CHAMFER"/"PLANE".
    match feature_type.as_str() {
        // --- Fully implemented (the exemplary pattern) ---
        "P.CU" | "CUBE" => features::cube::execute(&ctx),
        "P.S" | "SPHERE" => features::sphere::execute(&ctx),
        // --- Solid-producing primitives ---
        "P.CY" | "CYLINDER" => features::cylinder::execute(&ctx),
        "P.CO" | "CONE" => features::cone::execute(&ctx),
        "P.T" | "TORUS" => features::torus::execute(&ctx),
        "P.PY" | "PYRAMID" => features::pyramid::execute(&ctx),
        // --- Add-material ---
        "E" | "EXTRUDE" => features::extrude::execute(&ctx),
        "R" | "REVOLVE" => features::revolve::execute(&ctx),
        "LOFT" => features::loft::execute(&ctx),
        "SW" | "SWEEP" => features::sweep::execute(&ctx),
        "SWP" | "PATH SWEEP" | "PATHSWEEP" => features::path_sweep::execute(&ctx),
        "RIB" => features::rib::execute(&ctx),
        "TU" | "TUBE" => features::tube::execute(&ctx),
        // --- Edit / boolean / transform ---
        "B" | "BOOLEAN" => features::boolean::execute(&ctx),
        "M" | "MIRROR" => features::mirror::execute(&ctx),
        "SPL" | "SPLIT" => features::split::execute(&ctx),
        "XFORM" | "TRANSFORM" => features::transform::execute(&ctx),
        "PATTERN" => features::pattern::execute(&ctx),
        // --- Dressups ---
        "F" | "FILLET" => features::fillet::execute(&ctx),
        "CH" | "CHAMFER" => features::chamfer::execute(&ctx),
        "O.S" | "OFFSET SHELL" | "OFFSETSHELL" => features::offset_shell::execute(&ctx),
        "O.F" | "OFFSET FACE" | "OFFSETFACE" => features::offset_face::execute(&ctx),
        "PF" | "PUSHFACE" | "PUSH FACE" => features::push_face::execute(&ctx),
        "DF" | "DELETE FACE" | "DELETEFACE" => features::delete_face::execute(&ctx),
        "THK" | "THICKEN" => features::thicken::execute(&ctx),
        "H" | "HOLE" => features::hole::execute(&ctx),
        // --- No-kernel-op / long tail ---
        "IMPORT3D" => features::import3d::execute(&ctx),
        "SM.TAB" => features::sheet_metal_tab::execute(&ctx),
        "SM.CF" => features::sheet_metal_contour_flange::execute(&ctx),
        "SM.F" => features::sheet_metal_flange::execute(&ctx),
        "SM.HEM" => features::sheet_metal_hem::execute(&ctx),
        "SM.CUTOUT" => features::sheet_metal_cutout::execute(&ctx),
        "SM.UNFOLD" => features::sheet_metal_unfold::execute(&ctx),
        // --- Construction geometry that registers named plane frames (headless
        //     sketch-plane resolution) ---
        "D" | "DATUM" | "DATIUM" => features::datum::execute(&ctx),
        "P" | "PLANE" => features::plane::execute(&ctx),
        // --- Sketch: solves + extracts a profile the add-material features consume ---
        "S" | "SKETCH" => features::sketch::execute(&ctx),
        // --- Non-solid construction geometry: editor-drawn pass-throughs ---
        "SP" | "SPLINE" => features::spline::execute(&ctx),
        "PORT" => features::port::execute(&ctx),
        "HX" | "HELIX" => features::helix::execute(&ctx),
        // --- Genuinely unknown type string ---
        _ => FeatureResult::error(id, feature_type.clone(), format!("unknown feature type '{feature_type}'")),
    }
}

// ===========================================================================
// The incremental history cache — dependency-driven dirty tracking
// ===========================================================================
//
// A feature is DIRTY when it itself changed (its serialized descriptor hash — or
// the expression env — differs) or when a NAME it references was (re)produced,
// removed, or re-resolved differently since its cached run. Everything else is
// CLEAN: its cached result (resident handles, profiles, frames, axes, paths)
// replays into the scene untouched and is flagged `reused` so the caller skips display
// rebuild. Dependency edges come from the exact-match name contract itself
// (contract rule 1): any string in a feature's params matching a name produced
// earlier in the history IS a reference.
//
// OWNERSHIP: cache entries own the handles their feature produced. A handle (and
// its sheet-metal tree) is freed exactly when its producing entry is invalidated
// (feature dirty/deleted, or `clear_history_cache`). Nothing else frees scene
// handles — not `SceneMap::apply`, and not the caller (display Solids are non-owning
// views post-flip). Consumed intermediates therefore stay resident until an edit
// invalidates their producer: the accepted memory cost of incremental replay.

/// One cached feature execution.
struct CachedFeature {
    /// Hash of `type` + `inputParams` + `persistentData` + the env fingerprint.
    fingerprint: u64,
    /// The successful result (errored results are NEVER cached — an errored
    /// feature is unconditionally dirty next run).
    result: FeatureResult,
    /// The referenced names that RESOLVED against the names available at its
    /// position in the history. Compared for equality each run: a reference that
    /// starts/stops resolving (producer added/deleted/reordered) flips dirty.
    consumed: std::collections::BTreeSet<String>,
    /// Every name this feature produced or removed — the invalidation blast
    /// radius handed to `changed` when the entry dies.
    touched: HashMap<String, ()>,
    /// Content hash of this feature's EFFECTIVE inputs: its own `fingerprint`
    /// PLUS, for every consumed name, the producing feature's `output_version`
    /// (a Merkle hash over the feature DAG). This is what makes reuse correct
    /// ACROSS runs — including after a stop-point edit re-caches an upstream
    /// feature so it looks "clean" on the next full run. The per-run `changed`
    /// wavefront (below) only sees dirtiness WITHIN one run; this sees it across
    /// runs by comparing the input content directly. See `feature_output_version`.
    output_version: u64,
}

thread_local! {
    /// Feature id -> its cached execution, persisted across `execute_history`
    /// calls (same thread = same wasm instance).
    static HISTORY_CACHE: std::cell::RefCell<HashMap<String, CachedFeature>> =
        std::cell::RefCell::new(HashMap::new());
}

/// Free a dead entry's owned resources: each produced handle and its
/// sheet-metal tree. The SINGLE place cached handles die.
fn free_entry(entry: &CachedFeature) {
    for added in &entry.result.added {
        sheet_metal::remove_tree(added.handle);
        crate::free_registered_solid(added.handle);
    }
}

/// Drop the whole cache, freeing every owned handle + tree. Called by the caller on a
/// part/document switch (and by every Rust test for hermeticity).
pub fn clear_history_cache() {
    HISTORY_CACHE.with(|cache| {
        let mut cache = cache.borrow_mut();
        for entry in cache.values() {
            free_entry(entry);
        }
        cache.clear();
    });
    sheet_metal::clear_trees();
}

/// wasm boundary for [`clear_history_cache`].
#[wasm_bindgen]
pub fn clear_history_cache_json() {
    clear_history_cache();
}

/// Stable-enough fingerprint of one descriptor, with its expression-bearing
/// string leaves EVALUATED against `env`. `DefaultHasher` is stable within a
/// process, which is exactly the cache's lifetime.
///
/// This is what makes expression-edit invalidation FINE-GRAINED: an edit to the
/// expression sheet (or the configurator) only moves the fingerprint of a feature
/// whose parameter VALUES actually change, instead of the old coarse
/// `env_fingerprint` that hashed the whole sheet into every feature and thus
/// dirtied everything. The env's variable + configurator values reach a feature
/// only through the string params it evaluates, so hashing those evaluated values
/// captures exactly the feature's dependency on the sheet.
fn descriptor_fingerprint(descriptor: &FeatureDescriptor, env: &Env) -> u64 {
    use std::hash::{Hash, Hasher};
    let mut hasher = std::collections::hash_map::DefaultHasher::new();
    descriptor.feature_type.hash(&mut hasher);
    // Both param sources: `persistent_data` (e.g. sketch coordinates) can hold
    // expression strings too, so it must be evaluated or an expression-driven
    // sketch coord would go stale on a sheet edit.
    hash_evaluated(&descriptor.input_params, env, &mut hasher);
    hash_evaluated(&descriptor.persistent_data, env, &mut hasher);
    hasher.finish()
}

/// Feed a descriptor value into the hasher with every string leaf contributing
/// BOTH its raw text AND, if it parses as an expression, its evaluated value.
///
/// - Raw-ALWAYS keeps verbatim-read strings (ids, `reference_selection` names,
///   enum codes) honest: swapping one for a *different* string that happens to
///   evaluate to the same number still moves the hash.
/// - The evaluated value is what lets an UNRELATED sheet edit leave a
///   numeric-expression field untouched (its raw text `"w"` is unchanged and its
///   value only moves when `w` moves).
/// - A non-expression string simply fails to `eval` and contributes only its raw
///   text. A reference name that collides with a variable evaluates too → at
///   worst a harmless FALSE-dirty when that variable is edited (never a stale
///   reuse; the reference's real dependency rides the consumed-set /
///   `output_version`).
///
/// Object keys are visited in sorted order so the hash is representation-stable.
fn hash_evaluated(value: &serde_json::Value, env: &Env, hasher: &mut impl std::hash::Hasher) {
    use std::hash::Hash;
    match value {
        serde_json::Value::String(text) => {
            0u8.hash(hasher);
            text.hash(hasher);
            // Only attempt the (parsing) eval on strings short enough to be a real
            // expression — `persistent_data` can be large, and the raw text above
            // already covers everything for correctness.
            if text.len() <= 64 {
                if let Ok(number) = env.eval(text) {
                    1u8.hash(hasher);
                    number.to_bits().hash(hasher);
                }
            }
        }
        serde_json::Value::Array(items) => {
            2u8.hash(hasher);
            for item in items {
                hash_evaluated(item, env, hasher);
            }
        }
        serde_json::Value::Object(map) => {
            3u8.hash(hasher);
            let mut keys: Vec<&String> = map.keys().collect();
            keys.sort();
            for key in keys {
                key.hash(hasher);
                hash_evaluated(&map[key], env, hasher);
            }
        }
        other => {
            // Number / bool / null — canonical serialized form.
            4u8.hash(hasher);
            other.to_string().hash(hasher);
        }
    }
}

/// Collect every string in the descriptor (inputParams + persistentData,
/// recursively) that EXACT-matches a name available earlier in the history
/// (directly or with the `:PROFILE` selection alias stripped) — the feature's
/// resolvable reference set.
fn scan_consumed(
    descriptor: &FeatureDescriptor,
    available: &HashMap<String, ()>,
) -> std::collections::BTreeSet<String> {
    fn walk(
        value: &serde_json::Value,
        available: &HashMap<String, ()>,
        out: &mut std::collections::BTreeSet<String>,
    ) {
        match value {
            serde_json::Value::String(text) => {
                let trimmed = text.trim();
                if trimmed.is_empty() {
                    return;
                }
                // Record the CANONICAL produced name, not the alias spelling:
                // a `{sketch}:PROFILE` reference resolves against the profile
                // published under `{sketch}`, and the dirty check intersects
                // this set with produced/changed names — recording the alias
                // verbatim made a sketch edit invisible to its consumers
                // (changed = {"S1"}, consumed = {"S1:PROFILE"}, no overlap).
                if available.contains_key(trimmed) {
                    out.insert(trimmed.to_string());
                } else if let Some(base) = trimmed
                    .strip_suffix(":PROFILE")
                    .filter(|base| available.contains_key(*base))
                {
                    out.insert(base.to_string());
                }
            }
            serde_json::Value::Array(items) => {
                for item in items {
                    walk(item, available, out);
                }
            }
            serde_json::Value::Object(map) => {
                for item in map.values() {
                    walk(item, available, out);
                }
            }
            _ => {}
        }
    }
    let mut out = std::collections::BTreeSet::new();
    walk(&descriptor.input_params, available, &mut out);
    walk(&descriptor.persistent_data, available, &mut out);
    out
}

/// The EFFECTIVE input hash of one feature: its own descriptor `fingerprint`
/// combined with the `output_version` of every name it consumes. Because each
/// producer's `output_version` is itself computed this way, this is a Merkle hash
/// over the whole upstream DAG: it changes iff the feature's own descriptor OR any
/// transitive input changed. A feature is reusable iff its cached `output_version`
/// still equals this — which is exactly "nothing changed for any of its inputs",
/// and is correct across runs (a stop-point edit that re-cached an upstream feature
/// bumps that feature's version, so this consumer's version no longer matches).
///
/// `consumed` is a `BTreeSet`, so the iteration order is deterministic. A consumed
/// name should always have a version (it came from an already-walked producer); a
/// missing one hashes as `0` rather than panicking.
fn feature_output_version(
    fingerprint: u64,
    consumed: &std::collections::BTreeSet<String>,
    name_version: &HashMap<String, u64>,
) -> u64 {
    use std::hash::{Hash, Hasher};
    let mut hasher = std::collections::hash_map::DefaultHasher::new();
    fingerprint.hash(&mut hasher);
    for name in consumed {
        name.hash(&mut hasher);
        name_version.get(name).copied().unwrap_or(0).hash(&mut hasher);
    }
    hasher.finish()
}

/// Every name a result adds to the scene: solid/face/edge names plus the
/// profile/frame/axis/path names from the side-channels.
fn produced_names(result: &FeatureResult) -> Vec<String> {
    let mut names = Vec::new();
    for added in &result.added {
        names.push(added.name.clone());
        names.extend(added.face_names.iter().map(|(_, name)| name.clone()));
        names.extend(added.edge_names.iter().map(|(_, name)| name.clone()));
    }
    names.extend(result.profiles.iter().map(|(name, _)| name.clone()));
    names.extend(result.frames.iter().map(|(name, _)| name.clone()));
    names.extend(result.axes.iter().map(|(name, _)| name.clone()));
    names.extend(result.paths.iter().map(|(name, _)| name.clone()));
    names.extend(result.points.iter().map(|(name, _)| name.clone()));
    names
}

// ===========================================================================
// The history loop
// ===========================================================================

/// Run a whole feature history incrementally: build the expression env once,
/// then walk the ordered features. A CLEAN feature (see the cache section above)
/// replays its cached result; a DIRTY one re-executes (its old outputs are freed
/// first). On a feature error, record it and HALT (abort-on-error);
/// errored results are never cached. Never panics.
pub fn execute_history(request: &HistoryRequest) -> HistoryResult {
    let env = Env::build(&request.expressions, &request.configurator)
        .unwrap_or_else(Env::poisoned);

    // Entries whose feature was DELETED from the history die now. Their
    // consumers go dirty via the consumed-set equality check (the vanished names
    // drop out of the available set), so no changed-seeding is needed here.
    let request_ids: HashMap<String, ()> = request
        .features
        .iter()
        .map(|descriptor| (extract_id(&descriptor.input_params), ()))
        .collect();
    HISTORY_CACHE.with(|cache| {
        let mut cache = cache.borrow_mut();
        cache.retain(|id, entry| {
            let keep = request_ids.contains_key(id);
            if !keep {
                free_entry(entry);
            }
            keep
        });
    });

    let mut scene = SceneMap::default();
    let mut results = Vec::with_capacity(request.features.len());
    // Per-feature wall-clock timing, in run order (`web_time::Instant` — plain
    // `std::time::Instant` traps 'unreachable' on wasm32).
    let mut timings: Vec<(String, f64)> = Vec::with_capacity(request.features.len());
    // Names whose content changed this run (produced/removed by any re-executed
    // or invalidated feature) — the dirty wavefront.
    let mut changed: HashMap<String, ()> = HashMap::new();
    // Names available for reference so far this run (from clean AND dirty
    // features alike).
    let mut available: HashMap<String, ()> = HashMap::new();
    // Each available name -> the `output_version` of the feature that produced it
    // this run (walk order: a boolean that reuses its target name overwrites the
    // producer's version, so consumers depend on the boolean's version). Feeds
    // `feature_output_version` so cross-run reuse is decided by input CONTENT.
    let mut name_version: HashMap<String, u64> = HashMap::new();
    let mut seen_ids: HashMap<String, ()> = HashMap::new();

    for descriptor in &request.features {
        let id = extract_id(&descriptor.input_params);
        // Editor stop-point: BEFORE this feature — the rest of the request is
        // parse-only (their cache entries were already retained above).
        if request.stop_before_id.as_deref() == Some(id.as_str()) {
            break;
        }
        // An empty or duplicated id cannot key a cache entry: execute plainly,
        // touching no cached state (a duplicate must not free the entry its
        // first occurrence just wrote).
        let cacheable = !id.is_empty() && seen_ids.insert(id.clone(), ()).is_none();
        let fingerprint = descriptor_fingerprint(descriptor, &env);
        let consumed = scan_consumed(descriptor, &available);
        // Merkle input hash over this feature + its consumed producers' versions.
        // Computed for EVERY feature (cacheable or not) so its produced names can
        // publish a version for downstream consumers.
        let output_version = feature_output_version(fingerprint, &consumed, &name_version);

        let clean = cacheable
            && HISTORY_CACHE.with(|cache| {
                cache.borrow().get(&id).is_some_and(|entry| {
                    entry.fingerprint == fingerprint
                        && entry.consumed == consumed
                        && consumed.iter().all(|name| !changed.contains_key(name))
                        // The cross-run clause: reuse only if the effective input
                        // content is byte-identical to what this entry was built
                        // from. Subsumes the three clauses above (they are hashed
                        // in); kept additively so the diff stays minimal and the
                        // handle-ownership / blast-radius paths are untouched.
                        && entry.output_version == output_version
                })
            });

        if clean {
            let mut result =
                HISTORY_CACHE.with(|cache| cache.borrow().get(&id).unwrap().result.clone());
            result.reused = true;
            scene.apply(&result);
            for name in produced_names(&result) {
                available.insert(name.clone(), ());
                // A clean feature's current version equals its cached one; publish
                // it so downstream consumers hash the SAME value they cached against.
                name_version.insert(name, output_version);
            }
            results.push(result);
            timings.push((id.clone(), 0.0)); // replayed, not re-executed
            // Editor stop-point: AFTER this feature.
            if request.stop_at_id.as_deref() == Some(id.as_str()) {
                break;
            }
            continue;
        }

        // Dirty: the old entry (if any) dies — its blast radius joins `changed`.
        if cacheable {
            if let Some(old) = HISTORY_CACHE.with(|cache| cache.borrow_mut().remove(&id)) {
                free_entry(&old);
                changed.extend(old.touched.iter().map(|(name, _)| (name.clone(), ())));
            }
        }

        let feat_start = web_time::Instant::now();
        let result = execute_feature(descriptor, &env, &scene);
        timings.push((id.clone(), feat_start.elapsed().as_secs_f64() * 1000.0));
        let halt = result.error.is_some();
        scene.apply(&result);

        // Kernel-owned topology metadata: every face/edge this feature produced
        // records its producer (the `_seedSourceFeatureMetadata` step, moved here).
        // Non-overwriting — faces propagated through a boolean keep their
        // original sourceFeatureId, matching the established seed semantics.
        if !id.is_empty() {
            let mut seed = serde_json::Map::new();
            seed.insert("sourceFeatureId".into(), serde_json::Value::String(id.clone()));
            for added in &result.added {
                for (_, face_name) in &added.face_names {
                    scene_metadata::merge_record(face_name, &seed, false);
                }
                for (_, edge_name) in &added.edge_names {
                    scene_metadata::merge_record(edge_name, &seed, false);
                }
            }
        }

        let produced = produced_names(&result);
        for name in &produced {
            available.insert(name.clone(), ());
            changed.insert(name.clone(), ());
            // Publish this run's version for the name. Runs for cacheable AND
            // non-cacheable (empty/duplicate id) features alike — a non-cacheable
            // feature has no cache entry but its outputs still version their
            // downstream consumers correctly.
            name_version.insert(name.clone(), output_version);
        }
        for name in &result.removed {
            changed.insert(name.clone(), ());
        }

        if cacheable && !halt {
            let mut touched: HashMap<String, ()> =
                produced.into_iter().map(|name| (name, ())).collect();
            touched.extend(result.removed.iter().map(|name| (name.clone(), ())));
            HISTORY_CACHE.with(|cache| {
                cache.borrow_mut().insert(
                    id.clone(),
                    CachedFeature {
                        fingerprint,
                        result: result.clone(),
                        consumed,
                        touched,
                        output_version,
                    },
                );
            });
        }

        results.push(result);
        if halt {
            break;
        }
        // Editor stop-point: AFTER this feature.
        if request.stop_at_id.as_deref() == Some(id.as_str()) {
            break;
        }
    }
    HistoryResult { results, timings }
}

// ===========================================================================
// wasm boundary
// ===========================================================================

/// Deserialize a history request, run it, and serialize the per-feature results.
/// The handles in the result are `u32`s the caller tessellates / pulls names
/// from via the existing `*_handle` wasm exports.
#[wasm_bindgen]
pub fn execute_history_json(request_json: &str) -> Result<String, JsValue> {
    let request: HistoryRequest = serde_json::from_str(request_json)
        .map_err(|error| JsValue::from_str(&format!("execute_history_json: bad request: {error}")))?;
    let result = execute_history(&request);
    serde_json::to_string(&result).map_err(|error| JsValue::from_str(&error.to_string()))
}

#[cfg(test)]
mod tests;