voxgig_struct/

major.rs

// Copyright (c) 2025-2026 Voxgig Ltd. MIT LICENSE.
// VERSION: @voxgig/struct 0.1.0
//
// Major utilities — walk, merge, getpath, setpath, and (staged) the
// inject / transform / validate / select machinery. See rs/PLAN.md §8-§11.
//
// `merge` is implemented walk-based to stay close to the canonical; the
// `cur`/`dst` scratch vectors are shared between the before/after closures
// via `Rc<RefCell<…>>` (Rust can't have two FnMut closures both holding a
// `&mut` to the same Vec).

use std::cell::RefCell;
use std::rc::Rc;

use crate::consts::*;
use crate::mini::*;
use crate::ordered_map::OrderedMap;
use crate::value::{js_string, js_to_int32, js_to_number, Value};
use crate::StructError;

// ---------------------------------------------------------------------
// callback / function types
// ---------------------------------------------------------------------

/// `WalkApply` — `(key, val, parent, path) -> any`. `key` is `Noval` at the
/// root and a `Str` for every descendant (matches the canonical, where
/// `items` always yields string keys).
pub type WalkClosure<'a> = dyn FnMut(&Value, &Value, &Value, &[String]) -> Value + 'a;

/// `Injector` — `(inj, val, ref, store) -> any`.
pub type NativeFn = crate::value::NativeFn;

/// `Modify` — `(val, key, parent, inj, store)`.
pub type Modify = crate::value::ModifyFn;

pub type Inj = Rc<RefCell<Injection>>;
pub type SVec = Rc<RefCell<Vec<String>>>;

// ---------------------------------------------------------------------
// walk
// ---------------------------------------------------------------------

pub fn walk(
    val: Value,
    before: Option<&mut WalkClosure>,
    after: Option<&mut WalkClosure>,
    maxdepth: Option<i64>,
) -> Value {
    let mut path: Vec<String> = Vec::new();
    walk_impl(
        val,
        before,
        after,
        maxdepth,
        &Value::Noval,
        &Value::Noval,
        &mut path,
    )
}

fn walk_impl(
    val: Value,
    mut before: Option<&mut WalkClosure>,
    mut after: Option<&mut WalkClosure>,
    maxdepth: Option<i64>,
    key: &Value,
    parent: &Value,
    path: &mut Vec<String>,
) -> Value {
    let depth = path.len() as i64;

    let out = match before {
        Some(ref mut f) => f(key, &val, parent, path),
        None => val,
    };

    let md = match maxdepth {
        Some(m) if m >= 0 => m,
        _ => MAXDEPTH,
    };
    if md == 0 || (md > 0 && md <= depth) {
        return out;
    }

    if is_node(&out) {
        let entries = items_vec(&out);
        for (ckey, child) in entries {
            path.push(ckey.clone());
            let res = walk_impl(
                child,
                before.as_deref_mut(),
                after.as_deref_mut(),
                maxdepth,
                &Value::str(ckey.clone()),
                &out,
                path,
            );
            path.pop();
            set_prop(out.clone(), &Value::str(ckey), res);
        }
    }

    match after {
        Some(ref mut f) => f(key, &out, parent, path),
        None => out,
    }
}

// ---------------------------------------------------------------------
// merge
// ---------------------------------------------------------------------

const T_INSTANCE_I: i64 = T_INSTANCE as i64;

pub fn merge(val: &Value, maxdepth: Option<i64>) -> Value {
    let md = match slice(
        Value::Num(maxdepth.unwrap_or(MAXDEPTH) as f64),
        Some(0),
        None,
        false,
    ) {
        Value::Num(n) => n as i64,
        _ => MAXDEPTH,
    };

    let list: Vec<Value> = match val {
        Value::List(l) => l.borrow().clone(),
        other => return other.clone(),
    };

    if list.is_empty() {
        return Value::Noval;
    }
    if list.len() == 1 {
        return list[0].clone();
    }

    let mut out = match &list[0] {
        Value::Noval => Value::empty_map(),
        other => other.clone(),
    };

    for obj in list.iter().skip(1) {
        let obj = obj.clone();
        if !is_node(&obj) {
            out = obj;
            continue;
        }

        let cur: Rc<RefCell<Vec<Value>>> = Rc::new(RefCell::new(vec![out.clone()]));
        let dst: Rc<RefCell<Vec<Value>>> = Rc::new(RefCell::new(vec![out.clone()]));

        let cur_b = cur.clone();
        let dst_b = dst.clone();
        let mut before = move |key: &Value, v: &Value, _parent: &Value, path: &[String]| -> Value {
            let pi = path.len() as i64;
            let mut ret = v.clone();

            if md <= pi {
                let target = cur_b
                    .borrow()
                    .get((pi - 1) as usize)
                    .cloned()
                    .unwrap_or(Value::Noval);
                set_prop(target, key, v.clone());
            } else if !is_node(v) {
                let mut cb = cur_b.borrow_mut();
                grow(&mut cb, pi as usize);
                cb[pi as usize] = v.clone();
            } else {
                let tval = {
                    let d = if pi > 0 {
                        let prev = dst_b
                            .borrow()
                            .get((pi - 1) as usize)
                            .cloned()
                            .unwrap_or(Value::Noval);
                        get_prop(&prev, key, Value::Noval)
                    } else {
                        dst_b
                            .borrow()
                            .get(pi as usize)
                            .cloned()
                            .unwrap_or(Value::Noval)
                    };
                    let mut db = dst_b.borrow_mut();
                    grow(&mut db, pi as usize);
                    db[pi as usize] = d.clone();
                    d
                };
                let mut cb = cur_b.borrow_mut();
                grow(&mut cb, pi as usize);
                if tval.is_noval() && (typify(v) & T_INSTANCE_I) == 0 {
                    cb[pi as usize] = if is_list(v) {
                        Value::empty_list()
                    } else {
                        Value::empty_map()
                    };
                } else if typify(v) == typify(&tval) {
                    cb[pi as usize] = tval;
                } else {
                    cb[pi as usize] = v.clone();
                    ret = Value::Noval;
                }
            }
            ret
        };

        let cur_a = cur.clone();
        let mut after = move |key: &Value, _v: &Value, _parent: &Value, path: &[String]| -> Value {
            let ci = path.len() as i64;
            let (target, value) = {
                let cb = cur_a.borrow();
                (
                    cb.get((ci - 1) as usize).cloned().unwrap_or(Value::Noval),
                    cb.get(ci as usize).cloned().unwrap_or(Value::Noval),
                )
            };
            set_prop(target, key, value.clone());
            value
        };

        out = walk(obj, Some(&mut before), Some(&mut after), maxdepth);
    }

    if md == 0 {
        let last = get_elem(&Value::list(list.clone()), &Value::Num(-1.0), Value::Noval);
        out = match &last {
            Value::List(_) => Value::empty_list(),
            Value::Map(_) => Value::empty_map(),
            other => other.clone(),
        };
    }

    out
}

fn grow(v: &mut Vec<Value>, idx: usize) {
    while v.len() <= idx {
        v.push(Value::Noval);
    }
}

// ---------------------------------------------------------------------
// Injection state
// ---------------------------------------------------------------------

pub struct Injection {
    pub mode: i64,
    pub full: bool,
    pub key_i: i64,
    pub keys: SVec,
    pub key: String,
    pub val: Value,
    pub parent: Value,
    pub path: Vec<String>,
    pub nodes: Vec<Value>,
    pub handler: NativeFn,
    pub errs: Value, // Value::List
    pub meta: Value, // Value::Map
    pub dparent: Value,
    pub dpath: Vec<String>,
    pub base: Option<String>,
    pub modify: Option<Modify>,
    pub extra: Option<Value>,
    pub prior: Option<Inj>,
}

/// Public `injdef` argument — the subset of `Partial<Injection>` callers set.
#[derive(Default, Clone)]
pub struct InjectDef {
    pub base: Option<String>,
    pub errs: Option<Value>,
    pub meta: Option<Value>,
    pub modify: Option<Modify>,
    pub handler: Option<NativeFn>,
    pub extra: Option<Value>,
    pub dparent: Option<Value>,
    pub dpath: Option<Vec<String>>,
    pub key: Option<Value>,
}

impl Injection {
    /// Build a (mostly-empty) injection carrying just the fields the public
    /// `getpath` / `setpath` read from an `injdef`.
    pub fn from_def(def: Option<&InjectDef>) -> Inj {
        let inj = Injection {
            mode: M_VAL,
            full: false,
            key_i: 0,
            keys: Rc::new(RefCell::new(vec![S_DTOP.to_string()])),
            key: S_DTOP.to_string(),
            val: Value::Noval,
            parent: Value::Noval,
            path: vec![S_DTOP.to_string()],
            nodes: vec![Value::Noval],
            handler: inject_handler_fn(),
            errs: Value::empty_list(),
            meta: Value::empty_map(),
            dparent: Value::Noval,
            dpath: vec![S_DTOP.to_string()],
            base: None,
            modify: None,
            extra: None,
            prior: None,
        };
        let inj = Rc::new(RefCell::new(inj));
        if let Some(d) = def {
            let mut b = inj.borrow_mut();
            if let Some(x) = &d.base {
                b.base = Some(x.clone());
            }
            if let Some(x) = &d.errs {
                b.errs = x.clone();
            }
            if let Some(x) = &d.meta {
                b.meta = x.clone();
            }
            if let Some(x) = &d.modify {
                b.modify = Some(x.clone());
            }
            if let Some(x) = &d.handler {
                b.handler = x.clone();
            }
            if let Some(x) = &d.extra {
                b.extra = Some(x.clone());
            }
            if let Some(x) = &d.dparent {
                b.dparent = x.clone();
            }
            if let Some(x) = &d.dpath {
                b.dpath = x.clone();
            }
            if let Some(x) = &d.key {
                b.key = str_key(x.clone());
            }
        }
        inj
    }

    fn has_handler(def: Option<&InjectDef>) -> bool {
        def.map(|d| d.handler.is_some()).unwrap_or(false)
    }

    /// Fresh root injection: `val` wrapped in the virtual parent holder.
    pub fn root(val: Value, parent: Value) -> Inj {
        let parent_clone = parent.clone();
        Rc::new(RefCell::new(Injection {
            mode: M_VAL,
            full: false,
            key_i: 0,
            keys: Rc::new(RefCell::new(vec![S_DTOP.to_string()])),
            key: S_DTOP.to_string(),
            val,
            parent,
            path: vec![S_DTOP.to_string()],
            nodes: vec![parent_clone],
            handler: inject_handler_fn(),
            errs: Value::empty_list(),
            meta: Value::empty_map(),
            dparent: Value::Noval,
            dpath: vec![S_DTOP.to_string()],
            base: Some(S_DTOP.to_string()),
            modify: None,
            extra: None,
            prior: None,
        }))
    }

    pub fn descend(this: &Inj) {
        // meta.__d++
        {
            let b = this.borrow();
            if let Value::Map(m) = &b.meta {
                let cur = m
                    .borrow()
                    .get("__d")
                    .and_then(|v| v.as_num())
                    .unwrap_or(0.0);
                m.borrow_mut()
                    .insert("__d".to_string(), Value::Num(cur + 1.0));
            }
        }
        let (parentkey, has_dparent, dpath_len, last_part) = {
            let b = this.borrow();
            let parentkey = if b.path.len() >= 2 {
                Some(b.path[b.path.len() - 2].clone())
            } else {
                None
            };
            (
                parentkey,
                !b.dparent.is_noval(),
                b.dpath.len(),
                b.dpath.last().cloned(),
            )
        };

        if !has_dparent {
            if dpath_len > 1 {
                if let Some(pk) = parentkey {
                    this.borrow_mut().dpath.push(pk);
                }
            }
        } else if let Some(pk) = parentkey {
            let newdparent = {
                let b = this.borrow();
                get_prop(&b.dparent, &Value::str(pk.clone()), Value::Noval)
            };
            let mut b = this.borrow_mut();
            b.dparent = newdparent;
            if last_part.as_deref() == Some(format!("$:{pk}").as_str()) {
                let n = b.dpath.len();
                b.dpath.truncate(n.saturating_sub(1));
            } else {
                b.dpath.push(pk);
            }
        }
    }

    pub fn child(this: &Inj, key_i: i64, keys: SVec) -> Inj {
        let (
            key,
            parent_val,
            cval,
            path,
            nodes,
            mode,
            handler,
            modify,
            base,
            meta,
            errs,
            dpath,
            dparent,
        ) = {
            let b = this.borrow();
            let key = str_key(
                keys.borrow()
                    .get(key_i.max(0) as usize)
                    .cloned()
                    .map(Value::Str)
                    .unwrap_or(Value::Noval),
            );
            let parent_val = b.val.clone();
            let cval = get_prop(&parent_val, &Value::str(key.clone()), Value::Noval);
            let mut path = b.path.clone();
            path.push(key.clone());
            let mut nodes = b.nodes.clone();
            nodes.push(parent_val.clone());
            (
                key,
                parent_val,
                cval,
                path,
                nodes,
                b.mode,
                b.handler.clone(),
                b.modify.clone(),
                b.base.clone(),
                b.meta.clone(),
                b.errs.clone(),
                b.dpath.clone(),
                b.dparent.clone(),
            )
        };
        Rc::new(RefCell::new(Injection {
            mode,
            full: false,
            key_i,
            keys,
            key,
            val: cval,
            parent: parent_val,
            path,
            nodes,
            handler,
            errs,
            meta,
            dparent,
            dpath,
            base,
            modify,
            extra: None,
            prior: Some(Rc::clone(this)),
        }))
    }

    pub fn setval(this: &Inj, val: Value, ancestor: Option<i64>) -> Value {
        let anc = ancestor.unwrap_or(0);
        if anc < 2 {
            let (parent, key) = {
                let b = this.borrow();
                (b.parent.clone(), b.key.clone())
            };
            if val.is_noval() {
                let np = del_prop(parent, &Value::str(key));
                this.borrow_mut().parent = np.clone();
                np
            } else {
                set_prop(parent, &Value::str(key), val)
            }
        } else {
            let (aval, akey) = {
                let b = this.borrow();
                let n = b.nodes.len() as i64;
                let aval = if n - anc >= 0 {
                    b.nodes[(n - anc) as usize].clone()
                } else {
                    Value::Noval
                };
                let pn = b.path.len() as i64;
                let akey = if pn - anc >= 0 {
                    b.path[(pn - anc) as usize].clone()
                } else {
                    String::new()
                };
                (aval, akey)
            };
            if val.is_noval() {
                del_prop(aval, &Value::str(akey))
            } else {
                set_prop(aval, &Value::str(akey), val)
            }
        }
    }
}

// ---------------------------------------------------------------------
// getpath
// ---------------------------------------------------------------------

pub fn get_path(store: &Value, path: &Value, injdef: Option<&InjectDef>) -> Value {
    let inj: Option<Inj> = injdef.map(|_| Injection::from_def(injdef));
    get_path_inj(store, path, inj.as_ref())
}

/// Internal `getpath` working against a full `Inj` (used by the inject
/// machinery and by the public `get_path` wrapper).
pub fn get_path_inj(store: &Value, path: &Value, injdef: Option<&Inj>) -> Value {
    let mut parts: Vec<String> = match path {
        Value::List(l) => l
            .borrow()
            .iter()
            .map(|x| match x {
                Value::Str(s) => s.clone(),
                other => js_string(other),
            })
            .collect(),
        Value::Str(s) => s.split('.').map(|p| p.to_string()).collect(),
        Value::Num(n) => vec![str_key(Value::Num(*n))],
        _ => return Value::Noval,
    };

    let base = injdef.and_then(|i| i.borrow().base.clone());
    let src = match &base {
        Some(b) => get_prop(store, &Value::str(b.clone()), store.clone()),
        None => store.clone(),
    };
    let numparts = parts.len();
    let dparent = injdef
        .map(|i| i.borrow().dparent.clone())
        .unwrap_or(Value::Noval);

    let mut val = store.clone();

    let path_nullish = matches!(path, Value::Noval | Value::Null);
    if path_nullish
        || matches!(store, Value::Noval | Value::Null)
        || (numparts == 1 && parts[0].is_empty())
    {
        val = src.clone();
    } else if numparts > 0 {
        if numparts == 1 {
            val = get_prop(store, &Value::str(parts[0].clone()), Value::Noval);
        }

        if !is_func(&val) {
            val = src.clone();

            // meta path prefix:  "name$=..."  /  "name$~..."
            if let Some(inj) = injdef {
                let meta = inj.borrow().meta.clone();
                let first = parts[0].clone();
                if let Some(caps) = R_META_PATH.captures(&first) {
                    if !meta.is_noval() {
                        val = get_prop(&meta, &Value::str(caps[1].to_string()), Value::Noval);
                        parts[0] = caps[3].to_string();
                    }
                }
            }

            let dpath: Vec<String> = injdef.map(|i| i.borrow().dpath.clone()).unwrap_or_default();

            let mut p_i = 0usize;
            while !val.is_noval() && p_i < numparts {
                let mut part = parts[p_i].clone();

                if let Some(inj) = injdef {
                    if part == S_DKEY {
                        part = inj.borrow().key.clone();
                    } else if let Some(rest) = part.strip_prefix("$GET:") {
                        part = js_string(&get_path_inj(&src, &Value::str(drop_last(rest)), None));
                    } else if let Some(rest) = part.strip_prefix("$REF:") {
                        let spec = get_prop(store, &Value::str(S_DSPEC), Value::Noval);
                        part = js_string(&get_path_inj(&spec, &Value::str(drop_last(rest)), None));
                    } else if let Some(rest) = part.strip_prefix("$META:") {
                        let meta = inj.borrow().meta.clone();
                        part = js_string(&get_path_inj(&meta, &Value::str(drop_last(rest)), None));
                    }
                }

                // str::replace allocates a fresh String even with no match, so
                // skip it for the common no-`$$` segment.
                if part.contains("$$") {
                    part = part.replace("$$", "$");
                }

                if part.is_empty() {
                    let mut ascends = 0i64;
                    while parts.get(1 + p_i).map(|s| s.is_empty()).unwrap_or(false) {
                        ascends += 1;
                        p_i += 1;
                    }

                    if injdef.is_some() && ascends > 0 {
                        if p_i == parts.len() - 1 {
                            ascends -= 1;
                        }
                        if ascends == 0 {
                            val = dparent.clone();
                        } else {
                            // fullpath = slice(dpath, -ascends) ++ parts[p_i+1..]
                            let head = slice(
                                Value::list(dpath.iter().cloned().map(Value::Str).collect()),
                                Some(-ascends),
                                None,
                                false,
                            );
                            let mut fullpath: Vec<String> = match &head {
                                Value::List(l) => l
                                    .borrow()
                                    .iter()
                                    .map(|x| x.as_str().map(|s| s.to_string()).unwrap_or_default())
                                    .collect(),
                                _ => Vec::new(),
                            };
                            fullpath.extend_from_slice(&parts[p_i + 1..]);
                            if ascends <= dpath.len() as i64 {
                                val = get_path_inj(
                                    store,
                                    &Value::list(fullpath.into_iter().map(Value::Str).collect()),
                                    None,
                                );
                            } else {
                                val = Value::Noval;
                            }
                            break;
                        }
                    } else {
                        val = dparent.clone();
                    }
                } else {
                    val = get_prop(&val, &Value::str(part), Value::Noval);
                }

                p_i += 1;
            }
        }
    }

    if let Some(inj) = injdef {
        let handler = inj.borrow().handler.clone();
        let r = pathify(path, None, None);
        val = handler(inj, &val, &r, store);
    }

    val
}

fn drop_last(s: &str) -> String {
    let chars: Vec<char> = s.chars().collect();
    if chars.is_empty() {
        String::new()
    } else {
        chars[..chars.len() - 1].iter().collect()
    }
}

// ---------------------------------------------------------------------
// setpath
// ---------------------------------------------------------------------

pub fn set_path(store: &Value, path: &Value, val: Value, injdef: Option<&InjectDef>) -> Value {
    // Keep parts as Values so a numeric part (only possible when `path` is an
    // array) makes its parent a list, while a string part makes a map.
    let parts: Vec<Value> = match path {
        Value::List(l) => l.borrow().clone(),
        Value::Str(s) => s.split('.').map(Value::str).collect(),
        Value::Num(n) => vec![Value::Num(*n)],
        _ => return Value::Noval,
    };
    if parts.is_empty() {
        return Value::Noval;
    }

    let base = injdef.and_then(|d| d.base.clone());
    let numparts = parts.len();
    let mut parent = match &base {
        Some(b) => get_prop(store, &Value::str(b.clone()), store.clone()),
        None => store.clone(),
    };

    for p_i in 0..numparts - 1 {
        let part_key = parts[p_i].clone();
        let next_parent = get_prop(&parent, &part_key, Value::Noval);
        let next_parent = if !is_node(&next_parent) {
            let next_is_num = parts
                .get(p_i + 1)
                .map(|p| typify(p) & (T_NUMBER as i64) != 0)
                .unwrap_or(false);
            let np = if next_is_num {
                Value::empty_list()
            } else {
                Value::empty_map()
            };
            set_prop(parent.clone(), &part_key, np.clone());
            np
        } else {
            next_parent
        };
        parent = next_parent;
    }

    let last = parts[numparts - 1].clone();
    if val.is_delete() {
        del_prop(parent.clone(), &last);
    } else {
        set_prop(parent.clone(), &last, val);
    }

    parent
}

// ---------------------------------------------------------------------
// inject / transform / validate / select — staged (see rs/PLAN.md, NOTES.md)
// ---------------------------------------------------------------------

/// Default inject handler (`_injecthandler`): if the value is a `$NAME`
/// command function, call it; otherwise, in `val` mode for a full-string
/// injection, write the value back into the parent.
pub fn inject_handler_fn() -> NativeFn {
    Rc::new(inject_handler)
}

fn inject_handler(inj: &Inj, val: &Value, r: &str, store: &Value) -> Value {
    let iscmd = is_func(val) && (r.is_empty() || r.starts_with('$'));
    if iscmd {
        if let Value::Func(f) = val {
            return f(inj, val, r, store);
        }
    }
    let (mode, full) = {
        let b = inj.borrow();
        (b.mode, b.full)
    };
    if mode == M_VAL && full {
        Injection::setval(inj, val.clone(), None);
    }
    val.clone()
}

/// `_injectstr` — substitute `` `path` `` references inside a string.
fn injectstr(val: &str, store: &Value, inj: Option<&Inj>) -> Value {
    if val.is_empty() {
        return Value::str("");
    }

    if let Some(caps) = R_INJECTION_FULL.captures(val) {
        if let Some(i) = inj {
            i.borrow_mut().full = true;
        }
        let mut pathref = caps[1].to_string();
        if pathref.chars().count() > 3 {
            pathref = pathref.replace("$BT", S_BT).replace("$DS", S_DS);
        }
        return get_path_inj(store, &Value::str(pathref), inj);
    }

    // partial injection: replace each `ref` occurrence
    let out_str = R_INJECTION_PARTIAL
        .replace_all(val, |caps: &crate::re::Captures<'_>| -> String {
            let mut r = caps[1].to_string();
            if r.chars().count() > 3 {
                r = r.replace("$BT", S_BT).replace("$DS", S_DS);
            }
            if let Some(i) = inj {
                i.borrow_mut().full = false;
            }
            let found = get_path_inj(store, &Value::str(r), inj);
            match &found {
                Value::Noval => String::new(),
                Value::Str(s) => s.clone(),
                other => jsonify(
                    other,
                    Some(&JsonFlags {
                        indent: 0,
                        offset: 0,
                    }),
                ),
            }
        })
        .to_string();

    if let Some(i) = inj {
        let handler = {
            i.borrow_mut().full = true;
            i.borrow().handler.clone()
        };
        return handler(i, &Value::str(out_str), val, store);
    }
    Value::str(out_str)
}

pub fn inject(val: Value, store: &Value, injdef: Option<&InjectDef>) -> Value {
    let inj = make_root_injection(val.clone(), store, injdef);
    inject_inj(val, store, &inj)
}

/// Build the root injection for a top-level `inject` (mirrors the TS setup
/// block when `injdef.mode == null`).
fn make_root_injection(val: Value, store: &Value, injdef: Option<&InjectDef>) -> Inj {
    let mut top = OrderedMap::new();
    top.insert(S_DTOP.to_string(), val.clone());
    let inj = Injection::root(val, Value::map(top));
    {
        let mut b = inj.borrow_mut();
        b.dparent = store.clone();
        let store_errs = get_prop(store, &Value::str(S_DERRS), Value::Noval);
        if !store_errs.is_noval() {
            b.errs = store_errs;
        }
        if let Value::Map(m) = &b.meta {
            m.borrow_mut().insert("__d".to_string(), Value::Num(0.0));
        }
        if let Some(d) = injdef {
            if let Some(x) = &d.modify {
                b.modify = Some(x.clone());
            }
            if let Some(x) = &d.extra {
                b.extra = Some(x.clone());
            }
            if let Some(x) = &d.meta {
                b.meta = x.clone();
            }
            if let Some(x) = &d.handler {
                b.handler = x.clone();
            }
        }
    }
    inj
}

/// Recursive `inject` working against an existing injection.
// `nk_i` is re-read after every child phase to match the canonical loop
// (an injector in the M_VAL phase, e.g. $REF, may change `key_i`).
#[allow(unused_assignments)]
fn inject_inj(mut val: Value, store: &Value, inj: &Inj) -> Value {
    Injection::descend(inj);

    if is_node(&val) {
        // node keys: sorted, then `$`-bearing keys last (for maps).
        let nodekeys: SVec = {
            let ks = keysof_vec(&val);
            if is_map(&val) {
                let (mut plain, dollar): (Vec<String>, Vec<String>) =
                    ks.into_iter().partition(|k| !k.contains(S_DS));
                plain.extend(dollar);
                Rc::new(RefCell::new(plain))
            } else {
                Rc::new(RefCell::new(ks))
            }
        };

        let mut nk_i: i64 = 0;
        loop {
            if nk_i < 0 {
                nk_i += 1;
                continue;
            }
            if nk_i as usize >= nodekeys.borrow().len() {
                break;
            }

            let childinj = Injection::child(inj, nk_i, nodekeys.clone());
            let nodekey = childinj.borrow().key.clone();
            childinj.borrow_mut().mode = M_KEYPRE;

            let prekey = injectstr(&nodekey, store, Some(&childinj));
            nk_i = childinj.borrow().key_i;
            // (keys may have been replaced by an injector — `nodekeys` itself
            // is the shared Rc, so re-reading is implicit.)

            if !prekey.is_noval() {
                let cval = get_prop(&val, &prekey, Value::Noval);
                {
                    let mut b = childinj.borrow_mut();
                    b.val = cval.clone();
                    b.mode = M_VAL;
                }
                inject_inj(cval, store, &childinj);
                nk_i = childinj.borrow().key_i;

                childinj.borrow_mut().mode = M_KEYPOST;
                injectstr(&nodekey, store, Some(&childinj));
                nk_i = childinj.borrow().key_i;
            }

            nk_i += 1;
        }
    } else if let Value::Str(s) = val.clone() {
        inj.borrow_mut().mode = M_VAL;
        let r = injectstr(&s, store, Some(inj));
        val = r.clone();
        if !val.is_skip() {
            Injection::setval(inj, val.clone(), None);
        }
    }

    // custom modification
    let modify = inj.borrow().modify.clone();
    if let Some(m) = modify {
        if !val.is_skip() {
            let (mkey, mparent) = {
                let b = inj.borrow();
                (b.key.clone(), b.parent.clone())
            };
            let mval = get_prop(&mparent, &Value::str(mkey.clone()), Value::Noval);
            m(&mval, &Value::str(mkey), &mparent, inj, store);
        }
    }

    inj.borrow_mut().val = val;
    let parent = inj.borrow().parent.clone();
    // Read back the root via raw lookup (canonical TS `_lookup(inj.parent,
    // S_DTOP)`) so a null result is preserved, not dropped by Group A.
    lookup(&parent, &Value::str(S_DTOP))
}

// ---- transform commands ----------------------------------------------

const T_ANY_I: i64 = T_ANY as i64;

fn errs_push(inj: &Inj, msg: String) {
    let errs = inj.borrow().errs.clone();
    if let Value::List(l) = &errs {
        l.borrow_mut().push(Value::Str(msg));
    }
}

fn placement_str(mode: i64) -> &'static str {
    match mode {
        M_VAL => "value",
        M_KEYPRE | M_KEYPOST => "key",
        _ => "",
    }
}

pub fn check_placement(modes: i64, ijname: &str, parent_types: i64, inj: &Inj) -> bool {
    let (mode, parent) = {
        let b = inj.borrow();
        (b.mode, b.parent.clone())
    };
    if modes & mode == 0 {
        let expected: Vec<&str> = [M_KEYPRE, M_KEYPOST, M_VAL]
            .iter()
            .filter(|m| modes & **m != 0)
            .map(|m| placement_str(*m))
            .collect();
        errs_push(
            inj,
            format!(
                "${ijname}: invalid placement as {}, expected: {}.",
                placement_str(mode),
                expected.join(",")
            ),
        );
        return false;
    }
    if !is_empty(&Value::Num(parent_types as f64)) {
        let ptype = typify(&parent);
        if parent_types & ptype == 0 {
            errs_push(
                inj,
                format!(
                    "${ijname}: invalid placement in parent {}, expected: {}.",
                    type_name(ptype),
                    type_name(parent_types)
                ),
            );
            return false;
        }
    }
    true
}

pub fn injector_args(arg_types: &[i64], args: &[Value]) -> Vec<Value> {
    let mut found: Vec<Value> = Vec::with_capacity(1 + arg_types.len());
    found.push(Value::Noval);
    for (i, at) in arg_types.iter().enumerate() {
        let arg = args.get(i).cloned().unwrap_or(Value::Noval);
        let argtype = typify(&arg);
        if at & argtype == 0 {
            found[0] = Value::str(format!(
                "invalid argument: {} ({} at position {}) is not of type: {}.",
                stringify(&arg, Some(22), false),
                type_name(argtype),
                1 + i,
                type_name(*at)
            ));
            return found;
        }
        found.push(arg);
    }
    found
}

pub fn inject_child(child: Value, store: &Value, inj: &Inj) -> Inj {
    let prior = inj.borrow().prior.clone();
    let cinj: Inj = match prior {
        None => Rc::clone(inj),
        Some(p) => {
            let pprior = p.borrow().prior.clone();
            match pprior {
                Some(pp) => {
                    let (pki, pkeys, pkey) = {
                        let b = p.borrow();
                        (b.key_i, b.keys.clone(), b.key.clone())
                    };
                    let c = Injection::child(&pp, pki, pkeys);
                    c.borrow_mut().val = child.clone();
                    let cparent = c.borrow().parent.clone();
                    set_prop(cparent, &Value::str(pkey), child.clone());
                    c
                }
                None => {
                    let (ki, keys, key) = {
                        let b = inj.borrow();
                        (b.key_i, b.keys.clone(), b.key.clone())
                    };
                    let c = Injection::child(&p, ki, keys);
                    c.borrow_mut().val = child.clone();
                    let cparent = c.borrow().parent.clone();
                    set_prop(cparent, &Value::str(key), child.clone());
                    c
                }
            }
        }
    };
    let _ = inject_inj(child, store, &cinj);
    cinj
}

const FORMATTER_NAMES: [&str; 7] = [
    "identity", "upper", "lower", "string", "number", "integer", "concat",
];

fn apply_formatter(name: &str, k: &Value, v: &Value) -> Value {
    match name {
        "identity" => v.clone(),
        "upper" => {
            if is_node(v) {
                v.clone()
            } else {
                Value::str(js_string(v).to_uppercase())
            }
        }
        "lower" => {
            if is_node(v) {
                v.clone()
            } else {
                Value::str(js_string(v).to_lowercase())
            }
        }
        "string" => {
            if is_node(v) {
                v.clone()
            } else {
                Value::str(js_string(v))
            }
        }
        "number" => {
            if is_node(v) {
                v.clone()
            } else {
                let n = js_to_number(v);
                Value::Num(if n.is_nan() { 0.0 } else { n })
            }
        }
        "integer" => {
            if is_node(v) {
                v.clone()
            } else {
                let n = js_to_number(v);
                let n = if n.is_nan() { 0.0 } else { n };
                Value::Num(js_to_int32(n) as f64)
            }
        }
        "concat" => {
            if k.is_noval() && is_list(v) {
                Value::str(
                    items_vec(v)
                        .iter()
                        .map(|(_, n)| {
                            if is_node(n) {
                                String::new()
                            } else {
                                js_string(n)
                            }
                        })
                        .collect::<Vec<_>>()
                        .join(""),
                )
            } else {
                v.clone()
            }
        }
        _ => v.clone(),
    }
}

// `$FORMAT` — render a templated value through a named (or supplied) formatter.
fn transform_format(inj: &Inj, _val: &Value, _r: &str, store: &Value) -> Value {
    inj.borrow().keys.borrow_mut().truncate(1);
    if inj.borrow().mode != M_VAL {
        return Value::Noval;
    }
    let (parent, path, nodes) = {
        let b = inj.borrow();
        (b.parent.clone(), b.path.clone(), b.nodes.clone())
    };
    let name = lookup(&parent, &Value::Num(1.0));
    let child = lookup(&parent, &Value::Num(2.0));
    let tkey = path
        .get(path.len().saturating_sub(2))
        .cloned()
        .unwrap_or_default();
    let nlen = nodes.len();
    let target = if nlen >= 2 {
        nodes[nlen - 2].clone()
    } else if nlen >= 1 {
        nodes[nlen - 1].clone()
    } else {
        Value::Noval
    };

    let cinj = inject_child(child, store, inj);
    let resolved = cinj.borrow().val.clone();

    let fname: Option<String> = name
        .as_str()
        .filter(|n| FORMATTER_NAMES.contains(n))
        .map(|s| s.to_string());
    if fname.is_none() && !is_func(&name) {
        errs_push(
            inj,
            format!("$FORMAT: unknown format: {}.", js_string(&name)),
        );
        return Value::Noval;
    }

    let out = if let Some(fn_name) = &fname {
        let mut fmt = |k: &Value, v: &Value, _p: &Value, _t: &[String]| -> Value {
            apply_formatter(fn_name, k, v)
        };
        walk(resolved, Some(&mut fmt), None, None)
    } else if let Value::Func(f) = &name {
        let f = f.clone();
        let mut fmt =
            |_k: &Value, v: &Value, _p: &Value, _t: &[String]| -> Value { f(inj, v, "", store) };
        walk(resolved, Some(&mut fmt), None, None)
    } else {
        resolved
    };

    set_prop(target, &Value::str(tkey), out.clone());
    out
}

// `$APPLY` — call a function (from the spec args) on the resolved child.
fn transform_apply(inj: &Inj, _val: &Value, _r: &str, store: &Value) -> Value {
    if !check_placement(M_VAL, "APPLY", T_LIST as i64, inj) {
        return Value::Noval;
    }
    let (parent, path, nodes) = {
        let b = inj.borrow();
        (b.parent.clone(), b.path.clone(), b.nodes.clone())
    };
    let args: Vec<Value> = slice(parent.clone(), Some(1), None, false)
        .as_list()
        .map(|l| l.borrow().clone())
        .unwrap_or_default();
    let ia = injector_args(&[T_FUNCTION as i64, T_ANY as i64], &args);
    if let Value::Str(e) = &ia[0] {
        errs_push(inj, format!("$APPLY: {e}"));
        return Value::Noval;
    }
    let apply = ia.get(1).cloned().unwrap_or(Value::Noval);
    let child = ia.get(2).cloned().unwrap_or(Value::Noval);
    let tkey = path
        .get(path.len().saturating_sub(2))
        .cloned()
        .unwrap_or_default();
    let nlen = nodes.len();
    let target = if nlen >= 2 {
        nodes[nlen - 2].clone()
    } else if nlen >= 1 {
        nodes[nlen - 1].clone()
    } else {
        Value::Noval
    };
    let cinj = inject_child(child, store, inj);
    let resolved = cinj.borrow().val.clone();
    // The corpus only exercises the error paths; if `apply` is a callable, do
    // a best-effort call (the canonical passes (resolved, store, cinj)).
    let out = if let Value::Func(f) = &apply {
        f(&cinj, &resolved, "", store)
    } else {
        resolved
    };
    set_prop(target, &Value::str(tkey), out.clone());
    out
}

fn transform_delete(inj: &Inj, _v: &Value, _r: &str, _store: &Value) -> Value {
    Injection::setval(inj, Value::Noval, None);
    Value::Noval
}

fn transform_copy(inj: &Inj, _v: &Value, _r: &str, _store: &Value) -> Value {
    if !check_placement(M_VAL, "COPY", T_ANY_I, inj) {
        return Value::Noval;
    }
    let (dparent, key) = {
        let b = inj.borrow();
        (b.dparent.clone(), b.key.clone())
    };
    // Group B: preserve a stored null (canonical `_lookup(inj.dparent, inj.key)`).
    let out = lookup(&dparent, &Value::str(key));
    Injection::setval(inj, out.clone(), None);
    out
}

fn transform_key(inj: &Inj, _v: &Value, _r: &str, _store: &Value) -> Value {
    let (mode, parent, dparent, anno_key) = {
        let b = inj.borrow();
        let anno_key = b.path.get(b.path.len().saturating_sub(2)).cloned();
        (b.mode, b.parent.clone(), b.dparent.clone(), anno_key)
    };
    if mode != M_VAL {
        return Value::Noval;
    }
    // Literal presence of the $KEY meta (canonical `_lookup(parent, S_BKEY)`):
    // a null keyspec still counts as declared, so use the raw lookup.
    let keyspec = lookup(&parent, &Value::str(S_BKEY));
    if !keyspec.is_noval() {
        del_prop(parent.clone(), &Value::str(S_BKEY));
        return get_prop(&dparent, &keyspec, Value::Noval);
    }
    let anno = get_prop(&parent, &Value::str(S_BANNO), Value::Noval);
    get_prop(
        &anno,
        &Value::str(S_KEY),
        anno_key.map(Value::Str).unwrap_or(Value::Noval),
    )
}

fn transform_anno(inj: &Inj, _v: &Value, _r: &str, _store: &Value) -> Value {
    let parent = inj.borrow().parent.clone();
    del_prop(parent, &Value::str(S_BANNO));
    Value::Noval
}

fn transform_merge(inj: &Inj, _v: &Value, _r: &str, _store: &Value) -> Value {
    let (mode, key, parent) = {
        let b = inj.borrow();
        (b.mode, b.key.clone(), b.parent.clone())
    };
    let mut out = Value::Noval;
    if mode == M_KEYPRE {
        out = Value::str(key);
    } else if mode == M_KEYPOST {
        out = Value::str(key.clone());
        let mut args = get_prop(&parent, &Value::str(key.clone()), Value::Noval);
        if !is_list(&args) {
            args = Value::list(vec![args]);
        }
        Injection::setval(inj, Value::Noval, None); // remove $MERGE key from parent
        let args_vec: Vec<Value> = args
            .as_list()
            .map(|l| l.borrow().clone())
            .unwrap_or_default();
        let mut mergelist: Vec<Value> = vec![parent.clone()];
        mergelist.extend(args_vec);
        mergelist.push(clone(&parent));
        merge(&Value::list(mergelist), Some(1));
    }
    out
}

fn slice_str_vec(v: &[String], start: Option<i64>, end: Option<i64>) -> Vec<String> {
    match slice(path_value(v), start, end, false) {
        Value::List(l) => l
            .borrow()
            .iter()
            .map(|x| x.as_str().map(|s| s.to_string()).unwrap_or_default())
            .collect(),
        _ => Vec::new(),
    }
}

// `$REF` — reference the original spec (enables recursive transforms).
fn transform_ref(inj: &Inj, val: &Value, _r: &str, store: &Value) -> Value {
    let (mode, parent, path, nodes) = {
        let b = inj.borrow();
        (b.mode, b.parent.clone(), b.path.clone(), b.nodes.clone())
    };
    if mode != M_VAL {
        return Value::Noval;
    }
    // Group B raw read of the ref arg (canonical `_lookup(inj.parent, 1)`).
    let refpath = lookup(&parent, &Value::Num(1.0));
    {
        let keylen = inj.borrow().keys.borrow().len() as i64;
        inj.borrow_mut().key_i = keylen;
    }
    // spec = ($SPEC)()
    let spec = {
        let sf = get_prop(store, &Value::str(S_DSPEC), Value::Noval);
        match &sf {
            Value::Func(f) => f(inj, &Value::Noval, "", store),
            _ => Value::Noval,
        }
    };
    let dpath = slice_str_vec(&path, Some(1), None);
    let dparent_for_ref = get_path_inj(&spec, &path_value(&dpath), None);
    let ref_def = InjectDef {
        dpath: Some(dpath.clone()),
        dparent: Some(dparent_for_ref),
        ..Default::default()
    };
    let refval = get_path(&spec, &refpath, Some(&ref_def));

    let mut has_sub_ref = false;
    if is_node(&refval) {
        let mut probe = |_k: &Value, v: &Value, _p: &Value, _t: &[String]| -> Value {
            if matches!(v, Value::Str(s) if s == "`$REF`") {
                has_sub_ref = true;
            }
            v.clone()
        };
        walk(refval.clone(), Some(&mut probe), None, None);
    }

    let tref = clone(&refval);
    let cpath = slice_str_vec(&path, Some(-3), None);
    let tpath = slice_str_vec(&path, Some(-1), None);
    let tcur = get_path_inj(store, &path_value(&cpath), None);
    let tval_at = get_path_inj(store, &path_value(&tpath), None);

    let rval = if !has_sub_ref || !tval_at.is_noval() {
        let tinj = Injection::child(
            inj,
            0,
            Rc::new(RefCell::new(vec![tpath
                .last()
                .cloned()
                .unwrap_or_default()])),
        );
        {
            let mut b = tinj.borrow_mut();
            b.path = tpath.clone();
            let nlen = nodes.len();
            b.nodes = if nlen >= 1 {
                nodes[..nlen - 1].to_vec()
            } else {
                Vec::new()
            };
            b.parent = if nlen >= 2 {
                nodes[nlen - 2].clone()
            } else {
                Value::Noval
            };
            b.val = tref.clone();
            b.dpath = cpath.clone();
            b.dparent = tcur.clone();
        }
        let _ = inject_inj(tref.clone(), store, &tinj);
        let v = tinj.borrow().val.clone();
        v
    } else {
        Value::Noval
    };

    let grandparent = Injection::setval(inj, rval, Some(2));
    if is_list(&grandparent) {
        let prior = inj.borrow().prior.clone();
        if let Some(p) = prior {
            p.borrow_mut().key_i -= 1;
        }
    }
    val.clone()
}

fn srcpath_split(srcpath: &str) -> Vec<String> {
    srcpath.split('.').map(|s| s.to_string()).collect()
}

// `$EACH` — apply a child template to every entry of a list or map.
// Spec form (a list): ['`$EACH`', 'source-path', child-template]
fn transform_each(inj: &Inj, _val: &Value, _r: &str, store: &Value) -> Value {
    if !check_placement(M_VAL, "EACH", T_LIST as i64, inj) {
        return Value::Noval;
    }
    // remove remaining keys to avoid spurious processing
    inj.borrow().keys.borrow_mut().truncate(1);

    let (parent, path, nodes, base) = {
        let b = inj.borrow();
        (
            b.parent.clone(),
            b.path.clone(),
            b.nodes.clone(),
            b.base.clone(),
        )
    };
    let args: Vec<Value> = slice(parent.clone(), Some(1), None, false)
        .as_list()
        .map(|l| l.borrow().clone())
        .unwrap_or_default();
    let ia = injector_args(&[T_STRING as i64, T_ANY as i64], &args);
    if let Value::Str(e) = &ia[0] {
        errs_push(inj, format!("$EACH: {e}"));
        return Value::Noval;
    }
    let srcpath = ia.get(1).cloned().unwrap_or(Value::Noval);
    let child = ia.get(2).cloned().unwrap_or(Value::Noval);
    let srcpath_str = srcpath.as_str().unwrap_or("").to_string();

    let srcstore = get_prop(
        store,
        &Value::str(base.clone().unwrap_or_default()),
        store.clone(),
    );
    let src = get_path_inj(&srcstore, &srcpath, Some(inj));
    let srctype = typify(&src);

    let tkey = path
        .get(path.len().saturating_sub(2))
        .cloned()
        .unwrap_or_default();
    let nlen = nodes.len();
    let target = if nlen >= 2 {
        nodes[nlen - 2].clone()
    } else if nlen >= 1 {
        nodes[nlen - 1].clone()
    } else {
        Value::Noval
    };

    let tval: Vec<Value> = if srctype & (T_LIST as i64) != 0 {
        items_vec(&src).iter().map(|_| clone(&child)).collect()
    } else if srctype & (T_MAP as i64) != 0 {
        items_vec(&src)
            .iter()
            .map(|(k, _)| {
                merge(
                    &Value::list(vec![
                        clone(&child),
                        Value::map_of([(
                            S_BANNO.to_string(),
                            Value::map_of([(S_KEY.to_string(), Value::str(k.clone()))]),
                        )]),
                    ]),
                    Some(1),
                )
            })
            .collect()
    } else {
        Vec::new()
    };

    let mut rval = Value::empty_list();
    if !tval.is_empty() {
        let tcur_inner: Value = if src.is_nullish() {
            Value::Noval
        } else {
            Value::list(items_vec(&src).into_iter().map(|(_, v)| v).collect())
        };
        let ckey = path
            .get(path.len().saturating_sub(2))
            .cloned()
            .unwrap_or_default();
        let tpath = slice_str_vec(&path, Some(-1), None);
        let mut dpath: Vec<String> = vec![S_DTOP.to_string()];
        dpath.extend(srcpath_split(&srcpath_str));
        dpath.push(format!("$:{ckey}"));

        let mut tcur = Value::map_of([(ckey.clone(), tcur_inner)]);
        if tpath.len() > 1 {
            let pkey = path
                .get(path.len().saturating_sub(3))
                .cloned()
                .unwrap_or_else(|| S_DTOP.to_string());
            tcur = Value::map_of([(pkey.clone(), tcur)]);
            dpath.push(format!("$:{pkey}"));
        }

        let tval_v = Value::list(tval);
        let tinj = Injection::child(inj, 0, Rc::new(RefCell::new(vec![ckey.clone()])));
        {
            let mut b = tinj.borrow_mut();
            b.path = tpath;
            b.nodes = if nlen >= 1 {
                nodes[..nlen - 1].to_vec()
            } else {
                Vec::new()
            };
            b.parent = b.nodes.last().cloned().unwrap_or(Value::Noval);
            b.val = tval_v.clone();
            b.dpath = dpath;
            b.dparent = tcur;
        }
        let pclone = tinj.borrow().parent.clone();
        set_prop(pclone, &Value::str(ckey), tval_v.clone());
        let _ = inject_inj(tval_v.clone(), store, &tinj);
        rval = tinj.borrow().val.clone();
    }

    set_prop(target, &Value::str(tkey), rval.clone());
    get_prop(&rval, &Value::Num(0.0), Value::Noval)
}

// `$PACK` — repack a list/map into a map keyed by `$KEY`.
// Spec form (a map): { '`$PACK`': ['source-path', child-template] }
fn transform_pack(inj: &Inj, _val: &Value, _r: &str, store: &Value) -> Value {
    if !check_placement(M_KEYPRE, "EACH", T_MAP as i64, inj) {
        return Value::Noval;
    }
    let (key, parent, path, nodes, base) = {
        let b = inj.borrow();
        (
            b.key.clone(),
            b.parent.clone(),
            b.path.clone(),
            b.nodes.clone(),
            b.base.clone(),
        )
    };
    let args = get_prop(&parent, &Value::str(key), Value::Noval);
    let args_vec: Vec<Value> = args
        .as_list()
        .map(|l| l.borrow().clone())
        .unwrap_or_default();
    let ia = injector_args(&[T_STRING as i64, T_ANY as i64], &args_vec);
    if let Value::Str(e) = &ia[0] {
        errs_push(inj, format!("$EACH: {e}"));
        return Value::Noval;
    }
    let srcpath = ia.get(1).cloned().unwrap_or(Value::Noval);
    let origchildspec = ia.get(2).cloned().unwrap_or(Value::Noval);
    let srcpath_str = srcpath.as_str().unwrap_or("").to_string();

    let tkey = path
        .get(path.len().saturating_sub(2))
        .cloned()
        .unwrap_or_default();
    let pathsize = path.len();
    let nlen = nodes.len();
    let target = if pathsize >= 2 {
        nodes.get(pathsize - 2).cloned().unwrap_or(Value::Noval)
    } else {
        nodes
            .get(pathsize.saturating_sub(1))
            .cloned()
            .unwrap_or(Value::Noval)
    };
    let target = if target.is_noval() {
        nodes
            .get(pathsize.saturating_sub(1))
            .cloned()
            .unwrap_or(Value::Noval)
    } else {
        target
    };

    let srcstore = get_prop(
        store,
        &Value::str(base.clone().unwrap_or_default()),
        store.clone(),
    );
    let src_raw = get_path_inj(&srcstore, &srcpath, Some(inj));
    let src: Value = if is_list(&src_raw) {
        src_raw
    } else if is_map(&src_raw) {
        Value::list(
            items_vec(&src_raw)
                .into_iter()
                .map(|(k, v)| {
                    set_prop(
                        v.clone(),
                        &Value::str(S_BANNO),
                        Value::map_of([(S_KEY.to_string(), Value::str(k))]),
                    );
                    v
                })
                .collect(),
        )
    } else {
        return Value::Noval;
    };
    if src.is_nullish() {
        return Value::Noval;
    }

    let keypath = get_prop(&origchildspec, &Value::str(S_BKEY), Value::Noval);
    let childspec = del_prop(origchildspec.clone(), &Value::str(S_BKEY));
    let child = get_prop(&childspec, &Value::str(S_BVAL), childspec.clone());

    let resolve_key = |srckey: &str, srcnode: &Value| -> Value {
        if keypath.is_noval() {
            Value::str(srckey)
        } else if let Value::Str(kp) = &keypath {
            if kp.starts_with('`') {
                let m = merge(
                    &Value::list(vec![
                        Value::empty_map(),
                        store.clone(),
                        Value::map_of([(S_DTOP.to_string(), srcnode.clone())]),
                    ]),
                    Some(1),
                );
                inject(Value::str(kp.clone()), &m, None)
            } else {
                get_path_inj(srcnode, &Value::str(kp.clone()), Some(inj))
            }
        } else {
            Value::str(srckey)
        }
    };

    let tval = Value::empty_map();
    for (srckey, srcnode) in items_vec(&src) {
        let k = resolve_key(&srckey, &srcnode);
        let tchild = clone(&child);
        set_prop(tval.clone(), &k, tchild.clone());
        let anno = get_prop(&srcnode, &Value::str(S_BANNO), Value::Noval);
        if anno.is_noval() {
            del_prop(tchild, &Value::str(S_BANNO));
        } else {
            set_prop(tchild, &Value::str(S_BANNO), anno);
        }
    }

    let mut rval = Value::empty_map();
    if !is_empty(&tval) {
        let tsrc = Value::empty_map();
        for (i, (_, n)) in items_vec(&src).into_iter().enumerate() {
            let kn = if keypath.is_noval() {
                Value::Num(i as f64)
            } else {
                resolve_key("", &n)
            };
            set_prop(tsrc.clone(), &kn, n);
        }
        let tpath = slice_str_vec(&path, Some(-1), None);
        let ckey = path
            .get(path.len().saturating_sub(2))
            .cloned()
            .unwrap_or_default();
        let mut dpath: Vec<String> = vec![S_DTOP.to_string()];
        dpath.extend(srcpath_split(&srcpath_str));
        dpath.push(format!("$:{ckey}"));
        let mut tcur = Value::map_of([(ckey.clone(), tsrc)]);
        if tpath.len() > 1 {
            let pkey = path
                .get(path.len().saturating_sub(3))
                .cloned()
                .unwrap_or_else(|| S_DTOP.to_string());
            tcur = Value::map_of([(pkey.clone(), tcur)]);
            dpath.push(format!("$:{pkey}"));
        }
        let tinj = Injection::child(inj, 0, Rc::new(RefCell::new(vec![ckey.clone()])));
        {
            let mut b = tinj.borrow_mut();
            b.path = tpath;
            b.nodes = if nlen >= 1 {
                nodes[..nlen - 1].to_vec()
            } else {
                Vec::new()
            };
            b.parent = b.nodes.last().cloned().unwrap_or(Value::Noval);
            b.val = tval.clone();
            b.dpath = dpath;
            b.dparent = tcur;
        }
        let _ = inject_inj(tval.clone(), store, &tinj);
        rval = tinj.borrow().val.clone();
    }

    set_prop(target, &Value::str(tkey), rval);
    Value::Noval
}

pub fn transform(
    data: &Value,
    spec: &Value,
    injdef: Option<&InjectDef>,
) -> Result<Value, StructError> {
    let origspec = spec.clone();
    let spec_clone = clone(&origspec);

    let extra = injdef.and_then(|d| d.extra.clone());
    let collect = injdef.map(|d| d.errs.is_some()).unwrap_or(false);
    let errs = injdef
        .and_then(|d| d.errs.clone())
        .unwrap_or_else(Value::empty_list);

    // split `extra` into data-extras (non-$) and transform-extras ($)
    let mut extra_transforms = OrderedMap::new();
    let extra_data: Value = match &extra {
        None => Value::Noval,
        Some(e) => {
            let mut a = OrderedMap::new();
            for (k, v) in items_vec(e) {
                if k.starts_with(S_DS) {
                    extra_transforms.insert(k, v);
                } else {
                    a.insert(k, v);
                }
            }
            Value::map(a)
        }
    };

    let data_clone = merge(
        &Value::list(vec![
            if is_empty(&extra_data) {
                Value::Noval
            } else {
                clone(&extra_data)
            },
            clone(data),
        ]),
        None,
    );

    // build the transform store
    let origspec_for_thunk = origspec.clone();
    let mut store_base: OrderedMap<Value> = OrderedMap::new();
    store_base.insert(S_DTOP.to_string(), data_clone);
    store_base.insert(
        "$SPEC".to_string(),
        Value::func(move |_i: &Inj, _v: &Value, _r: &str, _s: &Value| origspec_for_thunk.clone()),
    );
    store_base.insert(
        "$BT".to_string(),
        Value::func(|_i: &Inj, _v: &Value, _r: &str, _s: &Value| Value::str(S_BT)),
    );
    store_base.insert(
        "$DS".to_string(),
        Value::func(|_i: &Inj, _v: &Value, _r: &str, _s: &Value| Value::str(S_DS)),
    );
    store_base.insert(
        "$WHEN".to_string(),
        Value::func(|_i: &Inj, _v: &Value, _r: &str, _s: &Value| Value::str(iso_now())),
    );
    store_base.insert("$DELETE".to_string(), Value::func(transform_delete));
    store_base.insert("$COPY".to_string(), Value::func(transform_copy));
    store_base.insert("$KEY".to_string(), Value::func(transform_key));
    store_base.insert("$ANNO".to_string(), Value::func(transform_anno));
    store_base.insert("$MERGE".to_string(), Value::func(transform_merge));
    store_base.insert("$EACH".to_string(), Value::func(transform_each));
    store_base.insert("$PACK".to_string(), Value::func(transform_pack));
    store_base.insert("$REF".to_string(), Value::func(transform_ref));
    store_base.insert("$FORMAT".to_string(), Value::func(transform_format));
    store_base.insert("$APPLY".to_string(), Value::func(transform_apply));

    let store = merge(
        &Value::list(vec![
            Value::map(store_base),
            Value::map(extra_transforms),
            Value::map_of([(S_DERRS.to_string(), errs.clone())]),
        ]),
        Some(1),
    );

    let out = inject(spec_clone, &store, injdef);

    let errlen = errs.as_list().map(|l| l.borrow().len()).unwrap_or(0);
    if errlen > 0 && !collect {
        let msgs: Vec<String> = errs
            .as_list()
            .map(|l| l.borrow().iter().map(js_string).collect())
            .unwrap_or_default();
        return Err(StructError {
            message: msgs.join(" | "),
        });
    }

    Ok(out)
}

fn iso_now() -> String {
    // best-effort ISO-8601 UTC string; the corpus can't assert the exact
    // value (it changes), so granularity to the second is fine.
    use std::time::{SystemTime, UNIX_EPOCH};
    let dur = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap_or_default();
    let secs = dur.as_secs() as i64;
    let millis = dur.subsec_millis();
    // days since 1970-01-01
    let days = secs.div_euclid(86_400);
    let tod = secs.rem_euclid(86_400);
    let (h, m, s) = (tod / 3600, (tod % 3600) / 60, tod % 60);
    let (y, mo, d) = civil_from_days(days);
    format!("{y:04}-{mo:02}-{d:02}T{h:02}:{m:02}:{s:02}.{millis:03}Z")
}

fn civil_from_days(z: i64) -> (i64, i64, i64) {
    // Howard Hinnant's algorithm.
    let z = z + 719_468;
    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
    let doe = z - era * 146_097;
    let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
    let y = yoe + era * 400;
    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
    let mp = (5 * doy + 2) / 153;
    let d = doy - (153 * mp + 2) / 5 + 1;
    let m = if mp < 10 { mp + 3 } else { mp - 9 };
    (if m <= 2 { y + 1 } else { y }, m, d)
}

// ---- validate --------------------------------------------------------

fn path_value(path: &[String]) -> Value {
    Value::list(path.iter().cloned().map(Value::Str).collect())
}

fn invalid_type_msg(path: &[String], needtype: &str, vt: i64, v: &Value) -> String {
    let vs = if v.is_nullish() {
        "no value".to_string()
    } else {
        stringify(v, None, false)
    };
    let field_part = if path.len() > 1 {
        format!("field {} to be ", pathify(&path_value(path), Some(1), None))
    } else {
        String::new()
    };
    let type_part = if !v.is_nullish() {
        format!("{}{}", type_name(vt), S_VIZ)
    } else {
        String::new()
    };
    format!("Expected {field_part}{needtype}, but found {type_part}{vs}.")
}

fn validate_string(inj: &Inj, _v: &Value, _r: &str, _store: &Value) -> Value {
    let (dparent, key, path) = {
        let b = inj.borrow();
        (b.dparent.clone(), b.key.clone(), b.path.clone())
    };
    let out = lookup(&dparent, &Value::str(key));
    let t = typify(&out);
    if t & (T_STRING as i64) == 0 {
        errs_push(inj, invalid_type_msg(&path, "string", t, &out));
        return Value::Noval;
    }
    if matches!(&out, Value::Str(s) if s.is_empty()) {
        errs_push(
            inj,
            format!(
                "Empty string at {}",
                pathify(&path_value(&path), Some(1), None)
            ),
        );
        return Value::Noval;
    }
    out
}

fn validate_type(inj: &Inj, _v: &Value, r: &str, _store: &Value) -> Value {
    let tname: String = r.chars().skip(1).collect::<String>().to_lowercase();
    let typev: i64 = match TYPENAME.iter().position(|x| *x == tname) {
        Some(idx) => 1i64 << (31 - idx as i64),
        None => 0,
    };
    let (dparent, key, path) = {
        let b = inj.borrow();
        (b.dparent.clone(), b.key.clone(), b.path.clone())
    };
    let out = lookup(&dparent, &Value::str(key));
    let t = typify(&out);
    if t & typev == 0 {
        errs_push(inj, invalid_type_msg(&path, &tname, t, &out));
        return Value::Noval;
    }
    out
}

fn validate_any(inj: &Inj, _v: &Value, _r: &str, _store: &Value) -> Value {
    let (dparent, key) = {
        let b = inj.borrow();
        (b.dparent.clone(), b.key.clone())
    };
    lookup(&dparent, &Value::str(key))
}

/// Render a list of tvals as `"a, b, c"`, lowering `` `$NAME` `` -> `name`.
fn tvals_desc(tvals: &[Value]) -> String {
    let joined = tvals
        .iter()
        .map(|v| stringify(v, None, false))
        .collect::<Vec<_>>()
        .join(", ");
    R_TRANSFORM_NAME
        .replace_all(&joined, |caps: &crate::re::Captures<'_>| {
            caps[1].to_lowercase()
        })
        .to_string()
}

// Map / list `$CHILD`: apply a child template to every direct child.
fn validate_child(inj: &Inj, _v: &Value, _r: &str, _store: &Value) -> Value {
    let (mode, key, parent, path, dparent) = {
        let b = inj.borrow();
        (
            b.mode,
            b.key.clone(),
            b.parent.clone(),
            b.path.clone(),
            b.dparent.clone(),
        )
    };

    if mode == M_KEYPRE {
        let childtm = get_prop(&parent, &Value::str(key), Value::Noval);
        let pkey = path
            .get(path.len().saturating_sub(2))
            .cloned()
            .unwrap_or_default();
        let mut tval = get_prop(&dparent, &Value::str(pkey), Value::Noval);
        if tval.is_noval() {
            tval = Value::empty_map();
        } else if !is_map(&tval) {
            errs_push(
                inj,
                invalid_type_msg(
                    &path[..path.len().saturating_sub(1)],
                    S_object,
                    typify(&tval),
                    &tval,
                ),
            );
            return Value::Noval;
        }
        let ckeys = keysof_vec(&tval);
        for ck in ckeys {
            set_prop(parent.clone(), &Value::str(ck.clone()), clone(&childtm));
            inj.borrow().keys.borrow_mut().push(ck);
        }
        Injection::setval(inj, Value::Noval, None);
        return Value::Noval;
    }

    if mode == M_VAL {
        if !is_list(&parent) {
            errs_push(inj, "Invalid $CHILD as value".to_string());
            return Value::Noval;
        }
        // List $CHILD template (canonical `_lookup(parent, 1)`): preserve a
        // null template literally rather than dropping it as Group A would.
        let childtm = lookup(&parent, &Value::Num(1.0));
        if dparent.is_noval() {
            slice(parent.clone(), Some(0), Some(0), true); // empty default
            return Value::Noval;
        }
        if !is_list(&dparent) {
            errs_push(
                inj,
                invalid_type_msg(
                    &path[..path.len().saturating_sub(1)],
                    S_list,
                    typify(&dparent),
                    &dparent,
                ),
            );
            let plen = parent.as_list().map(|l| l.borrow().len()).unwrap_or(0) as i64;
            inj.borrow_mut().key_i = plen;
            return dparent;
        }
        let dlen = dparent.as_list().map(|l| l.borrow().len()).unwrap_or(0);
        for n in 0..dlen {
            set_prop(parent.clone(), &Value::Num(n as f64), clone(&childtm));
        }
        slice(parent.clone(), Some(0), Some(dlen as i64), true);

        // NOTE: modifying inj! This extends the child value loop in inject
        // to cover every cloned child.
        {
            let keys = inj.borrow().keys.clone();
            let plen = parent.as_list().map(|l| l.borrow().len()).unwrap_or(0);
            let mut ks = keys.borrow_mut();
            for ckey_i in ks.len()..plen {
                ks.push(str_key(Value::Num(ckey_i as f64)));
            }
        }

        // Restart the child value loop at the first element (the loop
        // increments key_i on resume) so that the first element is also
        // validated against the child template.
        inj.borrow_mut().key_i = -1;

        // SKIP leaves the cloned child template in place at the first
        // element so the resumed loop can validate it.
        return Value::skip();
    }

    Value::Noval
}

// `$ONE`: value must match exactly one of a list of alternative sub-specs.
fn validate_one(inj: &Inj, _v: &Value, _r: &str, store: &Value) -> Value {
    let (mode, parent, key_i) = {
        let b = inj.borrow();
        (b.mode, b.parent.clone(), b.key_i)
    };
    if mode != M_VAL {
        return Value::Noval;
    }
    if !is_list(&parent) || key_i != 0 {
        let path = inj.borrow().path.clone();
        errs_push(
            inj,
            format!(
                "The $ONE validator at field {} must be the first element of an array.",
                pathify(&path_value(&path), Some(1), Some(1))
            ),
        );
        return Value::Noval;
    }
    let keylen = inj.borrow().keys.borrow().len() as i64;
    inj.borrow_mut().key_i = keylen;
    let dparent = inj.borrow().dparent.clone();
    Injection::setval(inj, dparent.clone(), Some(2));
    {
        let mut b = inj.borrow_mut();
        let n = b.path.len();
        b.path.truncate(n.saturating_sub(1));
        b.key = b.path.last().cloned().unwrap_or_default();
    }
    let path_after = inj.borrow().path.clone();
    let meta = inj.borrow().meta.clone();
    let tvals: Vec<Value> = slice(parent.clone(), Some(1), None, false)
        .as_list()
        .map(|l| l.borrow().clone())
        .unwrap_or_default();
    if tvals.is_empty() {
        errs_push(
            inj,
            format!(
                "The $ONE validator at field {} must have at least one argument.",
                pathify(&path_value(&path_after), Some(1), Some(1))
            ),
        );
        return Value::Noval;
    }
    for tval in &tvals {
        let terrs = Value::empty_list();
        let mut vstore = match merge(
            &Value::list(vec![Value::empty_map(), store.clone()]),
            Some(1),
        ) {
            v @ Value::Map(_) => v,
            _ => Value::empty_map(),
        };
        set_prop(vstore.clone(), &Value::str(S_DTOP), dparent.clone());
        let _ = &mut vstore;
        let vd = InjectDef {
            extra: Some(vstore.clone()),
            errs: Some(terrs.clone()),
            meta: Some(meta.clone()),
            ..Default::default()
        };
        let vcur = validate(&dparent, tval, Some(&vd)).unwrap_or(Value::Noval);
        Injection::setval(inj, vcur, Some(-2)); // hmm: ancestor -2 -> handled below
        let terrlen = terrs.as_list().map(|l| l.borrow().len()).unwrap_or(0);
        if terrlen == 0 {
            return Value::Noval;
        }
    }
    let valdesc = tvals_desc(&tvals);
    errs_push(
        inj,
        invalid_type_msg(
            &path_after,
            &format!(
                "{}{}",
                if tvals.len() > 1 { "one of " } else { "" },
                valdesc
            ),
            typify(&dparent),
            &dparent,
        ),
    );
    Value::Noval
}

// `$EXACT`: value must equal a literal exactly (no shape coercion).
fn validate_exact(inj: &Inj, _v: &Value, _r: &str, _store: &Value) -> Value {
    let (mode, parent, key, key_i) = {
        let b = inj.borrow();
        (b.mode, b.parent.clone(), b.key.clone(), b.key_i)
    };
    if mode != M_VAL {
        del_prop(parent, &Value::str(key));
        return Value::Noval;
    }
    if !is_list(&parent) || key_i != 0 {
        let path = inj.borrow().path.clone();
        errs_push(
            inj,
            format!(
                "The $EXACT validator at field {} must be the first element of an array.",
                pathify(&path_value(&path), Some(1), Some(1))
            ),
        );
        return Value::Noval;
    }
    let keylen = inj.borrow().keys.borrow().len() as i64;
    inj.borrow_mut().key_i = keylen;
    let dparent = inj.borrow().dparent.clone();
    Injection::setval(inj, dparent.clone(), Some(2));
    {
        let mut b = inj.borrow_mut();
        let n = b.path.len();
        b.path.truncate(n.saturating_sub(1));
        b.key = b.path.last().cloned().unwrap_or_default();
    }
    let path_after = inj.borrow().path.clone();
    let tvals: Vec<Value> = slice(parent.clone(), Some(1), None, false)
        .as_list()
        .map(|l| l.borrow().clone())
        .unwrap_or_default();
    if tvals.is_empty() {
        errs_push(
            inj,
            format!(
                "The $EXACT validator at field {} must have at least one argument.",
                pathify(&path_value(&path_after), Some(1), Some(1))
            ),
        );
        return Value::Noval;
    }
    let mut currentstr: Option<String> = None;
    for tval in &tvals {
        let mut exactmatch = tval == &dparent;
        if !exactmatch && is_node(tval) {
            let cs = currentstr
                .get_or_insert_with(|| stringify(&dparent, None, false))
                .clone();
            exactmatch = stringify(tval, None, false) == cs;
        }
        if exactmatch {
            return Value::Noval;
        }
    }
    let valdesc = tvals_desc(&tvals);
    let need = format!(
        "{}exactly equal to {}{}",
        if path_after.len() > 1 { "" } else { "value " },
        if tvals.len() == 1 { "" } else { "one of " },
        valdesc
    );
    errs_push(
        inj,
        invalid_type_msg(&path_after, &need, typify(&dparent), &dparent),
    );
    Value::Noval
}

/// `_validation` — the modify hook installed by `validate` (runs after the
/// per-key special commands).
fn validation_modify(pval: &Value, key: &Value, parent: &Value, inj: &Inj, _store: &Value) {
    if pval.is_skip() {
        return;
    }
    let (meta, dparent, path) = {
        let b = inj.borrow();
        (b.meta.clone(), b.dparent.clone(), b.path.clone())
    };
    let exact = matches!(
        get_prop(&meta, &Value::str(S_BEXACT), Value::Bool(false)),
        Value::Bool(true)
    );
    let cval = get_prop(&dparent, key, Value::Noval);
    if !exact && cval.is_noval() {
        return;
    }
    let ptype = typify(pval);
    if ptype & (T_STRING as i64) != 0 {
        if let Value::Str(s) = pval {
            if s.contains(S_DS) {
                return; // remaining special command — leave it
            }
        }
    }
    let ctype = typify(&cval);
    if ptype != ctype && !pval.is_noval() {
        errs_push(
            inj,
            invalid_type_msg(&path, &type_name(ptype), ctype, &cval),
        );
        return;
    }

    if is_map(&cval) {
        if !is_map(pval) {
            errs_push(
                inj,
                invalid_type_msg(&path, &type_name(ptype), ctype, &cval),
            );
            return;
        }
        let ckeys = keysof_vec(&cval);
        let pkeys = keysof_vec(pval);
        let open = matches!(
            get_prop(pval, &Value::str(S_BOPEN), Value::Noval),
            Value::Bool(true)
        );
        if !pkeys.is_empty() && !open {
            // Literal presence: the shape must be checked with a raw lookup
            // (canonical TS `NONE === _lookup(pval, ckey)`); the Group A
            // has_key would treat a null-valued shape slot as absent.
            let badkeys: Vec<String> = ckeys
                .iter()
                .filter(|ck| lookup(pval, &Value::str((*ck).clone())).is_noval())
                .cloned()
                .collect();
            if !badkeys.is_empty() {
                errs_push(
                    inj,
                    format!(
                        "Unexpected keys at field {}{}{}",
                        pathify(&path_value(&path), Some(1), None),
                        S_VIZ,
                        badkeys.join(", ")
                    ),
                );
            }
        } else {
            merge(&Value::list(vec![pval.clone(), cval.clone()]), None);
            if is_node(pval) {
                del_prop(pval.clone(), &Value::str(S_BOPEN));
            }
        }
    } else if is_list(&cval) {
        if !is_list(pval) {
            errs_push(
                inj,
                invalid_type_msg(&path, &type_name(ptype), ctype, &cval),
            );
        }
    } else if exact {
        if &cval != pval {
            let pathmsg = if path.len() > 1 {
                format!(
                    "at field {}{}",
                    pathify(&path_value(&path), Some(1), None),
                    S_VIZ
                )
            } else {
                String::new()
            };
            errs_push(
                inj,
                format!(
                    "Value {}{} should equal {}{}",
                    pathmsg,
                    js_string(&cval),
                    js_string(pval),
                    S_DT
                ),
            );
        }
    } else {
        set_prop(parent.clone(), key, cval.clone());
    }
}

/// `_validatehandler` — `getpath`/`_injectstr` handler installed by `validate`.
fn validatehandler(inj: &Inj, val: &Value, r: &str, store: &Value) -> Value {
    if let Some(caps) = R_META_PATH.captures(r) {
        if &caps[2] == "=" {
            Injection::setval(
                inj,
                Value::list(vec![Value::str(S_BEXACT), val.clone()]),
                None,
            );
        } else {
            Injection::setval(inj, val.clone(), None);
        }
        inj.borrow_mut().key_i = -1;
        return Value::skip();
    }
    inject_handler(inj, val, r, store)
}

pub fn validate(
    data: &Value,
    spec: &Value,
    injdef: Option<&InjectDef>,
) -> Result<Value, StructError> {
    let extra = injdef.and_then(|d| d.extra.clone());
    let collect = injdef.map(|d| d.errs.is_some()).unwrap_or(false);
    let errs = injdef
        .and_then(|d| d.errs.clone())
        .unwrap_or_else(Value::empty_list);

    // build the validator store
    let mut vmap: OrderedMap<Value> = OrderedMap::new();
    for k in [
        "$DELETE", "$COPY", "$KEY", "$META", "$MERGE", "$EACH", "$PACK",
    ] {
        vmap.insert(k.to_string(), Value::Null);
    }
    vmap.insert("$STRING".to_string(), Value::func(validate_string));
    for k in [
        "$NUMBER",
        "$INTEGER",
        "$DECIMAL",
        "$BOOLEAN",
        "$NULL",
        "$NIL",
        "$MAP",
        "$LIST",
        "$FUNCTION",
        "$INSTANCE",
    ] {
        vmap.insert(k.to_string(), Value::func(validate_type));
    }
    vmap.insert("$ANY".to_string(), Value::func(validate_any));
    vmap.insert("$CHILD".to_string(), Value::func(validate_child));
    vmap.insert("$ONE".to_string(), Value::func(validate_one));
    vmap.insert("$EXACT".to_string(), Value::func(validate_exact));

    let extra_or_empty = match &extra {
        Some(e) => e.clone(),
        None => Value::empty_map(),
    };
    let store = merge(
        &Value::list(vec![
            Value::map(vmap),
            extra_or_empty,
            Value::map_of([(S_DERRS.to_string(), errs.clone())]),
        ]),
        Some(1),
    );

    let meta = match injdef.and_then(|d| d.meta.clone()) {
        Some(m) => m,
        None => Value::empty_map(),
    };
    let exact_cur = get_prop(&meta, &Value::str(S_BEXACT), Value::Bool(false));
    set_prop(meta.clone(), &Value::str(S_BEXACT), exact_cur);

    let td = InjectDef {
        meta: Some(meta),
        extra: Some(store),
        modify: Some(Rc::new(validation_modify) as Modify),
        handler: Some(Rc::new(validatehandler) as NativeFn),
        errs: Some(errs.clone()),
        ..Default::default()
    };

    let out = transform(data, spec, Some(&td)).unwrap_or(Value::Noval);

    let errlen = errs.as_list().map(|l| l.borrow().len()).unwrap_or(0);
    if errlen > 0 && !collect {
        let msgs: Vec<String> = errs
            .as_list()
            .map(|l| l.borrow().iter().map(js_string).collect())
            .unwrap_or_default();
        return Err(StructError {
            message: msgs.join(" | "),
        });
    }

    Ok(out)
}

// ---- select ----------------------------------------------------------

fn js_lt(a: &Value, b: &Value) -> bool {
    match (a, b) {
        (Value::Str(x), Value::Str(y)) => x < y,
        _ => {
            let (x, y) = (js_to_number(a), js_to_number(b));
            x < y // NaN -> false, matches JS
        }
    }
}
fn js_gt(a: &Value, b: &Value) -> bool {
    match (a, b) {
        (Value::Str(x), Value::Str(y)) => x > y,
        _ => {
            let (x, y) = (js_to_number(a), js_to_number(b));
            x > y
        }
    }
}

fn select_subvalidate(point: &Value, term: &Value, store: &Value, meta: &Value) -> bool {
    let vstore = match merge(
        &Value::list(vec![Value::empty_map(), store.clone()]),
        Some(1),
    ) {
        v @ Value::Map(_) => v,
        _ => Value::empty_map(),
    };
    set_prop(vstore.clone(), &Value::str(S_DTOP), point.clone());
    let terrs = Value::empty_list();
    let vd = InjectDef {
        extra: Some(vstore),
        errs: Some(terrs.clone()),
        meta: Some(meta.clone()),
        ..Default::default()
    };
    let _ = validate(point, term, Some(&vd));
    terrs
        .as_list()
        .map(|l| l.borrow().is_empty())
        .unwrap_or(true)
}

fn select_and(inj: &Inj, _v: &Value, _r: &str, store: &Value) -> Value {
    if inj.borrow().mode != M_KEYPRE {
        return Value::Noval;
    }
    let (key, parent, path, nodes, meta) = {
        let b = inj.borrow();
        (
            b.key.clone(),
            b.parent.clone(),
            b.path.clone(),
            b.nodes.clone(),
            b.meta.clone(),
        )
    };
    let terms: Vec<Value> = lookup(&parent, &Value::str(key))
        .as_list()
        .map(|l| l.borrow().clone())
        .unwrap_or_default();
    let ppath = slice_str_vec(&path, Some(-1), None);
    let point = get_path_inj(store, &path_value(&ppath), None);
    for term in &terms {
        if !select_subvalidate(&point, term, store, &meta) {
            errs_push(
                inj,
                format!(
                    "AND:{}{}{} fail:{}",
                    pathify(&path_value(&ppath), None, None),
                    S_VIZ,
                    stringify(&point, None, false),
                    stringify(&Value::list(terms.clone()), None, false)
                ),
            );
        }
    }
    let gkey = path
        .get(path.len().saturating_sub(2))
        .cloned()
        .unwrap_or_default();
    let nlen = nodes.len();
    if nlen >= 2 {
        set_prop(nodes[nlen - 2].clone(), &Value::str(gkey), point);
    }
    Value::Noval
}

fn select_or(inj: &Inj, _v: &Value, _r: &str, store: &Value) -> Value {
    if inj.borrow().mode != M_KEYPRE {
        return Value::Noval;
    }
    let (key, parent, path, nodes, meta) = {
        let b = inj.borrow();
        (
            b.key.clone(),
            b.parent.clone(),
            b.path.clone(),
            b.nodes.clone(),
            b.meta.clone(),
        )
    };
    let terms: Vec<Value> = lookup(&parent, &Value::str(key))
        .as_list()
        .map(|l| l.borrow().clone())
        .unwrap_or_default();
    let ppath = slice_str_vec(&path, Some(-1), None);
    let point = get_path_inj(store, &path_value(&ppath), None);
    for term in &terms {
        if select_subvalidate(&point, term, store, &meta) {
            let gkey = path
                .get(path.len().saturating_sub(2))
                .cloned()
                .unwrap_or_default();
            let nlen = nodes.len();
            if nlen >= 2 {
                set_prop(nodes[nlen - 2].clone(), &Value::str(gkey), point);
            }
            return Value::Noval;
        }
    }
    errs_push(
        inj,
        format!(
            "OR:{}{}{} fail:{}",
            pathify(&path_value(&ppath), None, None),
            S_VIZ,
            stringify(&point, None, false),
            stringify(&Value::list(terms.clone()), None, false)
        ),
    );
    Value::Noval
}

fn select_not(inj: &Inj, _v: &Value, _r: &str, store: &Value) -> Value {
    if inj.borrow().mode != M_KEYPRE {
        return Value::Noval;
    }
    let (key, parent, path, nodes, meta) = {
        let b = inj.borrow();
        (
            b.key.clone(),
            b.parent.clone(),
            b.path.clone(),
            b.nodes.clone(),
            b.meta.clone(),
        )
    };
    let term = lookup(&parent, &Value::str(key));
    let ppath = slice_str_vec(&path, Some(-1), None);
    let point = get_path_inj(store, &path_value(&ppath), None);
    if select_subvalidate(&point, &term, store, &meta) {
        errs_push(
            inj,
            format!(
                "NOT:{}{}{} fail:{}",
                pathify(&path_value(&ppath), None, None),
                S_VIZ,
                stringify(&point, None, false),
                stringify(&term, None, false)
            ),
        );
    }
    let gkey = path
        .get(path.len().saturating_sub(2))
        .cloned()
        .unwrap_or_default();
    let nlen = nodes.len();
    if nlen >= 2 {
        set_prop(nodes[nlen - 2].clone(), &Value::str(gkey), point);
    }
    Value::Noval
}

fn select_cmp(inj: &Inj, _v: &Value, r: &str, store: &Value) -> Value {
    if inj.borrow().mode != M_KEYPRE {
        return Value::Noval;
    }
    let (key, parent, path, nodes) = {
        let b = inj.borrow();
        (
            b.key.clone(),
            b.parent.clone(),
            b.path.clone(),
            b.nodes.clone(),
        )
    };
    let term = lookup(&parent, &Value::str(key));
    let gkey = path
        .get(path.len().saturating_sub(2))
        .cloned()
        .unwrap_or_default();
    let ppath = slice_str_vec(&path, Some(-1), None);
    let point = get_path_inj(store, &path_value(&ppath), None);

    let pass = match r {
        "$GT" => js_gt(&point, &term),
        "$LT" => js_lt(&point, &term),
        "$GTE" => js_gt(&point, &term) || point == term,
        "$LTE" => js_lt(&point, &term) || point == term,
        "$LIKE" => {
            let pat = term.as_str().unwrap_or("").to_string();
            crate::re::Regex::new(&pat)
                .map(|re| re.is_match(&stringify(&point, None, false)))
                .unwrap_or(false)
        }
        _ => false,
    };

    if pass {
        let nlen = nodes.len();
        if nlen >= 2 {
            set_prop(nodes[nlen - 2].clone(), &Value::str(gkey), point);
        }
    } else {
        errs_push(
            inj,
            format!(
                "CMP: {}{}{} fail:{} {}",
                pathify(&path_value(&ppath), None, None),
                S_VIZ,
                stringify(&point, None, false),
                r,
                stringify(&term, None, false)
            ),
        );
    }
    Value::Noval
}

pub fn select(children: &Value, query: &Value) -> Value {
    if !is_node(children) {
        return Value::empty_list();
    }

    let child_list: Vec<Value> = match children {
        Value::Map(_) => items_vec(children)
            .into_iter()
            .map(|(k, v)| {
                set_prop(v.clone(), &Value::str(S_DKEY), Value::str(k));
                v
            })
            .collect(),
        Value::List(_) => items_vec(children)
            .into_iter()
            .map(|(k, v)| {
                set_prop(
                    v.clone(),
                    &Value::str(S_DKEY),
                    Value::Num(k.parse::<f64>().unwrap_or(f64::NAN)),
                );
                v
            })
            .collect(),
        _ => return Value::empty_list(),
    };

    let extra = Value::map_of([
        ("$AND".to_string(), Value::func(select_and)),
        ("$OR".to_string(), Value::func(select_or)),
        ("$NOT".to_string(), Value::func(select_not)),
        ("$GT".to_string(), Value::func(select_cmp)),
        ("$LT".to_string(), Value::func(select_cmp)),
        ("$GTE".to_string(), Value::func(select_cmp)),
        ("$LTE".to_string(), Value::func(select_cmp)),
        ("$LIKE".to_string(), Value::func(select_cmp)),
    ]);
    let meta = Value::map_of([(S_BEXACT.to_string(), Value::Bool(true))]);

    let q = clone(query);
    let mut open = |_k: &Value, v: &Value, _p: &Value, _t: &[String]| -> Value {
        if is_map(v) {
            let cur = get_prop(v, &Value::str(S_BOPEN), Value::Bool(true));
            set_prop(v.clone(), &Value::str(S_BOPEN), cur);
        }
        v.clone()
    };
    walk(q.clone(), Some(&mut open), None, None);

    let mut results: Vec<Value> = Vec::new();
    for child in &child_list {
        let errs = Value::empty_list();
        let vd = InjectDef {
            errs: Some(errs.clone()),
            meta: Some(meta.clone()),
            extra: Some(extra.clone()),
            ..Default::default()
        };
        let _ = validate(child, &clone(&q), Some(&vd));
        if errs
            .as_list()
            .map(|l| l.borrow().is_empty())
            .unwrap_or(true)
        {
            results.push(child.clone());
        }
    }
    Value::list(results)
}

// keep `Injection::has_handler` referenced (used once staging is complete)
#[allow(dead_code)]
fn _keepalive() {
    let _ = Injection::has_handler(None);
    let _ = inject_child as fn(Value, &Value, &Inj) -> Inj;
}