[FEAT][RUST] Add rust structural_visit and structural_walk.

[Seven-Streams]

A refreshed summary of the API as it now stands, since it has moved since the description above was written.

structural_walk(root, walker, order) walks a value graph and dispatches typed handlers in pre- or post-order; handlers steer the traversal through the returned WalkResult (Advance, Skip, Interrupt/InterruptWith(payload)) and may return Result<WalkResult> to propagate errors with ?. The walker can be:

• a &mut #[dispatch(visit)] visitor (or a hand-written VisitDispatch) — its visit_* methods dispatch on argument type in source order;
• a single closure over an FFI value type T (value cast), a borrowed object node &N (refcount-free subtype check), or the &VisitValue catch-all;
• a tuple of up to 8 such callbacks — closures and &mut visitors mixed freely — tried in order with the first matching argument type winning, the analog of the variadic C++ StructuralWalk(root, callbacks...) chain.

Every handler shape may declare a trailing DefRegionKind argument to receive the definition-region state:

use tvm_ffi::{structural_walk, Array, DefRegionKind, Object, WalkOrder, WalkResult};

let values = Array::new(vec![10_i64, 2]);
let mut total = 0_i64;
let mut objects = 0;
assert!(structural_walk(
    &values,
    (
        |value: i64| {
            total += value;
            WalkResult::Advance
        },
        |_object: &Object, _kind: DefRegionKind| {
            objects += 1;
            WalkResult::Advance
        },
    ),
    WalkOrder::PreOrder,
)
.unwrap()
.is_none());
assert_eq!((total, objects), (12, 1));

structural_visit(root, visitor) drives a hand-written StructuralVisitor when recursion itself is part of the analysis, mirroring a C++ StructuralVisitorObj: visit runs for each value and controls all descent through default_visit_children or visit_child(child, kind), whose explicit kind argument plays the role of WithDefRegionKind. Both entry points return Result<Option<VisitInterrupt>>: Ok(None) means the whole graph was visited, and an interrupting handler's payload comes back in Ok(Some(interrupt)):

use tvm_ffi::{
    structural_visit, Array, DefRegionKind, Result, StructuralVisitor, VisitInterrupt, VisitValue,
};

#[derive(Default)]
struct Depth {
    max: usize,
    current: usize,
}

impl StructuralVisitor for Depth {
    fn visit(
        &mut self,
        value: &VisitValue,
        def_region_kind: DefRegionKind,
    ) -> Result<Option<VisitInterrupt>> {
        self.current += 1;
        self.max = self.max.max(self.current);
        let interrupt = self.default_visit_children(value, def_region_kind)?;
        self.current -= 1;
        Ok(interrupt)
    }
}

let values = Array::new(vec![1_i64, 2]);
let mut depth = Depth::default();
structural_visit(&values, &mut depth)?;
assert_eq!(depth.max, 2);

Performance

Re-measured on the current branch with the shared benchmark: Rust structural_visit (pre-order) and structural_walk (post-order) against the equivalent C++ StructuralWalk traversals on identical object graphs, all language x style combinations checksum-asserted before timing. Medians of 30 pinned reps.

Rust / C++ time ratio (lower is better; < 1 means Rust is faster):

shape	structural_visit	structural_walk
reflected-object tree (196k values)	0.98x	1.04x
nested arrays (87k values)	1.10x	1.16x
map trees, small & dense layouts (31k values)	0.90x	0.96x

Every combination is within 1.16x of C++, at an absolute cost of ~7-21 ns per visited value, matching C++.

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.