pub trait PolydatNode: Send + Sync {
// Required methods
fn meta(&self) -> &NodeMeta;
fn eval(&self, inputs: &[Value], outputs: &mut [Value]);
// Provided methods
fn scratch_layout(&self) -> Vec<ScratchElem> { ... }
fn eval_in(
&self,
scratch: &mut [ScratchBuf],
inputs: &[Value],
outputs: &mut [Value],
) { ... }
fn commutativity(&self) -> Commutativity { ... }
fn accepts_none_inputs(&self) -> bool { ... }
fn compiled_u64(&self) -> Option<CompiledU64Op> { ... }
fn compiled_slot(&self, _wire_types: &[PortType]) -> Option<CompiledSlotKit> { ... }
fn jit_constants(&self) -> Vec<u64> { ... }
fn purity(&self) -> Purity { ... }
fn simd_variant(&self) -> Option<SimdVariant> { ... }
fn fusion_subgraph(&self) -> Option<FusionSubgraph<'_>> { ... }
}Expand description
Runtime evaluation interface for a Polydat node.
Phase 1: called via dyn PolydatNode (dynamic dispatch with Value enum).
Phase 2: if all nodes in the DAG are u64-only and provide a
compiled_u64 implementation, the assembly phase compiles the DAG
into a flat buffer evaluator with direct function calls.
Required Methods§
Provided Methods§
Sourcefn scratch_layout(&self) -> Vec<ScratchElem>
fn scratch_layout(&self) -> Vec<ScratchElem>
The scratch entries a state owns for this node’s evaluation
(axiom S3), one per entry in the order the node expects them
in Self::eval_in. Empty for a node that evaluates over
Values alone, which is every node but a native cone.
Sourcefn eval_in(
&self,
scratch: &mut [ScratchBuf],
inputs: &[Value],
outputs: &mut [Value],
)
fn eval_in( &self, scratch: &mut [ScratchBuf], inputs: &[Value], outputs: &mut [Value], )
Self::eval with the node’s scratch, which the evaluating
state owns and hands in: storage belongs to the state, never to
the node, which is shared by every state of the program.
Sourcefn commutativity(&self) -> Commutativity
fn commutativity(&self) -> Commutativity
Declare which inputs are interchangeable for this node.
Override for commutative operations like sum, product,
min, max. The default is Positional (order matters).
Sourcefn accepts_none_inputs(&self) -> bool
fn accepts_none_inputs(&self) -> bool
True iff this node should receive Value::None inputs
directly rather than have the kernel propagate None through
it. Default: false — most nodes follow SRD-74 Rule 1
(None in → None out, no eval invocation).
Override to true for nodes whose semantics explicitly
consume None: coalesce-style fallbacks (default_or),
optional/maybe handlers, anything that distinguishes
“present” from “absent” as part of its contract.
Override-true nodes are responsible for handling
Value::None in their own eval implementation.
See none_semantics.md (string-interpolation propagates None) — the rule is general (lifted to the kernel level) rather than per-node; this flag is the opt-out for legitimate None- aware operators.
Sourcefn compiled_u64(&self) -> Option<CompiledU64Op>
fn compiled_u64(&self) -> Option<CompiledU64Op>
Return a compiled u64-only evaluation closure, if this node operates entirely in u64 space.
The closure reads from an input slice and writes to an output
slice, both &[u64] / &mut [u64]. Assembly-time parameters
are captured in the closure.
Return None if the node has non-u64 ports or cannot be
compiled. The assembly phase will fall back to Phase 1.
Sourcefn compiled_slot(&self, _wire_types: &[PortType]) -> Option<CompiledSlotKit>
fn compiled_slot(&self, _wire_types: &[PortType]) -> Option<CompiledSlotKit>
Return a slot-compiled closure for nodes with typed-slice
ports (§8.4 layer 3): slice inputs read (ptr, len) slot
pairs; vector outputs write into kernel-owned scratch.
Checked by the compiled-kernel builders AFTER
Self::compiled_u64 — pure-scalar nodes never need it.
Default None: the node stays on typed eval.
Sourcefn jit_constants(&self) -> Vec<u64>
fn jit_constants(&self) -> Vec<u64>
Return assembly-time constants for JIT compilation.
Nodes with baked-in constants (Mod’s modulus, Add’s addend, etc.) override this to expose their constants to the JIT compiler. Returns a list of u64 constants in the order the JIT expects.
Default: empty (no constants to expose).
Sourcefn purity(&self) -> Purity
fn purity(&self) -> Purity
Declare this node’s purity status per the
runtime_model.md’s D2 axiom. Default:
Purity::Pure. Override to declare an observable
side channel (Purity::SideChannel) or
eval-call-spanning state (Purity::Nondeterministic).
What this affects:
- The runtime’s
node_cleancache (R1) holds forPurity::PureandPurity::SideChannel. The typed return value is cached after one eval; subsequent pulls with identical inputs reuse the cache. ForSideChannelnodes, this means the side channel fires once per dirty-to-clean transition (not on every pull). Purity::Nondeterministicnodes opt out ofnode_cleancaching at the construction tier (assembly marks them as nondeterministic perkernel/engines.rs::nondeterministic_nodes).- Hosts inspecting an expression’s determinism profile via D2 read this declaration to know whether the constituent node has side channels.
Default: Purity::Pure. Most nodes are pure
functions over their inputs.
Sourcefn simd_variant(&self) -> Option<SimdVariant>
fn simd_variant(&self) -> Option<SimdVariant>
Explicit SIMD-native implementation of this scalar node, if one has been registered with a semantic contract.
Returning metadata does not itself make a node promotable. The planner must still validate types, purity, source replay, packet ownership, and successful lowering by the same Cranelift ISA used for code generation.
Sourcefn fusion_subgraph(&self) -> Option<FusionSubgraph<'_>>
fn fusion_subgraph(&self) -> Option<FusionSubgraph<'_>>
A synthetic fusion node’s view of the subgraph it stands in
for (SRD-105 cone extraction). Program-identity hashing
(PolydatProgram::canonical_hash) walks THROUGH fusion
nodes into this subgraph, so identity is invariant to the
engine mix: jit=off and jit=auto compiles of the same
source hash identically, and resume-skip matching survives
mode changes. Default None: ordinary nodes hash as
themselves.
Dyn Compatibility§
This trait is dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".