Crate lamfold 

lamfold — read-only media filesystem stack (substrate core)

lamfold is an immutable-media filesystem stack: a shared no_std substrate under thin, clean-room format frontends (the flock). This crate is the substrate (L2) — the shared engine every frontend sits on:

• codec — the decompression-codec registry (deflate/lz4 wired; zstd/xz/lzo declared), one decoder shared across all compressed formats (decode, lz4_block_with_dict).
• BlockCache — an immutable decompressed-block LRU (read-only ⇒ no invalidation).
• read_cap — bounded-allocation hardening (no OOM on a hostile size; checked_full_read_len, checked_block_len).
• FoldFrontend — the trait the flock implements; Verifier — the shepherd (integrity-verification seam).
• BlockSource — the byte source a frontend reads over (LamBoot adapts its own BlockSource to this at integration).

Frontends (lamfold-iso, -udf, -squash, -erofs, …) live in their own crates and depend on this one. See the lamfold design spec.

Read-only by construction; #![forbid(unsafe_code)] in the substrate — zerocopy removes the transmute class, so the parse layer needs no unsafe.

Structs

BlockCache

A bounded LRU over decompressed blocks. Eviction is O(n) in the entry count, which is fine for the small working sets a bootloader/embedded reader holds.

DirEntry

MerkleVerifier

A Verifier over a single trusted file’s content (the dm-verity/composefs block-level model). Holds the trusted leaf-hash layer and the fs-verity measurement; Verifier::verify_block recomputes each block’s hash as it is read and refuses any mismatch — so tampered media fails the read instead of being trusted.

Metadata

NoVerifier

The no-op verifier: accepts everything. Used when the medium has no trust root (Secure Boot off, or a frontend without an integrity story yet).

SliceSource

A BlockSource over an in-memory byte slice — the workhorse for host tests and fixtures, and a legitimate source for an already-resident image.

SubstrateCtx

The shared substrate handed to a frontend on every call: the decompressed- block cache and the integrity verifier (the shepherd). Borrowed, never owned by the frontend, so one cache/verifier can serve nested frontends (a squashfs mounted over a file inside an iso).

Enums

Codec

The compressors a Family-A read-only format can use, matched to the crate that decodes each (the lamfold design spec §5).

FileKind

FoldError

Every fallible lamfold operation returns this. Variants carry a stable &'static str token (never an allocated string) so the type stays cheap and no_std-friendly, and so callers can log a stable token.

Constants

DEFAULT_BLOCK_LOG

fs-verity’s default block size is 4 KiB (log2 = 12).

MAX_BOOT_FILE_BYTES

Largest single file lamfold will allocate for a full read, while bounding a hostile inode size. 512 MiB — kept in lockstep with LamBoot’s consumer-side read_limit_pure::MAX_BOOT_FILE_BYTES. The earlier 256 MiB was too small: a real distro early-initramfs already exceeds it (Fedora-Workstation-Live-44’s /boot/x86_64/loader/initrd is 275 MiB; archiso’s is 238 MiB), so a 256 MiB cap rejected a legitimate boot file (file_too_large) and produced an empty initrd. Verified against real ISOs in the A2 live-VM matrix (2026-06-05).

MAX_DECOMPRESSED_BLOCK_BYTES

Largest single decompressed block lamfold will produce. Filesystem block / cluster sizes are small (squashfs ≤ 1 MiB, erofs clusters smaller); 16 MiB is a generous ceiling that still defuses a decompression bomb.

MAX_SYMLINKS

Maximum symlinks followed while resolving one path (loop/ELOOP guard).

Traits

BlockSource

A read-only, byte-addressed medium: a disc, a partition, an .iso file region, or (recursively) a file inside one of those.

FoldFrontend

A read-only media format frontend (a member of the flock). Generic over the BlockSource it reads, so the same frontend serves a whole partition, a logical volume, or an .iso loopback region — including recursively.

Verifier

Verifies a block of read-only data against a trusted integrity root.

Functions

checked_block_len

Validate a declared decompressed-block size before allocating its output buffer (the decompression-bomb guard).

checked_full_read_len

Validate a metadata-reported full-file size before vec![0u8; n]. Rejects anything over MAX_BOOT_FILE_BYTES or that does not fit usize.

decode

Decompress input into a fresh buffer. expected_len is the decompressed size the filesystem recorded for this block; it bounds the output (and is required by the size-less block codecs, lz4/lzo). The declared size is capped via checked_block_len before any allocation — the decompression-bomb guard.

fsverity_digest_sha256

Compute the fs-verity file digest (“measurement”) of data with SHA-256, the given block_log (log2 of the block size, e.g. 12 for 4 KiB), and an optional salt. Byte-identical to fsverity digest --hash-alg=sha256.

lz4_block_with_dict

LZ4 block decode with an external dictionary — the prior decompressed output that EROFS reaches into through its sliding window (lz4_max_distance, ≤ 64 KiB). Unlike decode, the dictionary is the bytes logically preceding this pcluster’s output, and the produced length is the pcluster’s exact decompressed size (expected_len). Used by lamfold-erofs’s compressed path.

metadata_path

Metadata by path (symlinks followed — so this reports the target’s kind).

microlzma_block_decode

Decode an EROFS MicroLZMA pcluster — a raw LZMA1 range-coded stream with no .xz/.lzma container, no 13-byte header, and no end-of-stream marker (the decompressed length is known). decode(Codec::Xz, ..) is the wrong path here: XzReader requires the .xz magic and rejects MicroLZMA.

read_dir_path

Directory listing by path (symlinks followed).

read_path

Read a whole file by path (symlinks followed), bounded by the substrate read cap. Errors with FoldError::IsDirectory if the path is a directory.

resolve

Resolve an absolute-or-relative path to a node, following symlinks. Leading /, empty components, and . are ignored; .. is rejected (a read-only boot reader has no use for parent traversal and it invites escapes).

Type Aliases

NodeId

An opaque per-volume node handle (an inode number, a directory-record LBA, an erofs nid — whatever the frontend uses internally).

Result

Sha256Digest

fs-verity SHA-256 digest (32 bytes).