json_eval_rs/jsoneval/

subform_methods.rs

// Subform methods for isolated array field evaluation

use super::JSONEval;
use crate::jsoneval::cancellation::CancellationToken;
use crate::jsoneval::eval_data::EvalData;
use crate::jsoneval::types::{ResolvedLayoutResult, ReturnFormat};
use serde_json::Value;

/// Decomposes a subform path that may optionally include a trailing item index,
/// and normalizes the base portion to the canonical schema-pointer key used in the
/// subform registry (e.g. `"#/illustration/properties/product_benefit/properties/riders"`).
///
/// Accepted formats for the **base** portion:
/// - Schema pointer:    `"#/illustration/properties/product_benefit/properties/riders"`
/// - Raw JSON pointer:  `"/illustration/properties/product_benefit/properties/riders"`
/// - Dot notation:      `"illustration.product_benefit.riders"`
///
/// Accepted formats for the **index** suffix (stripped before lookup):
/// - Trailing dot-index:     `"…riders.1"`
/// - Trailing slash-index:   `"…riders/1"`
/// - Bracket array index:    `"…riders[1]"` or `"…riders[1]."`
///
/// Returns `(canonical_base_path, optional_index)`.
fn resolve_subform_path(path: &str) -> (String, Option<usize>) {
    // --- Step 1: strip a trailing bracket array index, e.g. "riders[2]" or "riders[2]."
    let path = path.trim_end_matches('.');
    let (path, bracket_idx) = if let Some(bracket_start) = path.rfind('[') {
        let after = &path[bracket_start + 1..];
        if let Some(bracket_end) = after.find(']') {
            let idx_str = &after[..bracket_end];
            if let Ok(idx) = idx_str.parse::<usize>() {
                // strip everything from '[' onward (including any trailing '.')
                let base = path[..bracket_start].trim_end_matches('.');
                (base, Some(idx))
            } else {
                (path, None)
            }
        } else {
            (path, None)
        }
    } else {
        (path, None)
    };

    // --- Step 2: strip a trailing numeric segment (dot or slash separated)
    let (base_raw, trailing_idx) = if bracket_idx.is_none() {
        // Check dot-notation trailing index: "foo.bar.2"
        if let Some(dot_pos) = path.rfind('.') {
            let suffix = &path[dot_pos + 1..];
            if let Ok(idx) = suffix.parse::<usize>() {
                (&path[..dot_pos], Some(idx))
            } else {
                (path, None)
            }
        }
        // Check JSON-pointer trailing index: "#/foo/bar/0" or "/foo/bar/0"
        else if let Some(slash_pos) = path.rfind('/') {
            let suffix = &path[slash_pos + 1..];
            if let Ok(idx) = suffix.parse::<usize>() {
                (&path[..slash_pos], Some(idx))
            } else {
                (path, None)
            }
        } else {
            (path, None)
        }
    } else {
        (path, None)
    };

    let final_idx = bracket_idx.or(trailing_idx);

    // --- Step 3: normalize base_raw to a canonical schema pointer
    let canonical = normalize_to_subform_key(base_raw);

    (canonical, final_idx)
}

/// Normalize any path format to the canonical subform registry key.
///
/// The registry stores keys as `"#/field/properties/subfield/properties/…"` — exactly
/// as produced by the schema `walk()` function. This function converts all supported
/// formats into that form.
fn normalize_to_subform_key(path: &str) -> String {
    // Already a schema pointer — return as-is
    if path.starts_with("#/") {
        return path.to_string();
    }

    // Raw JSON pointer "/foo/properties/bar" → prefix with '#'
    if path.starts_with('/') {
        return format!("#{}", path);
    }

    // Dot-notation: "illustration.product_benefit.riders"
    // → "#/illustration/properties/product_benefit/properties/riders"
    crate::jsoneval::path_utils::dot_notation_to_schema_pointer(path)
}

impl JSONEval {
    /// Resolves the subform path, allowing aliases like "riders" to match the full
    /// schema pointer "#/illustration/properties/product_benefit/properties/riders".
    /// This ensures alias paths and full paths share the same underlying subform store and cache.
    pub(crate) fn resolve_subform_path_alias(&self, path: &str) -> (String, Option<usize>) {
        let (mut canonical, idx) = resolve_subform_path(path);

        if !self.subforms.contains_key(&canonical) {
            let search_suffix = if canonical.starts_with("#/") {
                format!("/properties/{}", &canonical[2..])
            } else {
                format!("/properties/{}", canonical)
            };

            for k in self.subforms.keys() {
                if k.ends_with(&search_suffix) || k == &canonical {
                    canonical = k.to_string();
                    break;
                }
            }
        }

        (canonical, idx)
    }

    /// Execute `f` on the subform at `base_path[idx]` with the parent cache swapped in.
    ///
    /// Lifecycle:
    /// 1. Set `data_value` + `context_value` on the subform's `eval_data`.
    /// 2. Compute item-level diff for `field_key` → bump `subform_caches[idx].data_versions`.
    /// 3. `mem::take` parent cache → set `active_item_index = Some(idx)` → swap into subform.
    /// 4. Execute `f(subform)` → collect result.
    /// 5. Swap parent cache back out → restore `self.eval_cache`.
    ///
    /// This ensures all three operations (evaluate / validate / evaluate_dependents)
    /// share parent-form Tier-2 cache entries, without duplicating the swap boilerplate.
    fn with_item_cache_swap<F, T>(
        &mut self,
        base_path: &str,
        idx: usize,
        data_value: Value,
        context_value: Value,
        f: F,
    ) -> Result<T, String>
    where
        F: FnOnce(&mut JSONEval) -> Result<T, String>,
    {
        let original_field_key = base_path
            .split('/')
            .next_back()
            .unwrap_or(base_path)
            .to_string();

        let schema_pointer = if base_path.starts_with("#/") {
            &base_path[1..]
        } else if base_path.starts_with('#') {
            &base_path[1..]
        } else {
            base_path
        };

        let root_key =
            crate::jsoneval::path_utils::get_value_by_pointer(&self.schema, schema_pointer)
                .and_then(|node| node.get("itemsRootKey"))
                .and_then(|v| v.as_str())
                .unwrap_or(&original_field_key)
                .to_string();

        let array_path =
            crate::jsoneval::path_utils::schema_path_to_data_pointer(base_path).into_owned();
        let item_path = format!("{}/{}", array_path, idx);
        let full_parent_payload = data_value.pointer(&array_path).is_some();
        let payload_has_parent_context = data_value
            .as_object()
            .map(|map| map.keys().any(|key| key != &root_key))
            .unwrap_or(false);

        // Normalize both public payload shapes into one active item before scope setup.
        let normalized_item = if full_parent_payload {
            data_value
                .pointer(&item_path)
                .cloned()
                .or_else(|| data_value.get(&root_key).cloned())
        } else {
            data_value.get(&root_key).cloned()
        }
        .ok_or_else(|| {
            format!(
                "Invalid indexed subform payload for {base_path}[{idx}]: expected active item at {item_path} or wrapper root {root_key}"
            )
        })?;

        // Prepare item data and cache state.
        let (old_item_snapshot, new_item_val, subform_item_cache_opt) = {
            let subform = self
                .subforms
                .get_mut(base_path)
                .ok_or_else(|| format!("Subform not found: {}", base_path))?;

            let old_item_snapshot = subform
                .eval_cache
                .subform_caches
                .get(&idx)
                .map(|c| c.item_snapshot.clone())
                .unwrap_or(Value::Null);

            // Merge parent payload when available.
            let mut scoped_data = EvalData::new(self.eval_data.snapshot_data_clone());
            if full_parent_payload || payload_has_parent_context {
                scoped_data.replace_data_and_context(data_value.clone(), context_value.clone());
            }
            scoped_data.set(&item_path, normalized_item.clone());
            let canonical_parent = scoped_data.snapshot_data_clone();
            let scope = crate::jsoneval::subform_scope::SubformScope::new(
                base_path,
                &array_path,
                Some(idx),
            );
            let mut scoped_view = scope.evaluation_view(&canonical_parent);
            if let Some(view) = scoped_view.as_object_mut() {
                view.insert("$context".to_string(), context_value.clone());
            }
            subform.eval_data = EvalData::new(scoped_view);
            let new_item_val = normalized_item.clone();

            // Move item cache into parent cache.
            let existing = subform.eval_cache.subform_caches.remove(&idx);
            (old_item_snapshot, new_item_val, existing)
        }; // subform borrow released here

        // Fall back to parent item snapshot.
        let parent_item = self.eval_data.get(&item_path).cloned();
        let old_item_snapshot = if old_item_snapshot == Value::Null {
            parent_item.clone().unwrap_or(Value::Null)
        } else {
            old_item_snapshot
        };

        // Parent data determines whether item is new.
        let is_new_item = parent_item.is_none();

        let mut parent_cache = std::mem::take(&mut self.eval_cache);
        if full_parent_payload {
            let old_parent_data = self.eval_data.snapshot_data_clone();
            self.eval_data
                .replace_data_and_context(data_value.clone(), context_value.clone());
            let new_parent_data = self.eval_data.snapshot_data_clone();
            crate::jsoneval::eval_cache::diff_and_update_versions(
                &mut parent_cache.data_versions,
                "",
                &old_parent_data,
                &new_parent_data,
                "sync_full_subform_payload",
            );
        }
        parent_cache.ensure_active_item_cache(idx);

        if let Some(c) = parent_cache.subform_caches.get_mut(&idx) {
            // Merge parent versions without item-local paths.
            c.data_versions
                .merge_excluding_prefix(&parent_cache.data_versions, &format!("/{root_key}/"));
            c.data_versions
                .merge_from_params(&parent_cache.params_versions);

            // Merge item version history before diffing.
            if let Some(subform_item_cache) = &subform_item_cache_opt {
                c.data_versions
                    .merge_from(&subform_item_cache.data_versions);
            }
        }

        // Keep baseline to detect new version bumps.
        let pre_diff_item_versions = parent_cache
            .subform_caches
            .get(&idx)
            .map(|c| c.data_versions.clone());

        if let Some(c) = parent_cache.subform_caches.get_mut(&idx) {
            // Diff only the item field to find what changed (skips the 5 MB parent tree).
            crate::jsoneval::eval_cache::diff_and_update_versions(
                &mut c.data_versions,
                &format!("/{}", root_key),
                &old_item_snapshot,
                &new_item_val,
                "with_item_cache_swap_diff_and_update_versions",
            );
            c.item_snapshot = new_item_val.clone();
        }

        // Propagate new item changes to parent T2 versions.
        {
            let item_field_prefix = format!("/{}/", root_key);
            if let (Some(ref pre), Some(c)) = (
                &pre_diff_item_versions,
                parent_cache.subform_caches.get(&idx),
            ) {
                let newly_bumped: Vec<String> = c
                    .data_versions
                    .versions()
                    .filter(|(k, &v)| k.starts_with(&item_field_prefix) && v > pre.get(k))
                    .map(|(k, _)| k.to_string())
                    .collect();
                if !newly_bumped.is_empty() {
                    for k in newly_bumped {
                        parent_cache
                            .data_versions
                            .bump(&k, "propagate_newly_bumped");
                    }
                    parent_cache.eval_generation += 1;
                }
            }
        }

        parent_cache.active_item_index = Some(idx);

        // Restore valid item cache entries.
        if let Some(subform_item_cache) = subform_item_cache_opt {
            if let Some(c) = parent_cache.subform_caches.get_mut(&idx) {
                // Merge historical item versions before validation.
                let current_dv = c.data_versions.clone();
                for (k, v) in subform_item_cache.entries {
                    // Skip if entry already exists (parent-form run may have added a fresher result).
                    if c.entries.contains_key(&k) {
                        continue;
                    }
                    // Validate all dep versions against the current item data_versions.
                    let still_valid = v.dep_versions.iter().all(|(dep_path, &cached_ver)| {
                        let current_ver = if dep_path.starts_with("/$params") {
                            parent_cache.params_versions.get(dep_path)
                        } else {
                            current_dv.get(dep_path)
                        };
                        current_ver == cached_ver
                    });
                    if still_valid {
                        c.entries.insert(k, v);
                    }
                }
            }
        }

        // Sync changed item into parent data.
        let current_at_item_path = self.eval_data.get(&item_path).cloned();
        if current_at_item_path.as_ref() != Some(&new_item_val) {
            self.eval_data.set(&item_path, new_item_val.clone());
            if is_new_item {
                parent_cache.bump_data_version(&array_path);
            }
        }

        // Refresh affected $params tables after new item changes.
        let field_prefix = format!("/{}/", root_key);
        let item_paths_bumped = match &pre_diff_item_versions {
            None => {
                // No pre-diff snapshot = cache slot was just created, treat as new
                parent_cache
                    .subform_caches
                    .get(&idx)
                    .map(|c| c.data_versions.any_bumped_with_prefix(&field_prefix))
                    .unwrap_or(false)
            }
            Some(pre) => {
                // Only count bumps that occurred during this specific diff pass
                parent_cache
                    .subform_caches
                    .get(&idx)
                    .map(|c| {
                        c.data_versions
                            .any_newly_bumped_with_prefix(&field_prefix, pre)
                    })
                    .unwrap_or(false)
            }
        };

        if is_new_item || item_paths_bumped {
            // Collect newly changed item paths.
            let newly_bumped_paths: Option<Vec<String>> = if item_paths_bumped {
                let paths = pre_diff_item_versions.as_ref().and_then(|pre| {
                    parent_cache.subform_caches.get(&idx).map(|c| {
                        c.data_versions
                            .versions()
                            .filter(|(k, &v)| k.starts_with(&field_prefix) && v > pre.get(k))
                            .map(|(k, _)| {
                                // Convert data path to schema path.
                                let sub = k.trim_start_matches(&field_prefix);
                                format!("#/{}/properties/{}", root_key, sub)
                            })
                            .collect::<Vec<_>>()
                    })
                });
                paths
            } else {
                None
            };

            let params_table_keys: Vec<String> = self
                .table_metadata
                .keys()
                .filter(|k| k.starts_with("#/$params"))
                .filter(|k| {
                    if is_new_item {
                        return true; // new rider: invalidate all tables
                    }
                    // Invalidate tables with changed dependencies.
                    let Some(ref bumped) = newly_bumped_paths else {
                        return true;
                    };
                    if bumped.is_empty() {
                        return false;
                    }
                    self.dependencies
                        .get(*k)
                        .map(|deps| {
                            deps.iter().any(|dep| {
                                bumped
                                    .iter()
                                    .any(|b| dep == b || dep.starts_with(b.as_str()))
                            })
                        })
                        .unwrap_or(false)
                })
                .cloned()
                .collect();
            if !params_table_keys.is_empty() {
                parent_cache.invalidate_params_tables_for_item(idx, &params_table_keys);

                let eval_data_snapshot = self.eval_data.snapshot_data();
                for key in &params_table_keys {
                    // Item-dependent tables run in subform scope.
                    let depends_on_subform_item = if let Some(deps) = self.dependencies.get(key) {
                        let subform_dep_prefix = format!("#/{}/properties/", root_key);
                        let subform_dep_prefix_short = format!("#/{}/", root_key);
                        deps.iter().any(|dep| {
                            dep.starts_with(&subform_dep_prefix)
                                || dep.starts_with(&subform_dep_prefix_short)
                        })
                    } else {
                        false
                    };

                    if depends_on_subform_item {
                        continue;
                    }

                    // Evaluate the table using parent's updated data
                    if let Ok((arc_val, external_deps_opt)) =
                        crate::jsoneval::table_evaluate::evaluate_table(
                            self,
                            key,
                            &EvalData::from_arc(std::sync::Arc::clone(&eval_data_snapshot)),
                            None,
                        )
                    {
                        if crate::utils::is_debug_cache_enabled() {
                            let rows_len = arc_val.as_array().map(|a| a.len()).unwrap_or(0);
                            println!("PARENT EVALUATED TABLE {} -> {} rows", key, rows_len);
                        }

                        if let Some(external_deps) = external_deps_opt {
                            // Store parent result in T2.
                            parent_cache.active_item_index = None;
                            parent_cache.store_cache_arc(key, &external_deps, arc_val);
                            parent_cache.active_item_index = Some(idx);
                        }
                    } else {
                        if crate::utils::is_debug_cache_enabled() {
                            println!("PARENT EVALUATED TABLE {} -> ERROR", key);
                        }
                    }
                }
            }
        }

        // Step 3: swap parent cache into subform so Tier 1 + Tier 2 entries are visible.
        {
            let subform = self.subforms.get_mut(base_path).unwrap();
            std::mem::swap(&mut subform.eval_cache, &mut parent_cache);
        }

        // Step 4: run the caller-supplied operation.
        let result = {
            let subform = self.subforms.get_mut(base_path).unwrap();
            f(subform)
        };

        // Step 5: restore parent cache.
        {
            let subform = self.subforms.get_mut(base_path).unwrap();
            std::mem::swap(&mut subform.eval_cache, &mut parent_cache);
        }
        parent_cache.active_item_index = None;
        self.eval_cache = parent_cache;

        // Persist item cache and evaluated schema.
        {
            let subform = self.subforms.get_mut(base_path).unwrap();
            if let Some(item_cache) = self.eval_cache.subform_caches.get_mut(&idx) {
                item_cache.evaluated_schema = Some(subform.evaluated_schema.clone());
                subform
                    .eval_cache
                    .subform_caches
                    .insert(idx, item_cache.clone());
            }
        }

        result
    }

    /// Evaluate a subform identified by `subform_path`.
    ///
    /// The path may include a trailing item index to bind the evaluation to a specific
    /// array element and enable the two-tier cache-swap strategy automatically:
    ///
    /// ```text
    /// // Evaluate riders item 1 with index-aware cache
    /// eval.evaluate_subform("illustration.product_benefit.riders.1", data, ctx, None, None)?;
    /// ```
    ///
    /// Without a trailing index, the subform is evaluated in isolation (no cache swap).
    pub fn evaluate_subform(
        &mut self,
        subform_path: &str,
        data: &str,
        context: Option<&str>,
        paths: Option<&[String]>,
        token: Option<&CancellationToken>,
    ) -> Result<(), String> {
        let (base_path, idx_opt) = self.resolve_subform_path_alias(subform_path);
        if let Some(idx) = idx_opt {
            self.evaluate_subform_item(&base_path, idx, data, context, paths, token)
        } else {
            let subform = self
                .subforms
                .get_mut(base_path.as_ref() as &str)
                .ok_or_else(|| format!("Subform not found: {}", base_path))?;
            subform.evaluate(data, context, paths, token)
        }
    }

    /// Internal: evaluate a single subform item at `idx` using the cache-swap strategy.
    fn evaluate_subform_item(
        &mut self,
        base_path: &str,
        idx: usize,
        data: &str,
        context: Option<&str>,
        paths: Option<&[String]>,
        token: Option<&CancellationToken>,
    ) -> Result<(), String> {
        let data_value = crate::jsoneval::json_parser::parse_json_str(data)
            .map_err(|e| format!("Failed to parse subform data: {}", e))?;
        let context_value = if let Some(ctx) = context {
            crate::jsoneval::json_parser::parse_json_str(ctx)
                .map_err(|e| format!("Failed to parse subform context: {}", e))?
        } else {
            Value::Object(serde_json::Map::new())
        };

        self.with_item_cache_swap(base_path, idx, data_value, context_value, |sf| {
            // Match main-form lifecycle: resolve visibility, hydrate missing visible static
            // defaults and their dependents, then re-evaluate only when data was written.
            sf.evaluate_internal_pre_diffed(paths, token)?;
            if sf.apply_visible_static_defaults_with_dependents(token)? {
                sf.evaluate_internal_pre_diffed(paths, token)?;
            }
            Ok(())
        })
    }

    /// Validate subform data against its schema rules.
    ///
    /// Supports the same trailing-index path syntax as `evaluate_subform`. When an index
    /// is present the parent cache is swapped in first, ensuring rule evaluations that
    /// depend on `$params` tables share already-computed parent-form results.
    pub fn validate_subform(
        &mut self,
        subform_path: &str,
        data: &str,
        context: Option<&str>,
        paths: Option<&[String]>,
        token: Option<&CancellationToken>,
        validate_readonly: Option<bool>,
    ) -> Result<crate::ValidationResult, String> {
        let (base_path, idx_opt) = self.resolve_subform_path_alias(subform_path);
        if let Some(idx) = idx_opt {
            let data_value = crate::jsoneval::json_parser::parse_json_str(data)
                .map_err(|e| format!("Failed to parse subform data: {}", e))?;
            let context_value = if let Some(ctx) = context {
                crate::jsoneval::json_parser::parse_json_str(ctx)
                    .map_err(|e| format!("Failed to parse subform context: {}", e))?
            } else {
                Value::Object(serde_json::Map::new())
            };
            let data_for_validation = data_value.clone();
            self.with_item_cache_swap(
                base_path.as_ref(),
                idx,
                data_value,
                context_value,
                move |sf| {
                    // Warm the evaluation cache before running rule checks.
                    sf.evaluate_internal_pre_diffed(paths, token)?;
                    sf.validate_pre_set(data_for_validation, paths, token, validate_readonly)
                },
            )
        } else {
            let subform = self
                .subforms
                .get_mut(base_path.as_ref() as &str)
                .ok_or_else(|| format!("Subform not found: {}", base_path))?;
            subform.validate(data, context, paths, token, validate_readonly)
        }
    }

    /// Evaluate dependents in a subform when a field changes.
    ///
    /// Supports the same trailing-index path syntax as `evaluate_subform`. When an index
    /// is present the parent cache is swapped in, so dependent evaluation runs with
    /// Tier-2 entries visible and item-scoped version bumps propagate to `eval_generation`.
    pub fn evaluate_dependents_subform(
        &mut self,
        subform_path: &str,
        changed_paths: &[String],
        data: Option<&str>,
        context: Option<&str>,
        re_evaluate: bool,
        token: Option<&CancellationToken>,
        canceled_paths: Option<&mut Vec<String>>,
        include_subforms: bool,
    ) -> Result<Value, String> {
        let (base_path, idx_opt) = self.resolve_subform_path_alias(subform_path);
        if let Some(idx) = idx_opt {
            // Parse or snapshot data for the swap / diff computation.
            let (data_value, context_value) = if let Some(data_str) = data {
                let dv = crate::jsoneval::json_parser::parse_json_str(data_str)
                    .map_err(|e| format!("Failed to parse subform data: {}", e))?;
                let cv = if let Some(ctx) = context {
                    crate::jsoneval::json_parser::parse_json_str(ctx)
                        .map_err(|e| format!("Failed to parse subform context: {}", e))?
                } else {
                    Value::Object(serde_json::Map::new())
                };
                (dv, cv)
            } else {
                // No new data provided — snapshot current subform state so diff is a no-op.
                let subform = self
                    .subforms
                    .get(base_path.as_ref() as &str)
                    .ok_or_else(|| format!("Subform not found: {}", base_path))?;
                let dv = subform.eval_data.snapshot_data_clone();
                (dv, Value::Object(serde_json::Map::new()))
            };
            let changes = self.with_item_cache_swap(
                base_path.as_ref(),
                idx,
                data_value,
                context_value,
                |sf| {
                    // Data is already set by with_item_cache_swap; pass None to avoid re-parsing.
                    sf.evaluate_dependents(
                        changed_paths,
                        None,
                        None,
                        re_evaluate,
                        token,
                        None,
                        include_subforms,
                    )
                },
            )?;
            // Public indexed-subform patches retain subform-local refs so callers can apply
            // them directly to their `{ riders: item }` editing payload. Internal dependent
            // evaluation stays canonical; only active-item result refs are projected here.
            let subform_dot_path =
                crate::jsoneval::path_utils::pointer_to_dot_notation(base_path.as_ref())
                    .replace(".properties.", ".");
            let canonical_prefix = format!("{subform_dot_path}.{idx}");
            let root_key = base_path.rsplit('/').next().unwrap_or(base_path.as_ref());
            let changes = match changes {
                Value::Array(changes) => Value::Array(
                    changes
                        .into_iter()
                        .map(|change| {
                            let Some(change_map) = change.as_object() else {
                                return change;
                            };
                            let Some(Value::String(reference)) = change_map.get("$ref") else {
                                return change;
                            };
                            let Some(suffix) = reference.strip_prefix(&canonical_prefix) else {
                                return change;
                            };
                            if !suffix.is_empty() && !suffix.starts_with('.') {
                                return change;
                            }
                            let mut mapped = change_map.clone();
                            mapped.insert(
                                "$ref".to_string(),
                                Value::String(format!("{root_key}{suffix}")),
                            );
                            Value::Object(mapped)
                        })
                        .collect(),
                ),
                value => value,
            };
            Ok(changes)
        } else {
            let subform = self
                .subforms
                .get_mut(base_path.as_ref() as &str)
                .ok_or_else(|| format!("Subform not found: {}", base_path))?;
            subform.evaluate_dependents(
                changed_paths,
                data,
                context,
                re_evaluate,
                token,
                canceled_paths,
                include_subforms,
            )
        }
    }

    /// Resolve layout for subform, returning overlay entries.
    pub fn resolve_layout_subform(
        &mut self,
        subform_path: &str,
        evaluate: bool,
    ) -> Result<ResolvedLayoutResult, String> {
        let (base_path, _) = self.resolve_subform_path_alias(subform_path);
        let subform = self
            .subforms
            .get_mut(base_path.as_ref() as &str)
            .ok_or_else(|| format!("Subform not found: {}", base_path))?;
        subform.resolve_layout(evaluate)
    }

    /// Get evaluated schema from subform.
    pub fn get_evaluated_schema_subform(&mut self, subform_path: &str) -> Value {
        let (base_path, idx_opt) = self.resolve_subform_path_alias(subform_path);

        if let Some(idx) = idx_opt {
            if let Some(schema) = self
                .eval_cache
                .subform_caches
                .get(&idx)
                .and_then(|c| c.evaluated_schema.clone())
            {
                return schema;
            }
            if let Some(subform) = self.subforms.get_mut(base_path.as_ref() as &str) {
                subform.get_evaluated_schema()
            } else {
                Value::Null
            }
        } else if let Some(subform) = self.subforms.get_mut(base_path.as_ref() as &str) {
            subform.get_evaluated_schema()
        } else {
            Value::Null
        }
    }

    /// Get schema value from subform in nested object format (all .value fields).
    ///
    /// Indexed evaluation stores an absolute parent-array wrapper in the subform's
    /// eval data for cross-item formulas. This endpoint exposes only fields declared
    /// by its isolated subform schema, never that implementation wrapper.
    pub fn get_schema_value_subform(&mut self, subform_path: &str) -> Value {
        let (base_path, _) = self.resolve_subform_path_alias(subform_path);
        let Some(subform) = self.subforms.get_mut(base_path.as_ref() as &str) else {
            return Value::Null;
        };

        let values = subform.get_schema_value();
        let Some(values) = values.as_object() else {
            return values;
        };

        let schema_root_keys: Vec<&str> = subform
            .schema
            .as_object()
            .into_iter()
            .flat_map(|schema| schema.keys())
            .filter(|key| !key.starts_with('$'))
            .map(String::as_str)
            .collect();

        Value::Object(
            schema_root_keys
                .into_iter()
                .filter_map(|key| {
                    values
                        .get(key)
                        .cloned()
                        .map(|value| (key.to_string(), value))
                })
                .collect(),
        )
    }

    /// Get schema values from subform as a flat array of path-value pairs.
    pub fn get_schema_value_array_subform(&self, subform_path: &str) -> Value {
        let (base_path, _) = self.resolve_subform_path_alias(subform_path);
        if let Some(subform) = self.subforms.get(base_path.as_ref() as &str) {
            subform.get_schema_value_array()
        } else {
            Value::Array(vec![])
        }
    }

    /// Get schema values from subform as a flat object with dotted path keys.
    pub fn get_schema_value_object_subform(&self, subform_path: &str) -> Value {
        let (base_path, _) = self.resolve_subform_path_alias(subform_path);
        if let Some(subform) = self.subforms.get(base_path.as_ref() as &str) {
            subform.get_schema_value_object()
        } else {
            Value::Object(serde_json::Map::new())
        }
    }

    /// Get evaluated schema without $params from subform.
    pub fn get_evaluated_schema_without_params_subform(&mut self, subform_path: &str) -> Value {
        let (base_path, _) = self.resolve_subform_path_alias(subform_path);
        if let Some(subform) = self.subforms.get_mut(base_path.as_ref() as &str) {
            subform.get_evaluated_schema_without_params()
        } else {
            Value::Null
        }
    }

    /// Get evaluated schema by specific path from subform.
    pub fn get_evaluated_schema_by_path_subform(
        &mut self,
        subform_path: &str,
        schema_path: &str,
    ) -> Option<Value> {
        let (base_path, _) = self.resolve_subform_path_alias(subform_path);
        self.subforms.get_mut(base_path.as_ref() as &str).map(|sf| {
            sf.get_evaluated_schema_by_paths(&[schema_path.to_string()], Some(ReturnFormat::Nested))
        })
    }

    /// Get evaluated schema by multiple paths from subform.
    pub fn get_evaluated_schema_by_paths_subform(
        &mut self,
        subform_path: &str,
        schema_paths: &[String],
        format: Option<crate::ReturnFormat>,
    ) -> Value {
        let (base_path, _) = self.resolve_subform_path_alias(subform_path);
        if let Some(subform) = self.subforms.get_mut(base_path.as_ref() as &str) {
            subform.get_evaluated_schema_by_paths(
                schema_paths,
                Some(format.unwrap_or(ReturnFormat::Flat)),
            )
        } else {
            match format.unwrap_or_default() {
                crate::ReturnFormat::Array => Value::Array(vec![]),
                _ => Value::Object(serde_json::Map::new()),
            }
        }
    }

    /// Get schema by specific path from subform.
    pub fn get_schema_by_path_subform(
        &self,
        subform_path: &str,
        schema_path: &str,
    ) -> Option<Value> {
        let (base_path, _) = self.resolve_subform_path_alias(subform_path);
        self.subforms
            .get(base_path.as_ref() as &str)
            .and_then(|sf| sf.get_schema_by_path(schema_path))
    }

    /// Get schema by multiple paths from subform.
    pub fn get_schema_by_paths_subform(
        &self,
        subform_path: &str,
        schema_paths: &[String],
        format: Option<crate::ReturnFormat>,
    ) -> Value {
        let (base_path, _) = self.resolve_subform_path_alias(subform_path);
        if let Some(subform) = self.subforms.get(base_path.as_ref() as &str) {
            subform.get_schema_by_paths(schema_paths, Some(format.unwrap_or(ReturnFormat::Flat)))
        } else {
            match format.unwrap_or_default() {
                crate::ReturnFormat::Array => Value::Array(vec![]),
                _ => Value::Object(serde_json::Map::new()),
            }
        }
    }

    /// Get resolved layout overlay entries for subform.
    pub fn get_resolved_layout_subform(&mut self, subform_path: &str) -> ResolvedLayoutResult {
        let (base_path, _) = self.resolve_subform_path_alias(subform_path);
        if let Some(subform) = self.subforms.get_mut(base_path.as_ref() as &str) {
            subform.get_resolved_layout()
        } else {
            ResolvedLayoutResult::default()
        }
    }

    /// Get evaluated schema with layout fully resolved for subform.
    pub fn get_evaluated_schema_resolved_subform(&mut self, subform_path: &str) -> Value {
        let (base_path, _) = self.resolve_subform_path_alias(subform_path);
        if let Some(subform) = self.subforms.get_mut(base_path.as_ref() as &str) {
            subform.get_evaluated_schema_resolved()
        } else {
            Value::Null
        }
    }

    /// Get list of available subform paths.
    pub fn get_subform_paths(&self) -> Vec<String> {
        self.subforms.keys().cloned().collect()
    }

    /// Check if a subform exists at the given path.
    pub fn has_subform(&self, subform_path: &str) -> bool {
        let (base_path, _) = self.resolve_subform_path_alias(subform_path);
        self.subforms.contains_key(base_path.as_ref() as &str)
    }
}