faf_fafb/
lib.rs

1//! faf-fafb — FAFb v2, the compiled binary form of `.faf`.
2//!
3//! IFF-inspired chunked binary: a string table for section names, a section
4//! table at the end for O(1) random access, classification bits (DNA /
5//! Context / Pointer), priority-based truncation, and a CRC32 seal over the
6//! source `.faf`.
7//!
8//! **Closed canonical.** The writer emits exactly the canonical chunk set
9//! (see [`canon`]), in canonical order; non-canonical top-level keys fold into
10//! the `context` chunk. The brick has two identities: a **Content ID** over
11//! stored content-chunk payloads, and a **file digest** over every byte.
12//! Stamps (timestamp, source CRC) do not enter the Content ID. The reader
13//! keeps the IFF rule (skip unknown section names gracefully), so a future
14//! minor version can add a chunk without breaking deployed readers.
15//!
16//! **v2 only.** FAFb v1 is pre-release history and is rejected on read
17//! (`IncompatibleVersion`) — re-compile from the `.faf` source, which is always
18//! the source of truth.
19//!
20//! **Stability — FAFb wire v2 is frozen.** The byte layout is immutable,
21//! enforced by a byte-exact golden-master test in this crate (`compile()` must
22//! reproduce the vendored `.fafb` byte-for-byte; any structural change is caught
23//! immediately). New capabilities ship only as forward-compatible additions —
24//! chunks or flag bits older readers skip; we do not break v2. Because the
25//! `.faf` source is always authoritative, you recompile, never migrate —
26//! nothing gets trapped in an old binary.
27//!
28//! ## Usage
29//!
30//! ```rust
31//! use faf_fafb::{compile, decompile, CompileOptions};
32//!
33//! let yaml = "faf_version: 2.5.0\nproject:\n  name: my-project\n";
34//! let opts = CompileOptions { use_timestamp: false };
35//! let bytes = compile(yaml, &opts).unwrap();
36//! let result = decompile(&bytes).unwrap();
37//! let name = result.get_section_string_by_name("project").unwrap();
38//! assert!(name.contains("my-project"));
39//! ```
40
41pub mod canon;
42pub mod compile;
43pub mod error;
44pub mod flags;
45pub mod header;
46pub mod identity;
47pub mod priority;
48pub mod section;
49pub mod string_table;
50
51// Re-exports for convenience
52pub use canon::{
53    CANONICAL_CHUNKS, CLASSIFICATION_MASK, CanonicalChunk, ChunkClassification, STRUCTURAL_CHUNKS,
54    canonical_chunk, is_canonical, is_known_structural, is_structural_name, is_valid_member_path,
55};
56pub use compile::{CompileOptions, DecompiledFafb, compile, decompile};
57pub use error::{FafbError, FafbResult};
58pub use flags::{
59    FLAG_COMPRESSED, FLAG_EMBEDDINGS, FLAG_MEMBERS, FLAG_MODEL_HINTS, FLAG_PROVENANCE,
60    FLAG_RESOLVED, FLAG_SIGNED, FLAG_STRING_TABLE, FLAG_TOKENIZED, FLAG_WEIGHTED, Flags,
61};
62pub use header::{
63    FafbHeader, HEADER_SIZE, MAGIC, MAGIC_U32, MAX_FILE_SIZE, MAX_SECTIONS, VERSION_MAJOR,
64    VERSION_MINOR, source_date_epoch,
65};
66pub use identity::{
67    TruncationTier, canonical_rendering, content_id, content_id_of, file_digest, hex_sha256,
68    truncated_rendering,
69};
70pub use priority::{
71    PRIORITY_CRITICAL, PRIORITY_HIGH, PRIORITY_LOW, PRIORITY_MEDIUM, PRIORITY_OPTIONAL, Priority,
72};
73pub use section::{SECTION_ENTRY_SIZE, SectionEntry, SectionTable};
74pub use string_table::StringTable;
75
76/// Library version
77pub const VERSION: &str = env!("CARGO_PKG_VERSION");
faf_fafb/lib.rs

faf_fafb/
lib.rs
