Module fttsq 

.fttsq — the canonical, portable, quantized model container.

What this format is, and what it deliberately is not

.fttsq is portable and machine-independent: tensor payloads, quantization scales, the frozen model config, provenance, and the license notice. It carries no machine-specific tiling — packed kernel layouts and the autotuned plan live in .fttspack, which is a regenerable per-machine cache. That split is the whole point: kernel layouts change often, and republishing a multi-gigabyte artifact every time a tile shape improves is not a cost we are willing to pay.

Access classes

Sections are grouped by how the runtime touches them, because the paging policy differs by an order of magnitude between them:

Class	Rough size	Access pattern
AccessClass::HotRecurrentMicrodecoder	~110 MB	reread 15× per frame — the residency target
AccessClass::HotRecurrentTalker	~440 MB	28 layers, once per frame
AccessClass::HotCodecDecoder	smaller	once per frame, latency-critical
AccessClass::ColdTextEmbedding	~622 MB	row-granular; never paged in wholesale
AccessClass::EnrollmentSpeakerEncoder / AccessClass::EnrollmentCodecEncoder	optional	enrollment only
AccessClass::Metadata	tiny	config, manifests, license

The cold text embedding is 622 MB that a synthesis run touches a few kilobytes of. Faulting it in as a unit would dominate startup and evict the microdecoder pack that the whole optimization program is built around, so its class is a load-bearing declaration, not a label.

Hardening

This reader parses attacker-influenced binary blobs — an artifact is just a file someone gives you. Every length and offset is checked arithmetic against the real file length, section ranges may not overlap, tensor ranges must lie inside their section, counts and dimensions are capped, and every section is digest-verified before its bytes are handed out. A malformed artifact is a named refusal, never a partial load that resurfaces later as garbage audio.

Layout

[0  .. 8 )   magic          b"FTTSQ\0\0\0"
[8  ..12 )   format_version u32 little-endian
[12 ..20 )   directory_len  u64 little-endian
[20 ..20+D)  directory      UTF-8 JSON
[20+D..   )  section payloads, at absolute offsets named in the directory

Bead: frankentts-p2-fttsq-format-wsa.

Structs

ArtifactCensus

The itemized result of an artifact census.

ArtifactManifest

The expected tensor inventory for one artifact.

ExpectedArtifactTensor

One tensor the artifact is required to carry, and where.

FttsqReader

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

FttsqStreamPlan

Metadata and fixed section lengths for a bounded .fttsq conversion.

FttsqStreamingWriter

A bounded writer for .fttsq section payloads.

FttsqWriter

Builds a .fttsq artifact.

MappedFttsq

A fully verified .fttsq held as a read-only mapping (or the safe owned-byte fallback).

PageAdviceApplication

One section’s page-in decision and what the loader actually requested.

SectionEntry

One access-class section: a contiguous, digest-verified byte range.

TensorEntry

One tensor, located relative to the start of its section.

Enums

AccessClass

How the runtime touches a section. Drives the page-in policy.

ArtifactFinding

One way an artifact diverged from its expected inventory.

FttsqError

What went wrong reading an artifact.

PageAdviceOutcome

The observable result of applying one access-class policy to a mapped section.

PagePolicy

What the loader should do with a section’s pages.

PageResidencyOutcome

An observed residency count for one section at a policy boundary.

StoredDtype

How a tensor’s elements are stored in the container.

Constants

FORMAT_VERSION

The format version this binary writes and is the newest it can read.

HEADER_PREFIX_BYTES

Fixed prefix length: magic + version + directory length.

MAGIC

File magic. Eight bytes so the directory length lands 8-byte aligned.

MAX_DIM

Largest single dimension. The largest real one is the 151,936-row text embedding.

MAX_DIRECTORY_BYTES

Largest directory we will parse, guarding against a hostile length prefix.

MAX_RANK

Most dimensions one tensor may have. The pinned checkpoint’s maximum rank is 4.

MAX_SECTIONS

Most sections an artifact may declare. Seven access classes, with headroom for splitting.

MAX_TENSORS

Most tensors an artifact may declare. The pinned checkpoint has 974.