Function commit_card_append 

pub fn commit_card_append(
    file: &mut File,
    plan: &CardAppendPlan,
    hash: [u8; 16],
    metadata: &[u8],
    build_info: &[u8],
) -> Result<Header, FileError>

Commit plan: write metadata, then build_info (outside the hash, so it may be sealed after card_append_hash), then a footer at the plan’s card offset, cut the file there, sync, and only then rewrite the 1 KiB header with hash and the new section entries, and sync again. Returns the header written.

Refuses a file whose header is no longer the one the plan was made from (another writer got there first). In place, nothing the old header points at is written before the new header lands: a crash before that leaves the old file, plus bytes past its end that the next run overwrites; a crash after it, the new file. The header is a single 1 KiB write at offset 0, inside the file’s first page.