Struct DynSegment 

pub struct DynSegment { /* private fields */ }

Owns validated raw instructions and complete canonical stack metadata.

new::<()>() starts an independent body with borrowed positional reads. Other new argument lists retain the direct, preloaded opaque-leaf ABI.

Implementations

impl DynSegment

pub fn new<Args: IntoCStackList>() -> Self

where ReverseList<Args::Output>: ToTypeIdList,

Creates a segment with an optional preloaded opaque-leaf stack.

Panics

Rejects preloaded erased whole-value owner carriers; import those at a checked external boundary.

Examples

let _ = cel_runtime::DynSegment::new::<()>();

pub fn new_fragment(&self) -> Self

Creates a conditional fragment above the ambient stack below the condition.

• Precondition: at least one operand is present.

Examples

See Self::join2.

pub fn current_stack_offset(&self) -> usize

Returns the current canonical stack byte length.

Examples

assert_eq!(cel_runtime::DynSegment::new::<()>().current_stack_offset(), 0);

pub fn stack_offset_before_top(&self, n: usize) -> Result<usize>

Returns the byte length preceding the top n operands.

Errors

Rejects insufficient operands.

Examples

assert!(cel_runtime::DynSegment::new::<()>().stack_offset_before_top(1).is_err());

pub fn peek_stack_infos(&self, n: usize) -> &[StackInfo]

Borrows up to the top n complete descriptors.

Examples

let body = cel_runtime::DynSegment::new::<()>();
assert!(body.peek_stack_infos(0).is_empty());

pub fn peek_output_type_id(&self) -> Option<TypeId>

Returns a diagnostic dispatch identity, never a structural cast authority.

Examples

assert!(cel_runtime::DynSegment::new::<()>().peek_output_type_id().is_none());

pub fn peek_tuple_arity(&self) -> Option<usize>

Returns the source tuple arity, including zero for canonical unit.

Examples

assert!(cel_runtime::DynSegment::new::<()>().peek_tuple_arity().is_none());

pub fn op0<R: 'static, F: Fn() -> R + 'static>(&mut self, f: F)

Registers a nullary opaque-leaf host operation.

Panics

Rejects erased whole-value owner results or unrepresentable frames. Use op0_repr for fallible registration and just_external for checked owner imports.

Examples

let mut b = cel_runtime::DynSegment::new::<()>();
b.op0(|| 7i32);
assert_eq!(b.call0::<i32>().unwrap(), 7);

pub fn op0r<R: 'static, F: Fn() -> Result<R> + 'static>(&mut self, f: F)

Registers a fallible nullary opaque-leaf operation with ambient cleanup.

Panics

Rejects erased whole-value owner results or unrepresentable frames during registration.

Examples

let mut b = cel_runtime::DynSegment::new::<()>();
b.op0r(|| Ok(7i32));

pub fn op0_repr<R: ValueRepr, F: Fn() -> R::Value + 'static>( &mut self, f: F, ) -> Result<()>

Registers a witnessed nullary operation.

Errors

Rejects unrepresentable stack positions.

• Complexity: O(n) registration work for n ambient slots.

Examples

let mut b = cel_runtime::DynSegment::new::<()>();
b.op0_repr::<cel_runtime::Nil, _>(|| cel_runtime::IntoCStackList::into_c_stack_list(())).unwrap();

pub fn op0r_repr<R: ValueRepr, F: Fn() -> Result<R::Value> + 'static>( &mut self, f: F, ) -> Result<()>

Registers a fallible witnessed nullary operation.

Errors

Rejects unrepresentable stack positions; host errors propagate on execution.

• Complexity: O(n) registration work for n ambient slots.

Examples

let mut b = cel_runtime::DynSegment::new::<()>();
b.op0r_repr::<cel_runtime::Leaf<i32>, _>(|| Ok(7)).unwrap();

pub fn op1<A: 'static, R: 'static, F: Fn(A) -> R + 'static>( &mut self, f: F, ) -> Result<()>

Registers a unary opaque-leaf operation.

Errors

Rejects insufficient or nonmatching opaque operands.

• Complexity: O(n) registration work for n stack slots.

Examples

let mut b = cel_runtime::DynSegment::new::<()>();
b.just(1i32); b.op1(|x: i32| x.to_string()).unwrap();

pub fn op1r<A: 'static, R: 'static, F: Fn(A) -> Result<R> + 'static>( &mut self, f: F, ) -> Result<()>

Registers a fallible unary opaque-leaf operation.

Errors

Rejects insufficient or nonmatching operands; execution propagates host errors.

• Complexity: O(n) registration work for n stack slots.

Examples

let mut b = cel_runtime::DynSegment::new::<()>();
b.just(1i32); b.op1r(|x: i32| Ok(x)).unwrap();

pub fn op1_repr<A: ValueRepr, R: ValueRepr, F: Fn(A::Value) -> R::Value + 'static>( &mut self, f: F, ) -> Result<()>

Registers a unary operation after checking its complete operand witness.

Errors

Rejects insufficient operands or recursive representation mismatch.

• Complexity: O(n) registration work for n frame/descriptor nodes.

Examples

let mut b = cel_runtime::DynSegment::new::<()>();
b.just(1i32);
b.op1_repr::<cel_runtime::Leaf<i32>, cel_runtime::Leaf<i32>, _>(|x| x).unwrap();

pub fn op1r_repr<A: ValueRepr, R: ValueRepr, F: Fn(A::Value) -> Result<R::Value> + 'static>( &mut self, f: F, ) -> Result<()>

Registers a fallible unary witnessed operation with error/unwind cleanup.

Errors

Rejects insufficient operands or recursive mismatch; propagates host errors on execution.

• Complexity: O(n) registration work for n frame/descriptor nodes.

Examples

let mut b = cel_runtime::DynSegment::new::<()>();
b.just(1i32);
b.op1r_repr::<cel_runtime::Leaf<i32>, cel_runtime::Leaf<i32>, _>(Ok).unwrap();

pub fn op2<A: 'static, B: 'static, R: 'static, F: Fn(A, B) -> R + 'static>( &mut self, f: F, ) -> Result<()>

Registers a binary opaque-leaf operation in source order.

Errors

Rejects insufficient or mismatched operands.

• Complexity: O(n) registration work for n frame/descriptor nodes.

Examples

let mut b = cel_runtime::DynSegment::new::<()>();
b.just(1i32); b.just(2i32); b.op2(|a: i32, b: i32| a + b).unwrap();

pub fn op2r<A: 'static, B: 'static, R: 'static, F: Fn(A, B) -> Result<R> + 'static>( &mut self, f: F, ) -> Result<()>

Registers a fallible binary opaque-leaf operation.

Errors

Rejects insufficient/mismatched operands; propagates host errors on execution.

• Complexity: O(n) registration work for n frame/descriptor nodes.

Examples

let mut b = cel_runtime::DynSegment::new::<()>();
b.just(1i32); b.just(2i32); b.op2r(|a: i32, b: i32| Ok(a + b)).unwrap();

pub fn op2_repr<A: ValueRepr, B: ValueRepr, R: ValueRepr, F: Fn(A::Value, B::Value) -> R::Value + 'static>( &mut self, f: F, ) -> Result<()>

Registers a binary witnessed operation in source order.

Errors

Rejects insufficient operands or complete witness mismatch.

• Complexity: O(n) registration work for n frame/descriptor nodes.

Examples

See Self::op2; use one witness per operand and result.

pub fn op2r_repr<A: ValueRepr, B: ValueRepr, R: ValueRepr, F: Fn(A::Value, B::Value) -> Result<R::Value> + 'static>( &mut self, f: F, ) -> Result<()>

Registers a fallible binary witnessed operation.

Errors

Rejects insufficient operands or complete mismatch; execution propagates host errors.

• Complexity: O(n) registration work for n frame/descriptor nodes.

Examples

See Self::op2r; use one witness per operand and result.

pub fn op3<A: 'static, B: 'static, C: 'static, R: 'static, F: Fn(A, B, C) -> R + 'static>( &mut self, f: F, ) -> Result<()>

Registers a ternary opaque-leaf operation in source order.

Errors

Rejects insufficient or mismatched operands.

• Complexity: O(n) registration work for n frame/descriptor nodes.

Examples

See Self::op2; push one additional operand.

pub fn op3r<A: 'static, B: 'static, C: 'static, R: 'static, F: Fn(A, B, C) -> Result<R> + 'static>( &mut self, f: F, ) -> Result<()>

Registers a fallible ternary opaque-leaf operation.

Errors

Rejects insufficient/mismatched operands; execution propagates host errors.

• Complexity: O(n) registration work for n frame/descriptor nodes.

Examples

See Self::op2r; push one additional operand.

pub fn op3_repr<A: ValueRepr, B: ValueRepr, C: ValueRepr, R: ValueRepr, F: Fn(A::Value, B::Value, C::Value) -> R::Value + 'static>( &mut self, f: F, ) -> Result<()>

Registers a ternary witnessed operation in source order.

Errors

Rejects insufficient operands or complete witness mismatch.

• Complexity: O(n) registration work for n frame/descriptor nodes.

Examples

See Self::op2_repr; supply one additional witness.

pub fn op3r_repr<A: ValueRepr, B: ValueRepr, C: ValueRepr, R: ValueRepr, F: Fn(A::Value, B::Value, C::Value) -> Result<R::Value> + 'static>( &mut self, f: F, ) -> Result<()>

Registers a fallible ternary witnessed operation.

Errors

Rejects insufficient operands or complete mismatch; execution propagates host errors.

• Complexity: O(n) registration work for n frame/descriptor nodes.

Examples

See Self::op2r_repr; supply one additional witness.

pub fn op1_vec<E: ValueRepr, R: ValueRepr, F: Fn(Vec<E::Value>) -> R::Value + 'static>( &mut self, f: F, ) -> Result<()>

Transfers a canonical array allocation into a concrete host vector.

Errors

Rejects insufficient operands or a differing complete element witness.

• Complexity: O(n) registration work; execution preserves the allocation.

Examples

See the prepared_containers integration tests.

pub fn op1r_vec<E: ValueRepr, R: ValueRepr, F: Fn(Vec<E::Value>) -> Result<R::Value> + 'static>( &mut self, f: F, ) -> Result<()>

Registers a fallible zero-copy canonical-array-to-vector adapter.

Errors

Rejects witness mismatch; execution propagates host errors with ambient cleanup.

• Complexity: O(n) registration work; O(1) ownership transfer.

Examples

See Self::op1_vec.

pub fn op1_slice<E: ValueRepr, R: ValueRepr, F: Fn(&[E::Value]) -> R::Value + 'static>( &mut self, f: F, ) -> Result<()>

Borrows the original canonical array payload during a host callback.

The consumed array is destroyed after the callback; the result is owned.

Errors

Rejects insufficient operands or complete element witness mismatch.

• Complexity: O(n) registration work; O(1) borrowing plus destruction.

Examples

See Self::op1_vec.

pub fn op1r_slice<E: ValueRepr, R: ValueRepr, F: Fn(&[E::Value]) -> Result<R::Value> + 'static>( &mut self, f: F, ) -> Result<()>

Registers a fallible borrowed-slice adapter with owned result and cleanup.

Errors

Rejects complete witness mismatch; execution propagates host errors.

• Complexity: O(n) registration work; O(1) borrowing plus destruction.

Examples

See Self::op1_slice.

pub fn just<T: Clone + 'static>(&mut self, value: T)

Pushes a cloned opaque constant on each execution.

Panics

Rejects erased whole-value owner constants; use Self::just_external to import them.

Examples

let mut b = cel_runtime::DynSegment::new::<()>(); b.just(7i32);

pub fn just_external( &mut self, value_type: ValueType, value: Box<dyn Any>, ) -> Result<()>

Imports an external constant once and emits only trusted canonical cloning.

The descriptor must include every borrowed clone capability. Wrapper headers are converted before registration, never during interpreter execution.

Errors

Rejects noncanonical descriptors, unavailable cloning, invalid external identity/shape, unsupported external conversions, or frame overflow.

• Complexity: Boundary validation/import at setup; value cloning on each execution.

Examples

use cel_runtime::{DynSegment, Array, OwnedValue, ValueType, Nil, ArrayOf, Leaf, IntoCStackList};
let mut body = DynSegment::new::<()>();
body.just_external(ValueType::array(ValueType::cloneable_leaf::<i32>()),
    Box::new(OwnedValue::new::<ArrayOf<Leaf<i32>>>(Array::from_vec(vec![7i32])))).unwrap();
let mut body = body.prepare::<Nil, ArrayOf<Leaf<i32>>>().unwrap();
assert_eq!(body.call(&().into_c_stack_list()).unwrap().as_slice(), [7]);

pub fn push_arg<T: Clone + 'static>(&mut self, index: usize)

Registers a borrowed opaque-leaf argument read.

Examples

let mut b = cel_runtime::DynSegment::new::<()>();
b.push_arg::<i32>(0);
assert_eq!(b.call_dyn::<i32>(&[&7i32]).unwrap(), 7);

pub fn push_argument( &mut self, index: usize, value_type: ValueType, ) -> Result<()>

Registers a canonical borrowed argument read with its frozen clone plan.

Errors

Rejects missing clone capability or unrepresentable frame positions. Preparation validates its complete identity against the argument witness.

• Complexity: O(d) registration for d descriptor nodes; execution has the value’s clone cost without temporary whole-value allocation.

Examples

let mut b = cel_runtime::DynSegment::new::<()>();
b.push_argument(0, cel_runtime::ValueType::cloneable_leaf::<i32>()).unwrap();

pub fn make_tuple(&mut self, n: usize, ambient_start: usize) -> Result<()>

Packs source-ordered operands into their canonical concrete list layout.

Errors

Rejects insufficient operands, a wrong ambient snapshot, or layout overflow.

• Complexity: O(n + s) registration and raw moves for n fields and s bytes.

Examples

let mut b = cel_runtime::DynSegment::new::<()>();
b.just(1i32); b.just(2f64); b.make_tuple(2, 0).unwrap();

pub fn make_array(&mut self, n: usize, ambient_start: usize) -> Result<()>

Packs homogeneous operands into a canonical owning array header.

Errors

Rejects empty inference, differing complete types, wrong ambient origin, insufficient operands, or allocation-layout overflow.

• Complexity: O(n + s) checks and moves for n elements and s bytes.

Examples

let mut b = cel_runtime::DynSegment::new::<()>();
b.just(1i32); b.make_array(1, 0).unwrap();

pub fn make_typed_array( &mut self, n: usize, ambient_start: usize, element: ValueType, ) -> Result<()>

Packs operands using an explicit complete element descriptor.

Errors

Rejects wrong ambient origin, insufficient/differently shaped operands, or allocation-layout overflow. Empty arrays need no element capabilities.

• Complexity: O(n + s) checks and moves for n elements and s bytes.

Examples

let mut b = cel_runtime::DynSegment::new::<()>();
b.make_typed_array(0, 0, cel_runtime::ValueType::leaf::<i32>()).unwrap();

pub fn tuple_index(&mut self, index: usize) -> Result<()>

Moves one source-ordered tuple field and destroys every other field.

Errors

Rejects a missing tuple or an out-of-range index before emitting.

• Complexity: O(n) registration/destruction for n fields, plus representation moves.

Examples

let mut b = cel_runtime::DynSegment::new::<()>();
b.just(1i32); b.just(2f64); b.make_tuple(2, 0).unwrap();
b.tuple_index(0).unwrap(); assert_eq!(b.call0::<i32>().unwrap(), 1);

pub fn array_index<I: TryInto<usize> + 'static>(&mut self) -> Result<()>

Moves an indexed canonical array element and destroys the consumed array’s siblings.

The stack holds the array followed by an opaque index of type I. No clone capability is required, including for nested tuple/array elements. Moving the validated index into its concrete type does not allocate.

Errors

Rejects absent/nonmatching operands during registration. Execution rejects negative/unrepresentable or out-of-bounds indices and cleans every operand.

• Complexity: O(n) setup/destruction for n stack slots or array elements.

Examples

let mut body = cel_runtime::DynSegment::new::<()>();
body.just(7i32); body.make_array(1, 0).unwrap();
body.just(0i32); body.array_index::<i32>().unwrap();
assert_eq!(body.call0::<i32>().unwrap(), 7);

pub fn drop_value(&mut self) -> Result<()>

Destroys the top canonical value without synthesizing a result.

Ambient values survive success and are cleaned if a destructor unwinds.

Errors

Rejects an empty stack before registration.

• Complexity: O(1) setup; value-dependent destruction.

Examples

let mut body = cel_runtime::DynSegment::new::<()>();
body.just(1i32); body.make_array(1, 0).unwrap();
body.drop_value().unwrap();
body.just(7i32); assert_eq!(body.call0::<i32>().unwrap(), 7);

pub fn relabel_repr<R: ValueRepr>(&mut self) -> Result<()>

Validates a complete value using an explicit matching structural witness.

Errors

Rejects an absent or mismatched value; this never authorizes opaque casts.

• Complexity: O(n) complete descriptor comparison for n nodes.

Examples

let mut b = cel_runtime::DynSegment::new::<()>();
b.make_tuple(0, 0).unwrap(); b.relabel_repr::<cel_runtime::Nil>().unwrap();

pub fn annotate_top(&mut self, value_type: ValueType) -> Result<()>

Installs complete registered capabilities without changing the top value’s identity.

A host registry can retain clone/equality/debug adapters on operation results for checked external export. No instruction or raw cast is emitted.

Errors

Rejects a missing value or any recursive identity/layout mismatch.

• Complexity: O(n) complete comparison for n descriptor nodes.

Examples

use cel_runtime::{DynSegment, Leaf, ValueType};
let mut body = DynSegment::new::<()>(); body.just(7i32);
body.annotate_top(ValueType::cloneable_leaf::<i32>()
    .with_equality::<Leaf<i32>>().unwrap()
    .with_debug::<Leaf<i32>>().unwrap()).unwrap();

pub fn pop_tuple_as<R: ValueRepr>(&mut self) -> Result<()>

Relabels a canonical tuple as its concrete opaque list using an explicit witness.

No bytes move. The witness authorizes the concrete Rust destructor and permits an ordinary typed operation or direct Segment conversion.

Errors

Rejects a missing/nontuple value or any complete witness mismatch.

• Complexity: O(n) complete comparison for n descriptor nodes.

Examples

let mut body = cel_runtime::DynSegment::new::<()>();
body.make_tuple(0, 0).unwrap();
body.pop_tuple_as::<cel_runtime::Nil>().unwrap();

pub fn push_tuple<R: ValueRepr>(&mut self) -> Result<()>

Relabels a concrete opaque canonical list as a structural tuple using its witness.

Errors

Rejects missing values, nontuple witnesses, or a different opaque concrete type.

• Complexity: O(n) witness construction for n tuple descriptor nodes.

Examples

use cel_runtime::{DynSegment, Nil, IntoCStackList};
let mut body = DynSegment::new::<()>();
body.just(().into_c_stack_list());
body.push_tuple::<Nil>().unwrap();

pub fn call_dyn<R: 'static>(&mut self, inputs: &[&dyn Any]) -> Result<R>

Evaluates a result at a checked external host boundary.

Structural results return canonical whole-value owners; callable results return their concrete carrier. Interpreter operations never use this conversion. Scalar inputs are borrowed after complete input preflight and cloned only by executed reads; compound inputs borrow checked canonical owners.

Errors

Rejects dependent bodies, non-single results, unsupported external shapes, unavailable argument capabilities, or mismatched arguments/results; propagates body errors.

• Complexity: Boundary validation and argument clones plus evaluation.

Examples

See Self::push_arg.

pub fn call_dyn_value(&mut self, inputs: &[&dyn Any]) -> Result<OwnedValue>

Evaluates an owned canonical value through a checked external argument boundary.

Errors

Rejects dependent bodies, non-single results, or invalid external arguments. Propagates operation errors without erasing their context.

• Complexity: Boundary validation/cloning plus body evaluation and one raw result move.

Examples

let mut body = cel_runtime::DynSegment::new::<()>();
body.just(7i32);
assert_eq!(body.call_dyn_value(&[]).unwrap().try_into_typed::<cel_runtime::Leaf<i32>>().unwrap(), 7);

pub fn call0<R: 'static>(&mut self) -> Result<R>

Executes a checked no-argument host call without consuming type metadata.

Errors

Rejects a result mismatch, extra stack values, or required preloaded arguments.

• Complexity: Body-dependent evaluation plus boundary checks.

Examples

See Self::op0.

pub fn call1<A: 'static, R: 'static>(&mut self, arg: A) -> Result<R>

Executes a preloaded single opaque-leaf argument and result.

Errors

Rejects nonmatching argument/result identities, positional reads, or extra results.

• Complexity: Body-dependent.

Examples

let mut b = cel_runtime::DynSegment::new::<(i32,)>();
b.op1(|x: i32| x.to_string()).unwrap();
assert_eq!(b.call1::<i32, String>(7).unwrap(), "7");

pub fn prepare<A: ValueRepr, R: ValueRepr>( self, ) -> Result<PreparedSegment<A, R>>

Prepares a complete borrowed argument list and owned result once.

Errors

Rejects dependent bodies, non-list arguments, mismatched reads/results, missing borrowed clone capabilities, or inconsistent reads of one argument.

• Complexity: O(n) complete comparisons for n frame/descriptor nodes.

Examples

See the module example.

pub fn push_closure(&mut self, closure: DynClosure) -> Result<()>

Pushes a known callable with complete metadata and shared body ownership.

Errors

Rejects an untyped/invalid closure or unavailable trusted binding.

• Complexity: O(n) signature/body validation for n descriptor nodes.

Examples

See Self::invoke_closure.

pub fn invoke_closure(&mut self, arity: usize) -> Result<()>

Invokes a canonical callable below its source-ordered evaluated arguments.

Moving the bound callee into its concrete carrier does not allocate. Argument and result transfers retain their erased ownership.

Errors

Rejects unavailable/mismatched callable metadata or insufficient operands. Execution propagates body errors, retaining their original context.

• Complexity: O(n) setup; body execution plus argument/result raw moves.

Examples

use cel_runtime::{DynClosure, DynSegment};
let mut body = DynSegment::new::<()>(); body.just(7i32);
let closure = DynClosure::typed(vec![], body).unwrap();
let mut b = DynSegment::new::<()>();
b.push_closure(closure).unwrap(); b.invoke_closure(0).unwrap();
assert_eq!(b.call0::<i32>().unwrap(), 7);

pub fn join2(&mut self, yes: Self, no: Self) -> Result<()>

Joins conditional fragments with identical complete results and origins.

Errors

Rejects a nonboolean condition, wrong fragment origins, or different results.

• Complexity: O(n) setup for n frame/descriptor nodes; executes one branch.

Examples

let mut b = cel_runtime::DynSegment::new::<()>(); b.just(true);
let mut yes = b.new_fragment(); yes.just(1i32);
let mut no = b.new_fragment(); no.just(2i32);
b.join2(yes, no).unwrap(); assert_eq!(b.call0::<i32>().unwrap(), 1);

Trait Implementations

impl<Args: IntoList + 'static, Stack> TryFrom<DynSegment> for Segment<Args, Stack>

where ReverseList<<Args as IntoList>::Output<CNil<()>>>: ListTypeIteratorAdvance<TypeId>, Stack: ListTypeIteratorAdvance<TypeId> + List + 'static,

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: DynSegment) -> Result<Self, Self::Error>

Performs the conversion.