Module pack 

STT packed format — a multi-object, edge-cacheable container.

Replaces the single-file v4 archive (ArchiveWriter) as the canonical write path. A single-file archive cannot be edge-cached once it exceeds the CDN per-object limit (Cloudflare = 512 MB): every range request hits origin forever. The packed format makes the cacheable unit a small object, not the whole dataset — tile blobs are split into many content-addressed pack objects (each ≤ pack_target_bytes) plus a tiny mutable manifest. A dumb CDN caches each immutable pack natively; no Worker, no vendor lock-in.

On-disk layout (per dataset)

<out_dir>/
  manifest.json            tiny, MUTABLE   → short TTL
  index/<blake3>.sttd      directory blob  → IMMUTABLE (content-addressed)
  packs/<blake3>.sttp      tile blob data  → IMMUTABLE (content-addressed)
  packs/<blake3>.sttp
  ...

Packs and the directory are content-addressed (blake3, 128-bit → 32 hex chars) so their bytes never change without their name changing. The directory is the v5 codec (crate::directory): per-run pack_id column + pack-relative offsets. See docs/spec/stt-packed-format.md for the full contract.

PackWriter reuses the dedup / per-blob-zstd / curve-ordering logic of ArchiveWriter::finalize_buffered, then cuts the ordered, deduped blob stream into packs. PackedReader is the local-file reader (the TS reader handles remote/HTTP); it mirrors ArchiveReader semantics.

Structs

BundleObject

One object entry in the bundle header’s objects table.

BundleSummary

Summary of a bundle pack/unpack for CLI reporting.

DirectoryRef

Pointer to the encoded directory object.

Manifest

The packed-format manifest.json — the only mutable object per dataset.

PackRef

Pointer to one pack object. The position in Manifest::packs is the pack_id the directory references.

PackWriter

Writer for the multi-object packed format.

PackedReader

Reader for a local packed dataset. Remote/HTTP reads are the TS reader’s job; this opens objects from the filesystem.

SchemaTemplateRef

One schema-template entry of a formatVersion-2 manifest’s schemas table: the blake3-128 content hash of the raw template bytes (32 lowercase hex chars — the hex form of the 16-byte reference v2 layer frames embed) and the raw template bytes, base64-encoded (standard alphabet, padded).

Constants

BUNDLE_MAGIC

First 4 bytes of a .sttb bundle file.

BUNDLE_VERSION

Bundle container version this toolchain writes and reads.

CAPABILITY_ATTR_QUANT

manifest.capabilities entry: numeric-attribute quantization (stt:qa re-types existing property columns to fixed-point integers).

CAPABILITY_COORD_QUANT

manifest.capabilities entry: coordinate quantization (stt:quant re-types the existing geometry column to fixed-point Int32).

CAPABILITY_ELEVATION_FOLD

manifest.capabilities entry: point-elevation fold (a property folded into POINT geometry z — the point leaf becomes 3 components instead of 2).

DEFAULT_PACK_TARGET_BYTES

Default pack target size — 64 MiB. Well under the 512 MB CDN per-object cap, with enough granularity for fine cache + parallel range reads.

DIRECTORY_ENCODING_ZSTD

At-rest encoding value for a zstd-compressed directory object.

DIRECTORY_LAYOUT_PAGED

directory.layout value for the paged container (root page + leaf pages, each independently framed). Absent or "single" = the whole-load v5 object.

DIRECTORY_LAYOUT_SINGLE

directory.layout value for the single whole-load object (the default).

DIRECTORY_MAGIC

First 4 bytes of a formatVersion-2 directory object.

KNOWN_CAPABILITIES

Every manifest.capabilities value this toolchain implements — the required-to-understand feature registry (docs/spec/stt-packed-format.md §3.1). Each capability RE-TYPES existing columns, so a reader that lacks it wouldn’t error downstream — it would silently misdecode (e.g. Int32 grid indices read as microscopic lon/lat degrees). A reader MUST therefore refuse, at open, any dataset declaring a capability outside its own set.

OBJECT_MAGIC_LEN

Length of the v2 object magic prelude: 4-byte tag + u8 version(2) + 3 zero bytes. Blob offsets in a v2 directory are object-absolute, so a pack’s first blob sits at offset 8; the manifest length fields and every blake3 content address cover the ENTIRE object including this prelude (★F5). v1 objects carry no magic (byte-frozen).

PACKED_FORMAT

format discriminator written into every packed manifest.

PACKED_FORMAT_VERSION

Packed-format version (the manifest schema, distinct from the directory codec’s crate::directory::DIRECTORY_VERSION) this writer emits by default. stt-build --format-version 1 is the transitional kill switch.

PACKED_FORMAT_VERSION_V1

The 0.3.x packed format: no object magic, v1 layer frames, no manifest schemas table. Frozen — PackWriter::with_format_version(1) MUST keep reproducing it byte-identically (pinned by tests/v1_golden.rs).

PACKED_FORMAT_VERSION_V2

The 2026-07 coordinated byte break (docs/roadmap/stt-packed-v2-design-2026-07.md): STTP/STTD object magic, object-absolute blob offsets, and v2 sectioned layer frames referencing manifest-embedded schema templates (manifest.schemas).

PACK_MAGIC

First 4 bytes of a formatVersion-2 pack object.

SUPPORTED_PACKED_FORMAT_VERSIONS

Every manifest.formatVersion this toolchain’s readers accept.

Functions

directory_codec_bytes

A directory object’s codec bytes: the whole object under v1, the post-magic slice under v2. (rootLength keeps meaning the root frame’s at-rest length — a paged root fetch is bytes=0..(8+rootLength-1) — so all downstream paged math is unchanged once the magic is stripped.) Public so out-of-band directory consumers (e.g. stt-validate’s direct paged-structure re-check) apply the same version-aware unwrap.

read_bundle_manifest

Read just the (typed) manifest out of a .sttb bundle header.

unpack_bundle

Explode a .sttb bundle back into a packed dataset directory: manifest.json (the verbatim header bytes) plus every object at its key path. Keys are traversal-validated and windows bounds-checked before anything is written. Objects are content-addressed, so callers can (and stt-bundle unpack does) run verify_packed_objects on the result to prove the round-trip byte-identical.

verify_bundle_objects

Bundle analog of verify_packed_objects: verify a .sttb’s contents against its embedded manifest with no trusted side-channel — each content-addressed object’s bytes must blake3-hash to its key, in-bundle lengths must match the manifest-declared lengths, the directory must decode (paged structure included), and no pack_id may fall outside the pack table.

verify_packed_objects

Verify the on-disk integrity of a packed dataset against its manifest.

write_bundle

Pack an exploded packed dataset into a single .sttb bundle file.