Struct FlowEngine 

pub struct FlowEngine<'c, M> { /* private fields */ }

Tracks open flows and completed detectors while chunks are appended.

Open-flow keys borrow the boundary PauliMaps of the appended chunks (lifetime 'c), so matching flows across chunks never clones a key. This works because every appended flow outlives the engine; the engine is a per-pass scratch structure, not a long-lived store.

Implementations

impl<'c, M> FlowEngine<'c, M>

pub fn new() -> FlowEngine<'c, M>

Creates an empty flow-composition engine.

pub fn finish(self) -> Result<Vec<CompletedFlow<M>>, FlowError>

Return completed flows after requiring all active flows to terminate. Latent stabilizers that survive the final measured-check span are output logical correlations; observable lowering owns them, not the detector side table.

Errors

Returns FlowError if any flow remains unterminated.

pub fn append_group_allowing_dangling( &mut self, parts: &[OffsetFlows<'c>], meas_mapper: impl FnMut(usize, &u32) -> M, ) -> Result<(), FlowError>

Append one logical chunk assembled from several offset flow slices (one per node member), while allowing previously-open boundary flows to remain open for later chunks.

The mapper receives the slice index alongside each measurement reference so every member can resolve against its own template measurement table.

Errors

Returns FlowError if boundaries cannot be translated or composed.

pub fn append_group_allowing_stabilizer_transition( &mut self, parts: &[OffsetFlows<'c>], meas_mapper: impl FnMut(usize, &u32) -> M, ) -> Result<(), FlowError>

where M: Copy,

Append a boundary group while allowing its stabilizer span to differ from the currently-open span. Exact matching remains the fast path. At a gauge transition, products in the two spans’ intersection emit detectors; old-only generators retire and the group’s ordinary creator flows start its new-only generators.

Errors

Returns FlowError if boundaries cannot be translated or composed.

pub fn append_group_skipping_unmatched_inputs( &mut self, parts: &[OffsetFlows<'c>], meas_mapper: impl FnMut(usize, &u32) -> M, ) -> Result<(), FlowError>

Append chunks while ignoring flows whose start boundary is not already open. This is useful when extracting template-local detectors: flows that enter through a template boundary are handled later by instance lowering, not by the reusable template side table.

Errors

Returns FlowError if boundaries cannot be translated or composed.

pub fn append_residual_group( &mut self, parts: &[OffsetFlows<'c>], meas_mapper: impl FnMut(usize, &u32) -> M, ) -> Result<(), FlowError>

Append chunks for residual extraction: like Self::append_group_skipping_unmatched_inputs, but a flow whose start is not already open is kept as a boundary-entering chain (recording where it entered) rather than dropped. Combined with Self::into_residual_flows, this composes a template’s open boundary flows into fused chains in one pass: internal detectors fall out via Self::drain_completed as usual, while every flow touching the boundary survives in the residual.

Errors

Returns FlowError if boundaries cannot be translated or composed.

pub fn drain_completed(&mut self) -> Drain<'_, CompletedFlow<M>>

Drains the completed (internal, boundary-detached) detector chains, leaving open flows untouched for later chunks.

pub fn into_residual_flows(self) -> Vec<ResidualFlow<M>>

Consume the engine after a residual composition (chunks appended with Self::append_residual_group) and return every boundary flow as a fused chain: the chains still open (origin_start → open key) plus those that closed against a boundary input (origin_start → ∅). Chains that closed with an empty origin are internal detectors; they collect in completed (drainable via Self::drain_completed) and are excluded here.

The caller owns ordering: open_flows iterates in hash order, so a caller that needs determinism (e.g. reproducible detector emission) must sort the result by a canonical key.

impl<'c, M> FlowEngine<'c, DetectorTerm<M>>

where M: Copy + Ord,

pub fn start_loop_detector_states( &mut self, body_first_chunk: &[OffsetFlows<'c>], next_loop_state: &mut u32, ) -> Result<PendingLoopDetectorStates<'c, M>, FlowError>

Assign a loop-carried detector state to every open flow the loop body is about to consume: the open measurements become the state’s initial parity and are replaced by a single loop-state term.

Open flows are matched against the first body chunk’s start keys directly; a valid body never consumes the same key twice (the append would fail), so each open flow gains at most one state.

Errors

Returns FlowError if coordinates or the loop-state id space overflow.

Panics

Panics if the preflighted loop-state range is internally inconsistent.

pub fn drain_composed_chains( &mut self, ) -> impl Iterator<Item = ComposedChain<M>>

Drain completed chains, classifying each by its fused FlowMarker into a ComposedChain: a Discard-marked or empty-parity chain produces nothing, a Restart chain becomes a restart syndrome, everything else a detector at the chain’s center. This is the shared marker discipline for detector synthesis — the compile-time boundary pass (bloq_compile::lower::detector) and the seam recompose (bloq_ir::edit) both drain through here so the two cannot drift.

pub fn finish_loop_detector_states( &self, pending: PendingLoopDetectorStates<'c, M>, ) -> Vec<LoopCarriedDetectorState<M>>

Completes the pending loop states: each state’s next parity is read from the flow still open at its key after the body was appended.

Trait Implementations

impl<'c, M> Clone for FlowEngine<'c, M>

where M: Clone,

fn clone(&self) -> FlowEngine<'c, M>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<M> Debug for FlowEngine<'_, M>

where M: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<M> Default for FlowEngine<'_, M>

fn default() -> FlowEngine<'_, M>

Returns the “default value” for a type.