PTWM
ptwm_core

ptwm_core::compact

Compact single-tensor frame (magic \x89PTWS).

ptwm_core::compact

Compact single-tensor frame (magic \x89PTWS).

rsmod

ptwm_core::compact

crates/ptwm-core/src/compact.rs:1
mod compact

Compact single-tensor frame (magic `\x89PTWS`).

A full `.ptwm` container carries a fixed header, an Extension Table, a prelude, a chain registry, a tensor index and an EOF sentinel. For one small tensor those sections cost more than the payload. The compact frame holds one tensor with only the fields its decoder needs: ```text magic: [u8; 5] \x89PTWS flags: u8 see FLAG_*; unknown bits are rejected, and FLAG_PLANE_CRC with FLAG_PAYLOAD_HASH is rejected dtype_code: varint at most u16::MAX input_format: u8 [orig_size] varint raw byte count (FLAG_SIZE) [shape] varint ndim (<= 64), then varint per dimension (FLAG_SHAPE) [dtype_name] varint len, then UTF-8 bytes (FLAG_DTYPE_NAME) [delta_ref] [u8; 32] BLAKE3 of the delta reference (FLAG_DELTA_REF) [payload_hash] u64 xxh64 of the raw bytes (FLAG_PAYLOAD_HASH) body ``` `orig_size` is stored only when the shape does not give it: without `FLAG_SHAPE`, for a dtype code without a known element size, or when `product(shape) × element_size` differs from the raw byte count (for example a byte buffer with a shape in other units). A reader rejects `FLAG_SIZE` when the shape gives the same value. `FLAG_DTYPE_NAME` requires `FLAG_SHAPE` and a name that differs from the canonical name of `dtype_code`; `FLAG_SHAPE` without it requires a known dtype code. When `FLAG_STORED` is set, the body is the `orig_size` raw bytes. Else the body is a coded tensor: ```text chain: CW2 chain (chain::wire_compact); op_ref is the OpId wire id, and a bound Source takes the frame's shape and dtype_code per terminal plane, in chain terminal order: head: varint CodecId wire id << 2 | state state 0 = none, 1 = inline, 2 = inline, version 0, empty; 3 is rejected [state_version] u8 (state 1) [state_len] varint (state 1) [state] bytes (state 1) payload_len: varint [crc32] u32 CRC32 of the raw plane (FLAG_PLANE_CRC) payload: bytes ``` State 1 with version 0 and an empty state is rejected: state 2 is its only encoding. States 0 and 2 decode alike; the frame keeps the distinction the codec reported, and the reader accepts either. All integers are little-endian; varints are canonical unsigned LEB128 ([`crate::varint`]). A stored body must be exactly `orig_size` bytes, and a coded body must end exactly with the last plane's payload, so the reader rejects bytes appended to either. The payload hash covers the decoded bytes of the one tensor, and so every plane, so the writer stores plane CRCs only when it does not store the hash. Both checks verify decoded bytes; they do not cover the coded payload. Each header, chain and plane field has one encoding for the value it holds. The frame as a whole is not unique for a tensor: the writer chooses between a stored and a coded body, between plane state codes 0 and 2, and between codecs and chains, and the reader accepts any valid choice. The plane layout, the decoded plane length and the plane count all come from the chain, so the frame does not store them. Planes that need shared state (a prelude) or chunking cannot use this frame; the caller falls back to the full container for those. The magic differs from `\x89PTWM`, so readers that predate this frame reject it as "not a .ptwm container" instead of misparsing it. Like the container, the frame has no numeric version field: a reader rejects unknown flag bits, and an incompatible layout gets a new magic.
rstype

ptwm_core::compact::CompactTensor

crates/ptwm-core/src/compact.rs:141
pub struct CompactTensor

A tensor decoded from a compact frame.

rsfn

ptwm_core::compact::compress_compact

crates/ptwm-core/src/compact.rs:183
pub fn compress_compact(input: &InputTensor<'_>, opts: &CompressorOptions) -> Result<Option<Vec<u8>>, PtwmCoreError>

Encode one tensor as a compact frame.

Runs the same chain and codec search as [`crate::compressor::compress_model`], then writes the smaller of the coded body and the raw bytes. Returns `Ok(None)` when the tensor cannot use this frame: chunked encoding (`opts.chunk_size`) or a plane that selected shared state. The caller then writes a full container.
rsfn

ptwm_core::compact::decode_compact

crates/ptwm-core/src/compact.rs:407
pub fn decode_compact(buf: &[u8]) -> Result<CompactTensor, PtwmCoreError>

Decode a compact frame. Verifies the payload hash and plane CRCs when the frame carries them.

rsconst

ptwm_core::compact::FLAG_DELTA_REF

crates/ptwm-core/src/compact.rs:117
pub const FLAG_DELTA_REF

The frame carries the BLAKE3 hash of a delta reference.

rsconst

ptwm_core::compact::FLAG_DTYPE_NAME

crates/ptwm-core/src/compact.rs:115
pub const FLAG_DTYPE_NAME

The frame carries a dtype name that differs from the canonical name of `dtype_code`.

rsconst

ptwm_core::compact::FLAG_PAYLOAD_HASH

crates/ptwm-core/src/compact.rs:107
pub const FLAG_PAYLOAD_HASH

The frame carries an xxh64 of the raw bytes.

rsconst

ptwm_core::compact::FLAG_PLANE_CRC

crates/ptwm-core/src/compact.rs:110
pub const FLAG_PLANE_CRC

Every coded plane carries a CRC32 of its raw bytes. Not combined with [`FLAG_PAYLOAD_HASH`], which already covers every plane.

rsconst

ptwm_core::compact::FLAG_SHAPE

crates/ptwm-core/src/compact.rs:112
pub const FLAG_SHAPE

The frame carries the tensor shape.

rsconst

ptwm_core::compact::FLAG_SIZE

crates/ptwm-core/src/compact.rs:121
pub const FLAG_SIZE

The frame stores `orig_size` because the shape does not give it.

rsconst

ptwm_core::compact::FLAG_STORED

crates/ptwm-core/src/compact.rs:119
pub const FLAG_STORED

The body is the raw bytes, not a coded tensor.

rsfn

ptwm_core::compact::is_compact

crates/ptwm-core/src/compact.rs:160
pub fn is_compact(buf: &[u8]) -> bool

Return `true` when `buf` starts with the compact-frame magic.

rsconst

ptwm_core::compact::MAGIC_COMPACT

crates/ptwm-core/src/compact.rs:104
pub const MAGIC_COMPACT

Compact-frame magic. Shares the `\x89PTW` prefix with the full container.

rsfn

ptwm_core::compact::size_from_shape

crates/ptwm-core/src/compact.rs:167
pub fn size_from_shape(shape: &[u64], dtype_code: u16) -> Option<u64>

Raw byte count implied by a shape and a public dtype code: `product(shape) × element_size`. `None` for an unknown dtype code or on overflow.