PTWM
chain

ptwm_core::chain::wire_compact

CW2, the compact chain wire.

ptwm_core::chain::wire_compact

CW2, the compact chain wire.

rsmod

ptwm_core::chain::wire_compact

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

CW2, the compact chain wire.

[`crate::chain::wire`] stores a chain with fixed-width fields and section lengths, which costs 50-70 bytes for a typical production chain. CW2 stores the same [`Chain`] in about 15-20 bytes. The `\x89PTWS` compact frame and the `\x89PTWC` compact container use it. The legacy wire stays unchanged for `\x89PTWM` containers and Python chain blobs. ```text n_nodes varint 1..=255 n_edges varint 0..=255 n_terms varint 0..=255 node × n_nodes: op_ref varint resolved by the caller (see below) param_len varint 0..=255 params bytes [n_spine] varint 0..=n_edges; present only when n_edges > 0 edge × (n_edges − n_spine): src, src_out, dst, dst_in varint each, 0..=255 etag u8 bit0 ROLE, bit1 VENDOR; other bits must be 0 [role] compact role (ROLE) [vendor] varint len 1..=65535, then bytes (VENDOR) terminal × n_terms: ref u8 node << 4 | out, for node <= 14 and out <= 15; 0xFF = escape, then node u8, out u8 role compact role ``` All varints are canonical unsigned LEB128 ([`crate::varint`]). **op_ref.** The caller maps ops to integers: the `\x89PTWS` frame uses the `OpId` wire id, a container uses an Extension Table index. **Spine edges.** Most chains start with edges `(i, 0) → (i + 1, 0)` with no role override and no vendor bytes. The first `n_spine` edges are of that form for `i = 0..n_spine` and are not stored. The writer always emits the longest such run, so the reader rejects an explicit first edge that would extend it. **Bound Source.** A `Source` node with `param_len = 0` takes its params from the tensor that the chain encodes: the caller passes [`crate::transforms::source::bound_source_params`] of the tensor's shape and dtype. The writer binds a Source exactly when its params equal those bytes, and the reader rejects explicit params that equal them. Real Source params are never empty (ndim and dtype take 3 bytes), so the marker cannot collide with an explicit Source. Chains that differ only in the tensor shape then encode to the same bytes. **Compact roles.** One byte for every role production chains use: | byte | role | |---|---| | `0x00..=0x04` | `Scale { format }` (`ScaleFormat` tag) | | `0x08..=0x0C` | `GlobalScale { format }` | | `0x10..=0x12` | `Nibble { kind }` (`NibbleKind` tag) | | `0x18` | `Value { Fp4E2m1 }` | | `0x19` | `ExponentByte` | | `0x1A` | `Raw` | | `0x1B` | `Index` | | `0x1C` | `Residual { Xor }` | | `0x40 + 8·(of − 1) + index` | `MantissaByte { index, of }`, `index < of <= 8` | | `0x80 + 8·(of − 1) + index` | `IntegerByte { index, of }`, `index < of <= 8` | | `0xC0 + bits − 1` | `Value { IntN { bits } }`, `1 <= bits <= 32` | | `0xFF` | escape, followed by the [`Role::write`] bytes | Other bytes are rejected, and so is an escaped role that has a one-byte form.
rsfn

ptwm_core::chain::wire_compact::bind_deferred_source

crates/ptwm-core/src/chain/wire_compact.rs:398
pub fn bind_deferred_source(chain: &mut Chain, params: &[u8])

Replace the params of every bound Source of `chain` with `params`.

rsfn

ptwm_core::chain::wire_compact::has_deferred_source

crates/ptwm-core/src/chain/wire_compact.rs:390
pub fn has_deferred_source(chain: &Chain) -> bool

Whether `chain` has a bound Source that a tensor record must supply (a Source node with empty params; see [`write_chain_compact_deferred`]).

rsfn

ptwm_core::chain::wire_compact::op_from_wire_ref

crates/ptwm-core/src/chain/wire_compact.rs:94
pub fn op_from_wire_ref(op_ref: u64) -> Result<OpId, PtwmCoreError>

Inverse of [`op_wire_ref`]; unknown ids are rejected.

rsfn

ptwm_core::chain::wire_compact::op_wire_ref

crates/ptwm-core/src/chain/wire_compact.rs:89
pub fn op_wire_ref(op: OpId) -> Result<u64, PtwmCoreError>

`op_ref` resolver for the `\x89PTWS` frame: the `OpId` wire id.

rsfn

ptwm_core::chain::wire_compact::read_chain_compact

crates/ptwm-core/src/chain/wire_compact.rs:247
pub fn read_chain_compact(r: &mut Cursor<'_>, bound_source: Option<&[u8]>, resolve: impl ?) -> Result<Chain, PtwmCoreError>

Decode one CW2 chain at the cursor. The cursor advances past the chain; bytes after it are left for the caller.

`bound_source` supplies the params of a bound Source (see [`write_chain_compact`]); a bound Source without it is an error. The returned chain is not validated: callers run `validate_chain`.
rsfn

ptwm_core::chain::wire_compact::read_chain_compact_deferred_exact

crates/ptwm-core/src/chain/wire_compact.rs:378
pub fn read_chain_compact_deferred_exact(buf: &[u8], resolve: impl ?) -> Result<Chain, PtwmCoreError>

Decode a shared (registry) CW2 chain that must fill `buf` exactly. A bound Source comes back with empty params; see [`write_chain_compact_deferred`].

rsfn

ptwm_core::chain::wire_compact::read_chain_compact_exact

crates/ptwm-core/src/chain/wire_compact.rs:407
pub fn read_chain_compact_exact(buf: &[u8], bound_source: Option<&[u8]>, resolve: impl ?) -> Result<Chain, PtwmCoreError>

Decode a CW2 chain that must fill `buf` exactly.

rsfn

ptwm_core::chain::wire_compact::read_chain_with

crates/ptwm-core/src/chain/wire_compact.rs:257
pub fn read_chain_with(r: &mut Cursor<'_>, binding: SourceBinding<'_>, resolve: impl ?) -> Result<Chain, PtwmCoreError>

Decode one CW2 chain with an explicit [`SourceBinding`]. With [`SourceBinding::Deferred`] a bound Source is returned with empty params.

rsfn

ptwm_core::chain::wire_compact::read_role_compact

crates/ptwm-core/src/chain/wire_compact.rs:485
pub fn read_role_compact(r: &mut Cursor<'_>) -> Result<Role, PtwmCoreError>

Read one compact role at the cursor.

rstype

ptwm_core::chain::wire_compact::SourceBinding

crates/ptwm-core/src/chain/wire_compact.rs:134
pub enum SourceBinding

How a chain's Source params relate to the tensor it encodes.

rsfn

ptwm_core::chain::wire_compact::write_chain_compact

crates/ptwm-core/src/chain/wire_compact.rs:108
pub fn write_chain_compact(chain: &Chain, bound_source: Option<&[u8]>, op_ref: impl ?, out: &mut Vec<u8>) -> Result<(), PtwmCoreError>

Encode `chain` as CW2 into `out`.

`bound_source` is the tensor's [`bound_source_params`] (`None` when the tensor cannot bind one); a Source whose params equal it is written as a bound Source. `op_ref` maps each node's op to its stored integer. [`bound_source_params`]: crate::transforms::source::bound_source_params
rsfn

ptwm_core::chain::wire_compact::write_chain_compact_deferred

crates/ptwm-core/src/chain/wire_compact.rs:124
pub fn write_chain_compact_deferred(chain: &Chain, op_ref: impl ?, out: &mut Vec<u8>) -> Result<(), PtwmCoreError>

Encode a shared chain (a container registry entry) as CW2 into `out`.

A registry chain serves many tensors, so it cannot be bound to one. In memory, a Source node with empty params stands for a bound Source: it is written as one, and each tensor record that uses the chain supplies the params ([`SourceBinding::Deferred`]). Other Source nodes are written with their params.
rsfn

ptwm_core::chain::wire_compact::write_role_compact

crates/ptwm-core/src/chain/wire_compact.rs:465
pub fn write_role_compact(role: &Role, out: &mut Vec<u8>) -> Result<(), PtwmCoreError>

Append the compact encoding of `role`.