Crate entelix_graph 

entelix-graph

Control-flow contract for entelix (invariant 8). Houses StateGraph<S> with typed state, the Reducer<T> trait, conditional / fan-out edges, subgraphs, the Checkpointer trait plus InMemoryCheckpointer, and the Command<S> HITL resume API. recursion_limit (F6 mitigation) is enforced here. The HITL pause primitive (entelix_core::interrupt / entelix_core::interrupt_with) lives in entelix-core so tools, nodes, and middleware layers all raise the same Error::Interrupted shape.

Surface: StateGraph<S> builder with static and conditional edges + CompiledGraph<S> executor with recursion_limit enforcement and the END sentinel target. Checkpointer + InMemoryCheckpointer for write-after-each-node persistence; CompiledGraph::resume / CompiledGraph::resume_with crash recovery. Command<S> for typed resume payloads.

Structs

Annotated

Newtype that bundles a value T with the reducer R that should merge it. The wrapper is a standalone helper users compose into their state types; it does not hook into StateGraph::add_node directly.

Append

Append: current followed by update. Specialised for Vec<U> where U: Clone + Send + Sync + 'static.

Checkpoint

One snapshot of graph progress for a particular (tenant_id, thread_id). next_node = None indicates the graph terminated cleanly (a finish point ran or a conditional edge routed to END).

CheckpointId

Stable identifier for a checkpoint. Backed by UUID v7 — time-ordered and globally unique across processes.

CompiledGraph

Frozen graph ready to execute.

ConditionalEdge

One conditional-edge dispatch.

ContributingNodeAdapter

Runnable<S, S> adapter that snapshots the inbound state, runs an inner Runnable<S, S::Contribution> to produce only the slots the node touched, and folds that contribution into the snapshot via S::merge_contribution.

Dispatch

One unit of fan-out work — semantically equivalent to LangGraph’s Send(node, payload). Carries the payload that a fanned-out runnable will receive when scatter runs.

FinalizingStream

Stream that fires finalize exactly once when dropped before the inner stream returned None. Normal completion (the inner stream yielded None from poll_next) is not an early-cancel — the finalizer is silently skipped.

InMemoryCheckpointer

In-process checkpointer backed by a HashMap<(tenant_id, thread_id), Vec<Checkpoint>>. The composite key encodes Invariant 11 (multi-tenant isolation): the same thread_id under two tenants resolves to two distinct histories.

Max

Keep the larger of current / update per T: Ord. Useful for “highest score wins” reducers and usize step counters merged across parallel branches.

MergeMap

Merge two HashMap<K, V>s, right-biased — entries from update overwrite collisions in current. (Right-bias matches typical LangGraph / dict-update semantics.)

MergeNodeAdapter

Runnable<S, S> that runs an inner Runnable<S, U> and merges the resulting U back into a fresh copy of the inbound S via the supplied closure.

Replace

Last-write-wins. Matches the current StateGraph default — included so users who explicitly opt into reducer machinery have a no-op option.

SendEdge

Parallel fan-out edge.

StateGraph

Builder for a state-machine graph parameterised over its state type S.

Enums

CheckpointGranularity

How often the compiled graph writes a checkpoint when a Checkpointer is attached.

Command

Resume directive supplied to CompiledGraph::resume_with.

Constants

DEFAULT_RECURSION_LIMIT

Default cap on node executions per invoke (F6 mitigation — guards against infinite cycles).

END

Sentinel target meaning “terminate without running another node”. Use in add_conditional_edges mapping when a branch should end the graph.

Traits

Checkpointer

Persistent (or in-memory) store of Checkpoint<S>s addressed by ThreadKey.

Reducer

Combines a current value and an incoming update into the next value.

StateMerge

State-level merge: how an incoming update folds into the current state. The dispatch-loop counterpart to Reducer<T>, one level up — implemented on the whole S shape rather than a single slot.

Functions

scatter

Fan a Vec<Dispatch<I>> through a Runnable<I, O> in parallel and collect the outputs in submission order.

Type Aliases

EdgeSelector

Closure that picks a conditional-edge target by inspecting state.

SendMerger

Two-state merger applied per branch result during a send-edge fold — the dispatch loop calls it once per branch with (folded_so_far, branch_state) -> next_folded.

SendSelector

Closure returning the parallel branches a send edge dispatches. Each pair is (target_node_name, branch_state); target nodes run concurrently with their respective branch states.

Derive Macros

StateMerge

Derive entelix_graph::StateMerge and generate the <Name>Contribution companion struct.