Module fxar 

FXAR v2 archive format – gear-hash chunking, BLAKE3 CAS, binary index. FXAR v2: variable-size gear-hash chunking + BLAKE3 CAS + binary index. Replaces v1’s tar+whole-file-dedup with true chunk-level deduplication.

Archive layout: HEADER | MANIFEST | CHUNK INDEX | CHUNK DATA [ | FOOTER ]

Structs

ChunkIndexEntry

Binary chunk index entry (48 bytes, little-endian).

FileVersionInfo

Information about available versions for a file in the archive.

FxarExportStats

Statistics from an FXAR export operation.

FxarExtensionDirectory

Directory of extension sections appended to an FXAR archive.

FxarExtensionEntry

A single entry in the FXAR extension section directory.

FxarHeader

Binary header for FXAR v2 archives (64 bytes, little-endian).

FxarImportStats

Statistics from an FXAR import/restore operation.

FxarInspectResult

Result of inspecting an FXAR archive without extracting.

FxarManifest

Archive manifest listing all files and their chunk references.

FxarManifestEntry

A single file entry in the FXAR manifest.

FxarReader

Read an FXAR v2 archive with random access.

Constants

FLAG_HAS_EXTENSION_DIR

Flag indicating the archive contains an extension section directory. Set in FxarHeader.flags (bit 31 – does not overlap compression bits 0-4).

FXAR_EXT_CHUNK_MAP

Extension section type: chunk-level content map.

FXAR_EXT_FILE_MAP

Extension section type: file-level content map.

FXAR_EXT_HNSW

Extension section type: HNSW vector index.

Functions

detect_format

Detect archive format by reading magic bytes. Returns “fxar2” for FXAR v2, “tar” for tar archives, “unknown” otherwise.

inspect_archive

Inspect an FXAR v2 archive and return summary info.

prepare_ai_extension_sections

Read .foxing_index/ files from disk and return them as raw (section_type, bytes) pairs ready for write_archive_seekable_with_ai.

read_archive_stream

Read an FXAR v2 archive from a non-seekable stream.

update_fxar_ai_sections

Update the AI extension sections of an existing FXAR archive in-place.

write_archive

Write an FXAR v2 archive from a VersionStore (streaming – appends footer).

write_archive_from_directory

Write an FXAR v2 archive directly from a directory (no VersionStore required).

write_archive_from_directory_stream

Write an FXAR v2 archive from a directory to a non-seekable stream (appends footer).

write_archive_seekable

Write FXAR v2 with seekable writer – updates header offsets in-place.

write_archive_seekable_with_ai

write_archive_with_ai_index

Convenience wrapper: reads .foxing_index/ files via prepare_ai_extension_sections, then writes the archive with write_archive_seekable_with_ai.