PTWM
chain

ptwm_core::chain::runtime

PPG DAG runtime — forward executor, inverse executor, fusion picker.

ptwm_core::chain::runtime

PPG DAG runtime — forward executor, inverse executor, fusion picker.

rsmod

ptwm_core::chain::runtime

crates/ptwm-core/src/chain/runtime.rs:1
mod runtime

PPG DAG runtime — forward executor, inverse executor, fusion picker.

rsfn

ptwm_core::chain::runtime::chain_source_descriptor

crates/ptwm-core/src/chain/runtime.rs:278
pub fn chain_source_descriptor(chain: &Chain) -> Result<PlaneDescriptor, PtwmCoreError>

Descriptor of the plane the chain's `Source` node emits.

Checks that the chain is non-empty and that node 0 is `Source`. The length comes from the Source params (shape × dtype) with checked arithmetic, so a corrupt shape returns an error instead of wrapping.
rsfn

ptwm_core::chain::runtime::chain_terminal_descriptors

crates/ptwm-core/src/chain/runtime.rs:443
pub fn chain_terminal_descriptors(chain: &Chain) -> Result<Vec<PlaneDescriptor>, PtwmCoreError>

Recover terminal descriptors. Kept for callers of the earlier API; it is [`propagate_terminal_descriptors`].

rsfn

ptwm_core::chain::runtime::forward_chain

crates/ptwm-core/src/chain/runtime.rs:106
pub fn forward_chain(chain: &Chain, ctx: &ForwardContext<'_>) -> Result<ForwardResult, PtwmCoreError>

Execute the chain in forward (encode) order.

Node 0 must be `Source`; its output wraps `ctx.source_bytes` in a `Plane`. Each subsequent node comes from `op_from_id`, and the runtime calls `forward` with the gathered input planes. Terminal refs collect at the end in `chain.terminals` order.
rstype

ptwm_core::chain::runtime::ForwardContext

crates/ptwm-core/src/chain/runtime.rs:85
pub struct ForwardContext

Context supplied by the caller for a forward (encode) pass.

`source_bytes` is borrowed: the runtime owns the single allocation that seeds node 0's `Plane`, sparing callers (e.g. multi-chain trial-encode) from cloning the raw tensor for every candidate.
rstype

ptwm_core::chain::runtime::ForwardResult

crates/ptwm-core/src/chain/runtime.rs:95
pub struct ForwardResult

Output of a forward pass.

rstype

ptwm_core::chain::runtime::FusedExecution

crates/ptwm-core/src/chain/runtime.rs:724
pub struct FusedExecution

A fused execution pair: producer node merged with consumer node.

rsfn

ptwm_core::chain::runtime::inverse_chain

crates/ptwm-core/src/chain/runtime.rs:535
pub fn inverse_chain(chain: &Chain, ctx: &InverseContext<'_>) -> Result<Plane, PtwmCoreError>

Execute the chain in inverse (decode) order, reconstructing the source plane.

The traversal walks nodes in reverse topological order. For each node, `op.inverse` runs on the node's output planes (from the working state) to reconstruct the input planes, then stores them under the corresponding source edges. After the traversal, the plane at `(0, 0)` is the reconstructed source.
rstype

ptwm_core::chain::runtime::InverseContext

crates/ptwm-core/src/chain/runtime.rs:520
pub struct InverseContext

Context supplied by the caller for an inverse (decode) pass.

rsfn

ptwm_core::chain::runtime::max_plane_len

crates/ptwm-core/src/chain/runtime.rs:317
pub fn max_plane_len(orig_size: u64) -> u64

Largest plane, at any node of a chain, that a decoder accepts for a tensor of `orig_size` raw bytes.

The factor 16 is the product of two cases that existing files can combine: - A Source that overstates the raw size by up to 8×. Only files written by the Python byte-input path before the P4 fix do this, and their chains are 1-D byte passthroughs or byte splits, whose planes are no larger than the Source. - Ops that expand a plane. MxFp4 deinterleave at most doubles it. The spherical and alpha-stable scale planes can reach 4× their input (one 8-byte scale per row of a single 16-bit element), but their builders accept only 2-D shapes, which the Python path always sizes exactly. So no chain a writer emits multiplies the two, and 16× leaves 2× of headroom over the largest case (8× overstated Source, or a 4× scale plane). The constant 4096 covers block padding such as the BurrowsWheeler index (4 bytes per 256 KiB block). Decoders use this one helper so the bound cannot drift between layouts.
rsfn

ptwm_core::chain::runtime::propagate_terminal_descriptors

crates/ptwm-core/src/chain/runtime.rs:326
pub fn propagate_terminal_descriptors(chain: &Chain) -> Result<Vec<PlaneDescriptor>, PtwmCoreError>

Recover the [`PlaneDescriptor`] of every chain terminal in `chain.terminals` order, without the tensor bytes and without allocating any plane buffer.

Same as [`propagate_terminal_descriptors_bounded`] with no bound.
rsfn

ptwm_core::chain::runtime::propagate_terminal_descriptors_bounded

crates/ptwm-core/src/chain/runtime.rs:359
pub fn propagate_terminal_descriptors_bounded(chain: &Chain, max_plane_len: u64) -> Result<Vec<PlaneDescriptor>, PtwmCoreError>

Recover terminal descriptors symbolically and reject any node output longer than `max_plane_len` bytes.

The walk calls `propagate_descriptors` on every node in topological order. It mirrors [`forward_chain`]: - inputs are gathered from the incoming edges sorted by `dst_input_idx`, and an edge's `role_override` replaces the input's role; - fused pairs (see [`try_fuse_at`]) need no special case: fusion applies only to edges without a role override, and every fused kernel emits the same descriptors as the unfused producer and consumer; - each terminal's descriptor takes the terminal's role, as `forward_chain` re-tags terminal planes. No op's output size, layout or role depends on plane contents, so the result equals the descriptors `forward_chain` produces on a tensor of the Source's declared size. The one data-dependent field is the estimate `EntropyEstimate` writes into `vendor_bytes`: this walk reports zeros (its `propagate_descriptors` value). The earlier decoder computed it from placeholder planes, which was not the encode-time value either, and no codec or decoder reads it. Cross-tensor delta ops (`XorDelta`, `FloatDelta`) need dependency planes and return an error here. The Source descriptor is checked against the bound first, so a Source that declares gigabytes fails before any other node is visited.
rsfn

ptwm_core::chain::runtime::try_fuse_at

crates/ptwm-core/src/chain/runtime.rs:744
pub fn try_fuse_at(chain: &Chain, node_idx: u8) -> Option<FusedExecution>

Check whether `node_idx` is the CONSUMER in a fusable pair. If so, return a `FusedExecution` with `producer_node` set to the upstream node.

Conditions for fusion: 1. The connecting edge has no `role_override` and empty `vendor_bytes`. 2. No other edge or terminal consumes the producer's output. 3. The (producer.op, consumer.op) pair is in the fusion table.