Struct FttsqReader

Source

pub struct FttsqReader { /* private fields */ }

Expand description

A parsed, validated .fttsq directory over a buffer the reader does not own.

Implementations§

Source §

impl FttsqReader

Source

pub fn open(bytes: &[u8]) -> Result<Self, FttsqError>

Parses and fully validates an artifact, including every section digest.

Digest verification is not optional here. A reader that can be asked to skip it grows a caller that always skips it, and then corruption surfaces as audio rather than as an error.

§Errors

Returns a named FttsqError for any structural, range, or integrity violation.

Source

pub fn parse_directory(bytes: &[u8]) -> Result<Self, FttsqError>

Parses and structurally validates without computing digests.

For inspection tooling (ftts inspect) over an artifact whose bytes are not all present — listing a remote artifact’s tensors, say. Never use this to load weights: it does not prove the payload is intact.

§Errors

Returns a named FttsqError for any structural or range violation.

Source

pub fn parse_directory_of_prefix( bytes: &[u8], file_len: u64, ) -> Result<Self, FttsqError>

Parses the directory of a PREFIX, validating ranges against the artifact’s full length.

FttsqReader::parse_directory bounds every declared range by the bytes in hand, which is right for a whole file and wrong for a deliberate prefix: the section being left behind necessarily runs past the end, so parsing refuses before absence can even be considered. Here the structural check keeps its full strength against file_len — the artifact’s real size, known independently — while only the header and directory need to be present.

This proves structure, never integrity. Digests still decide what may be read, via FttsqReader::verify_digests_of_present.

§Errors

Returns a named FttsqError for any structural or range violation.

Source

pub fn verify_digests(&self, bytes: &[u8]) -> Result<(), FttsqError>

Recomputes and checks every section digest against bytes.

§Errors

Returns FttsqError::DigestMismatch naming the first corrupt section.

Source

pub fn verify_digests_of_present(&self, bytes: &[u8]) -> Result<(), FttsqError>

Verify every section the bytes fully contain, skipping those they stop short of.

The skip is deliberately silent because the caller has already classified what is absent and refused any section that was merely truncated — see [MappedFttsq::from_prefix_bytes]. What this verifies, it verifies exactly as FttsqReader::verify_digests does.

§Errors

On any present section whose payload does not match its declared digest.

Source

pub fn absent_sections_in_prefix( &self, available: u64, ) -> Result<Vec<String>, FttsqError>

Which sections a prefix of available bytes stops short of entirely.

A section is absent when it starts at or after the cut, and present when it ends at or before it. A section straddling the cut is neither: it cannot be digest-checked and must not be read, so it is an error rather than a third category. That distinction is what separates “the caller deliberately declined a trailing section” from “the download stopped early”, which would otherwise both arrive here looking identical.

§Errors

When the prefix splits a section, or a declared section’s range overflows.

Source

pub fn prefix_len_omitting(&self, omit: &[AccessClass]) -> Option<u64>

The shortest prefix that holds every section EXCEPT those in omit.

Returns None when omitting those classes would not leave a contiguous prefix — i.e. when a retained section sits after an omitted one. That is the guard that keeps the browser’s truncation honest against a future layout change: the saving depends on the omitted sections being last, and this is what refuses to assume it.

Source

pub const fn format_version(&self) -> u32

The format version the artifact declares.

Source

pub fn model_family(&self) -> &str

The model family the artifact was built from.

Source

pub fn source_sha256(&self) -> &str

SHA-256 of the upstream checkpoint this artifact was converted from.

Source

pub fn license_notice(&self) -> &str

The Apache-2.0 §4 attribution notice. Guaranteed non-empty.

Source

pub const fn model_config(&self) -> &Value

The frozen copy of the upstream model config.

Source

pub const fn quantization_manifest(&self) -> &Value

The per-tensor quantization policy actually applied, which the license notice references.

Source

pub fn sections(&self) -> &[SectionEntry]

Every declared section, in declaration order.

Source

pub fn tensors(&self) -> &[TensorEntry]

Every declared tensor, in declaration order.

Source

pub fn section(&self, name: &str) -> Option<&SectionEntry>

Looks a section up by name.

Source

pub fn tensor(&self, name: &str) -> Option<&TensorEntry>

Looks a tensor up by name.

Source

pub fn sections_in_class(&self, class: AccessClass) -> Vec<&SectionEntry>

Sections belonging to one access class.

Source

pub fn tensor_bytes<'a>( &self, name: &str, bytes: &'a [u8], ) -> Result<&'a [u8], FttsqError>

The byte span of one tensor within bytes.

§Errors

Returns FttsqError::UnknownSection when the tensor’s section is missing, or FttsqError::RangeOutOfBounds when the resolved span leaves the buffer.

Source

pub fn page_in_plan(&self) -> Vec<(&SectionEntry, PagePolicy)>

The page-in plan: every section paired with its policy, in the order to apply them.

Ordered PagePolicy::Resident first. Prefetch order matters under memory pressure — the section that gets its MADV_WILLNEED in last is the one most likely to find the page cache already full, and that must never be the microdecoder pack.

Within the resident group, smaller sections come first: the ~110 MB microdecoder pack lands ahead of the ~440 MB talker, so the reread-15×-per-frame working set wins the race for cache it would otherwise lose to a body read once per frame.

Source