(refactor): read and write crate cache blob sections via CacheBlobReader

[eytan-starkware]

Summary

Introduces CacheBlobReader and write_cache_section as shared abstractions for reading and writing length-prefixed sections within a crate cache blob. Each cache layer (def, semantic, lowering) now identifies its section by a named constant (DEF_CACHE_SECTION = 0, SEMANTIC_CACHE_SECTION = 1, LOWERING_CACHE_SECTION = 2) and uses CacheBlobReader::read_section to deserialize only the relevant section, replacing the manual byte-offset arithmetic that was previously duplicated across all three cache modules.

---

Type of change

Please check one:

• Bug fix (fixes incorrect behavior)
• New feature
• Performance improvement
• Documentation change with concrete technical impact
• Style, wording, formatting, or typo-only change

---

Why is this change needed?

Each of the three cache layers (def, semantic, lowering) independently computed byte offsets into the blob by reading and accumulating section sizes. This logic was error-prone, duplicated, and tightly coupled to the physical layout of the blob. A single mistake in one layer's offset arithmetic could silently read the wrong section.

---

What was the behavior or documentation before?

Each cache loader manually read the first 8 bytes as a big-endian u64 size, computed the start of the next section by adding that size, repeated this for each preceding section, and then sliced the raw byte array directly before deserializing with postcard.

---

What is the behavior or documentation after?

write_cache_section appends a length-prefixed section to a blob. CacheBlobReader wraps a byte slice and exposes next_section to advance past sections and read_section to skip to a specific section by index and deserialize it. Each cache layer calls CacheBlobReader::read_section with its section index constant, eliminating all manual offset arithmetic.

---

Related issue or discussion (if any)

---

Additional context

The blob format itself is unchanged — sections are still written in [def, semantic, lowering] order with an 8-byte big-endian length prefix per section. Only the reading and writing logic has been centralized.

[reviewable-StarkWare]

This change is 

[eytan-starkware]

• (opt): keep syntax node ids stable across reparses #10105
• (feat): cache external (plugin-generated) file content in the defs cache #10164
• (refactor): read and write crate cache blob sections via CacheBlobReader #10167 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

PR Summary

Low Risk
Refactor-only with unchanged blob format; risk is mainly mis-indexed sections or truncation handling, which still panics like before on bad blobs.

Overview
Centralizes how the compiler reads and writes length-prefixed sections in a crate cache blob. write_cache_section and CacheBlobReader (with next_section / read_section) live in cairo-lang-defs, along with CacheError and section index constants (DEF_CACHE_SECTION, SEMANTIC_CACHE_SECTION, LOWERING_CACHE_SECTION).

Def, semantic, and lowering cache loaders no longer duplicate manual byte-offset math; each calls CacheBlobReader::read_section with its section index. Crate cache generation in lowering appends all three sections through write_cache_section instead of inlined postcard + length headers. postcard is dropped as a direct dependency of semantic/lowering; lowering’s CrateCacheError now wraps defs’ CacheError.

The on-disk layout (ordered def → semantic → lowering, 8-byte big-endian lengths) is unchanged.

^{Reviewed by Cursor Bugbot for commit caad4bd. Bugbot is set up for automated code reviews on this repo. Configure here.}

[orizi]

@orizi reviewed 4 files and all commit messages, and made 2 comments.
Reviewable status: 4 of 7 files reviewed, 2 unresolved discussions (waiting on eytan-starkware and TomerStarkware).

---

crates/cairo-lang-lowering/src/cache/mod.rs line 61 at r1 (raw file):

type LookupCache = (CacheLookups, Vec<(DefsFunctionWithBodyIdCached, MultiLoweringCached)>);

const LOWERING_CACHE_SECTION: u8 = 2;

Suggestion:

const LOWERING_CACHE_SECTION: u8 = SEMANTIC+1;

---

crates/cairo-lang-semantic/src/cache/mod.rs line 67 at r1 (raw file):

type SemanticCache<'db> = (CrateSemanticCache, SemanticCacheLookups);

const SEMANTIC_CACHE_SECTION: u8 = 1;

Suggestion:

type SemanticCache<'db> = (CrateSemanticCache, SemanticCacheLookups);

const SEMANTIC_CACHE_SECTION: u8 = DEFS + 1;

[eytan-starkware]

@eytan-starkware made 2 comments.
Reviewable status: 3 of 7 files reviewed, 2 unresolved discussions (waiting on orizi and TomerStarkware).

---

crates/cairo-lang-lowering/src/cache/mod.rs line 61 at r1 (raw file):

type LookupCache = (CacheLookups, Vec<(DefsFunctionWithBodyIdCached, MultiLoweringCached)>);

const LOWERING_CACHE_SECTION: u8 = 2;

Done.

---

crates/cairo-lang-semantic/src/cache/mod.rs line 67 at r1 (raw file):

type SemanticCache<'db> = (CrateSemanticCache, SemanticCacheLookups);

const SEMANTIC_CACHE_SECTION: u8 = 1;

Done.

[orizi]

@orizi reviewed 4 files and all commit messages, made 1 comment, and resolved 2 discussions.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on TomerStarkware).