//! The exFAT filesystem engine: mount a block device, walk the allocation
//! structures and directory entry sets, and (this step) resolve, list, and read.
//! Pure logic over a `BlockDevice` interface — no IPC — host-testable against a
//! RAM-backed image (the tests at the bottom build one with `formatExfat`). The
//! exfat.zig server wraps a real `.block` device and serves this over the VFS
//! protocol through the shared filesystem harness, exactly as fat.zig does.
//!
//! Three things differ from FAT and shape this file. A file is a directory-entry
//! SET — a File entry (0x85), a Stream Extension (0xC0), then File Name entries
//! (0xC1) — read as consecutive 32-byte entries that may cross sector and cluster
//! boundaries. A stream's `no_fat_chain` flag says its clusters are contiguous
//! (walk by arithmetic) or fragmented (follow the 32-bit FAT). And names are
//! matched case-folded through the volume's own on-disk up-case table, a bounded
//! prefix of which is loaded at mount. Allocation authority (the bitmap) is the
//! write path's concern (step 3); reads never touch it.
//!
//! Everything works in 512-byte sectors; a cluster is N sectors.

const std = @import("std");
const on_disk = @import("on-disk.zig");

const sector_size = 512;
const name_units_per_entry = on_disk.name_units_per_entry; // 15

/// bound: UTF-16 units of a file name (the longest name a listing/resolve handles)
/// decided-by: external
/// protects: the on-stack name buffers and the Listing name_buffer
/// at-limit: truncate - the exFAT format caps a name at 255 units, so a longer
///   name is impossible on a valid volume; a corrupt over-long name is cut and the
///   set's checksum mismatch (checked on read) flags it
/// observed-by: a set-checksum rejection in scanDirectory
const name_maximum = 255;

/// bound: code points whose case-fold the engine loads from the up-case table
/// decided-by: ours
/// protects: the in-memory `upcase` table
/// at-limit: truncate - code points at or above this fold to themselves, so two
///   names differing only in case ABOVE this point compare as distinct (danos
///   names are ASCII, far below it)
/// observed-by: a case-only-different high-plane name resolving as not-found
const upcase_fold_limit = 256;

/// bound: 32-byte entries one directory scan will read before giving up
/// decided-by: ours
/// protects: scanDirectory / mount against a directory with no end marker or a
///   cyclic cluster chain (a corrupt medium)
/// at-limit: truncate - entries beyond are not listed or resolved; a real
///   directory is far smaller, so hitting this means corruption
/// observed-by: an on-disk file absent from a listing under a huge directory
const directory_entry_scan_maximum = 65536;

/// The most sectors one multi-sector transfer moves (the DMA bounce the exfat
/// server sizes to). The engine's read path works a sector at a time, so this only
/// bounds the server's buffer; kept for parity with the fat engine.
/// bound: sectors in one coalesced device transfer
/// decided-by: ours
/// protects: the exfat server's DMA bounce buffer (max_transfer_sectors * 512)
/// at-limit: truncate - a longer run is split into several transfers, no data lost
/// observed-by: more device commands than the ideal, never a wrong byte
pub const max_transfer_sectors = 8;

const block_cache_lines = 16;

/// A block device the engine reads and writes in fixed-size blocks (identical to
/// the fat engine's — the shared harness is generic over whichever engine wraps a
/// real `.block` driver or, in tests, a RAM buffer).
pub const BlockDevice = struct {
    context: *anyopaque,
    block_size: u32,
    block_count: u64,
    readBlocksFn: *const fn (context: *anyopaque, lba: u64, count: u32, buffer: []u8) bool,
    writeBlocksFn: *const fn (context: *anyopaque, lba: u64, count: u32, buffer: []const u8) bool,

    pub fn readBlocks(self: BlockDevice, lba: u64, count: u32, buffer: []u8) bool {
        return self.readBlocksFn(self.context, lba, count, buffer);
    }
    pub fn writeBlocks(self: BlockDevice, lba: u64, count: u32, buffer: []const u8) bool {
        return self.writeBlocksFn(self.context, lba, count, buffer);
    }
    pub fn readBlock(self: BlockDevice, lba: u64, buffer: []u8) bool {
        return self.readBlocksFn(self.context, lba, 1, buffer);
    }
    pub fn writeBlock(self: BlockDevice, lba: u64, buffer: []const u8) bool {
        return self.writeBlocksFn(self.context, lba, 1, buffer);
    }
};

/// A resolved filesystem object and where its directory-entry set lives, so writes
/// (step 3) can rewrite the Stream entry's sizes/first-cluster and recompute the
/// set checksum.
pub const Node = struct {
    first_cluster: u32,
    size: u32, // data_length, clamped to the vfs u32 offset surface
    is_directory: bool,
    no_fat_chain: bool = false,
    valid_data_length: u32 = 0, // bytes actually written; [valid, size) read as zero
    mtime: u64 = 0,
    // The set's home: its parent directory's chain and the File entry's linear
    // 32-byte-entry index within it, plus how many secondary entries follow.
    parent_first_cluster: u32 = 0,
    parent_no_fat_chain: bool = false,
    entry_index: u64 = 0,
    secondary_count: u8 = 0,
    has_entry: bool = false,
};

pub const Listing = struct {
    name_buffer: [name_maximum]u8 = undefined,
    name_len: usize = 0,
    is_directory: bool = false,
    size: u32 = 0,
    mtime: u64 = 0,
};

const CacheLine = struct {
    lba: u64 = 0,
    valid: bool = false,
    data: [sector_size]u8 = undefined,
};

pub const FileSystem = struct {
    device: BlockDevice,
    geometry: on_disk.Geometry,
    base_lba: u64 = 0, // the volume manager confines the channel volume-relative
    sector: [sector_size]u8 = undefined,
    cache: [block_cache_lines]CacheLine = [_]CacheLine{.{}} ** block_cache_lines,
    cache_cursor: u32 = 0,
    // The case-fold table, a bounded prefix loaded at mount (unit -> uppercase).
    upcase: [upcase_fold_limit]u16 = undefined,
    upcase_len: usize = 0,
    // The allocation bitmap's location, for the write path (step 3).
    bitmap_first_cluster: u32 = 0,
    bitmap_length: u64 = 0, // bytes
    // Wall-clock (Unix epoch seconds) the server sets before a mutating op.
    current_time_epoch: u64 = 0,

    // --- single-sector write-through cache ----------------------------------

    fn cacheFind(self: *FileSystem, lba: u64) ?*CacheLine {
        for (&self.cache) |*line| if (line.valid and line.lba == lba) return line;
        return null;
    }
    fn cacheInstall(self: *FileSystem, lba: u64, data: []const u8) void {
        const line = self.cacheFind(lba) orelse blk: {
            const slot = &self.cache[self.cache_cursor];
            self.cache_cursor = (self.cache_cursor + 1) % block_cache_lines;
            slot.valid = true;
            slot.lba = lba;
            break :blk slot;
        };
        @memcpy(&line.data, data[0..sector_size]);
    }
    fn cacheInvalidateRange(self: *FileSystem, lba: u64, count: u32) void {
        for (&self.cache) |*line| {
            if (line.valid and line.lba >= lba and line.lba < lba + count) line.valid = false;
        }
    }

    fn blockRead(self: *FileSystem, lba: u64, buffer: []u8) bool {
        if (self.cacheFind(lba)) |line| {
            @memcpy(buffer[0..sector_size], &line.data);
            return true;
        }
        if (!self.device.readBlock(self.base_lba + lba, buffer)) return false;
        self.cacheInstall(lba, buffer);
        return true;
    }
    fn blockWrite(self: *FileSystem, lba: u64, buffer: []const u8) bool {
        if (!self.device.writeBlock(self.base_lba + lba, buffer)) return false;
        self.cacheInstall(lba, buffer);
        return true;
    }

    // --- cluster <-> sector, and the FAT ------------------------------------

    fn clusterBytes(self: *const FileSystem) u32 {
        return self.geometry.sectors_per_cluster * sector_size;
    }

    fn clusterSector(self: *const FileSystem, cluster: u32, sector_in_cluster: u32) u64 {
        return @as(u64, self.geometry.cluster_heap_offset_sectors) +
            @as(u64, cluster - 2) * self.geometry.sectors_per_cluster + sector_in_cluster;
    }

    fn validCluster(self: *const FileSystem, cluster: u32) bool {
        return cluster >= on_disk.first_data_cluster and cluster < self.geometry.cluster_count + on_disk.first_data_cluster;
    }

    /// Read the 32-bit FAT entry for `cluster` (exFAT's FAT is only consulted for a
    /// fragmented chain — a stream with `no_fat_chain` clear, or the metadata).
    fn readFatEntry(self: *FileSystem, cluster: u32) u32 {
        const byte = @as(u64, self.geometry.fat_offset_sectors) * sector_size + @as(u64, cluster) * 4;
        const lba = byte / sector_size;
        const within: usize = @intCast(byte % sector_size);
        if (!self.blockRead(lba, &self.sector)) return on_disk.end_of_chain;
        return std.mem.readInt(u32, self.sector[within..][0..4], .little);
    }

    fn isEndOfChain(_: *const FileSystem, value: u32) bool {
        return value >= 0xFFFFFFF8; // EOC (0xFFFFFFFF) or bad (0xFFFFFFF7) and up
    }

    /// The `index`-th cluster of a chain: contiguous arithmetic when `no_fat_chain`,
    /// else a FAT walk. Null past the end or off a corrupt/out-of-range link.
    fn clusterOfChain(self: *FileSystem, first: u32, no_fat_chain: bool, index: u32) ?u32 {
        if (!self.validCluster(first)) return null;
        if (no_fat_chain) {
            const cluster = first + index;
            return if (self.validCluster(cluster)) cluster else null;
        }
        var cluster = first;
        var steps = index;
        while (steps > 0) : (steps -= 1) {
            const next = self.readFatEntry(cluster);
            if (self.isEndOfChain(next) or !self.validCluster(next)) return null;
            cluster = next;
        }
        return cluster;
    }

    /// Read up to `out.len` bytes of a cluster chain starting at `byte_offset`,
    /// a sector at a time. Returns bytes produced (short at the chain's end).
    fn readChain(self: *FileSystem, first: u32, no_fat_chain: bool, byte_offset: u64, out: []u8) usize {
        const cluster_bytes = self.clusterBytes();
        var produced: usize = 0;
        var position = byte_offset;
        while (produced < out.len) {
            const cluster = self.clusterOfChain(first, no_fat_chain, @intCast(position / cluster_bytes)) orelse break;
            const in_cluster: u32 = @intCast(position % cluster_bytes);
            const lba = self.clusterSector(cluster, in_cluster / sector_size);
            const in_sector = in_cluster % sector_size;
            if (!self.blockRead(lba, &self.sector)) break;
            const n = @min(out.len - produced, sector_size - in_sector);
            @memcpy(out[produced .. produced + n], self.sector[in_sector .. in_sector + n]);
            produced += n;
            position += n;
        }
        return produced;
    }

    /// Read the `index`-th 32-byte directory entry (an entry never straddles a
    /// sector: 512/32 divides evenly and entries are 32-aligned).
    fn entryAt(self: *FileSystem, dir_first: u32, dir_no_fat_chain: bool, index: u64, out: *[on_disk.entry_bytes]u8) bool {
        return self.readChain(dir_first, dir_no_fat_chain, index * on_disk.entry_bytes, out) == on_disk.entry_bytes;
    }

    // --- the up-case table --------------------------------------------------

    fn fold(self: *const FileSystem, unit: u16) u16 {
        return if (unit < self.upcase_len) self.upcase[unit] else unit;
    }

    /// Load a bounded prefix of the on-disk up-case table (unit -> uppercase),
    /// decompressing 0xFFFF identity runs. Any prefix entry the table does not
    /// reach folds to itself.
    fn loadUpcase(self: *FileSystem, first_cluster: u32, data_length: u64) void {
        var raw: [upcase_fold_limit * 2]u8 = undefined;
        const want: usize = @intCast(@min(data_length, @as(u64, raw.len)));
        const got = self.readChain(first_cluster, false, 0, raw[0..want]);
        var out_index: usize = 0;
        var in_index: usize = 0;
        while (out_index < upcase_fold_limit and in_index + 2 <= got) {
            const value = std.mem.readInt(u16, raw[in_index..][0..2], .little);
            in_index += 2;
            if (value == 0xFFFF and in_index + 2 <= got) {
                var run = std.mem.readInt(u16, raw[in_index..][0..2], .little);
                in_index += 2;
                while (run > 0 and out_index < upcase_fold_limit) : (run -= 1) {
                    self.upcase[out_index] = @intCast(out_index);
                    out_index += 1;
                }
            } else {
                self.upcase[out_index] = value;
                out_index += 1;
            }
        }
        while (out_index < upcase_fold_limit) : (out_index += 1) self.upcase[out_index] = @intCast(out_index);
        self.upcase_len = upcase_fold_limit;
    }

    // --- mount --------------------------------------------------------------

    /// Mount an exFAT volume: read the VBR, load the geometry, then scan the root
    /// directory for the Allocation Bitmap (0x81) and Up-case Table (0x82). Null
    /// unless it is a 512-byte-sector exFAT volume.
    pub fn mount(device: BlockDevice) ?FileSystem {
        var boot: [sector_size]u8 = undefined;
        if (!device.readBlock(0, &boot)) return null;
        const geometry = on_disk.geometryOf(&boot) orelse return null;
        if (geometry.bytes_per_sector != sector_size) return null; // danos handles 512-byte sectors

        var fs = FileSystem{ .device = device, .geometry = geometry };
        // Identity fold until the table loads, so a volume with no up-case entry
        // still matches ASCII case-insensitively is NOT assumed — we only fold what
        // the table gives; unloaded means case-sensitive. loadUpcase fills it.
        fs.upcase_len = 0;

        var index: u64 = 0;
        var found_upcase = false;
        while (index < directory_entry_scan_maximum) : (index += 1) {
            var raw: [on_disk.entry_bytes]u8 = undefined;
            if (!fs.entryAt(geometry.first_cluster_of_root, false, index, &raw)) break;
            switch (raw[0]) {
                on_disk.entry_type_end_of_directory => break,
                on_disk.entry_type_allocation_bitmap => {
                    const entry = std.mem.bytesToValue(on_disk.AllocationBitmapEntry, &raw);
                    if (fs.bitmap_first_cluster == 0) { // the first (active, flags bit0=0) bitmap
                        fs.bitmap_first_cluster = entry.first_cluster;
                        fs.bitmap_length = entry.data_length;
                    }
                },
                on_disk.entry_type_upcase_table => {
                    if (!found_upcase) {
                        const entry = std.mem.bytesToValue(on_disk.UpcaseTableEntry, &raw);
                        fs.loadUpcase(entry.first_cluster, entry.data_length);
                        found_upcase = true;
                    }
                },
                else => {},
            }
        }
        return fs;
    }

    pub fn rootNode(self: *const FileSystem) Node {
        return .{
            .first_cluster = self.geometry.first_cluster_of_root,
            .size = 0,
            .is_directory = true,
            .no_fat_chain = false, // the root's chain is followed via the FAT
            .has_entry = false,
        };
    }

    // --- directory scan (entry-set assembly) --------------------------------

    fn nameMatches(self: *const FileSystem, display: []const u8, query: []const u8) bool {
        if (display.len != query.len) return false;
        for (display, query) |a, b| {
            if (self.fold(a) != self.fold(b)) return false;
        }
        return true;
    }

    /// Assemble each File-entry SET in `dir` and hand it to `visit`. Stops when
    /// `visit` returns true, the directory ends, or the scan cap is hit.
    fn scanDirectory(
        self: *FileSystem,
        dir: Node,
        context: anytype,
        comptime visit: fn (@TypeOf(context), node: Node, name: []const u8) bool,
    ) void {
        var index: u64 = 0;
        while (index < directory_entry_scan_maximum) {
            var raw: [on_disk.entry_bytes]u8 = undefined;
            if (!self.entryAt(dir.first_cluster, dir.no_fat_chain, index, &raw)) return;
            if (raw[0] == on_disk.entry_type_end_of_directory) return;
            if (raw[0] != on_disk.entry_type_file) {
                index += 1;
                continue;
            }
            const file = std.mem.bytesToValue(on_disk.FileEntry, &raw);

            var stream_raw: [on_disk.entry_bytes]u8 = undefined;
            if (!self.entryAt(dir.first_cluster, dir.no_fat_chain, index + 1, &stream_raw)) return;
            if (stream_raw[0] != on_disk.entry_type_stream_extension) {
                index += 1;
                continue; // a File entry without its Stream — malformed, skip
            }
            const stream = std.mem.bytesToValue(on_disk.StreamExtensionEntry, &stream_raw);

            // Reconstruct the name from the File Name entries, and validate the
            // whole set's checksum as we go (over File + Stream + Name bytes).
            var checksum_bytes: [on_disk.entry_bytes * (1 + 255)]u8 = undefined;
            @memcpy(checksum_bytes[0..on_disk.entry_bytes], &raw);
            @memcpy(checksum_bytes[on_disk.entry_bytes .. on_disk.entry_bytes * 2], &stream_raw);
            var set_bytes: usize = on_disk.entry_bytes * 2;

            var name_buf: [name_maximum]u8 = undefined;
            var name_len: usize = 0;
            const name_entries = (@as(usize, stream.name_length) + name_units_per_entry - 1) / name_units_per_entry;
            var e: usize = 0;
            var malformed = false;
            while (e < name_entries) : (e += 1) {
                var fn_raw: [on_disk.entry_bytes]u8 = undefined;
                if (!self.entryAt(dir.first_cluster, dir.no_fat_chain, index + 2 + e, &fn_raw)) return;
                if (fn_raw[0] != on_disk.entry_type_file_name) {
                    malformed = true;
                    break;
                }
                @memcpy(checksum_bytes[set_bytes .. set_bytes + on_disk.entry_bytes], &fn_raw);
                set_bytes += on_disk.entry_bytes;
                const name_entry = std.mem.bytesToValue(on_disk.FileNameEntry, &fn_raw);
                for (name_entry.file_name) |unit| {
                    if (name_len >= stream.name_length) break;
                    if (name_len < name_buf.len) name_buf[name_len] = if (unit < 0x80) @truncate(unit) else '?';
                    name_len += 1;
                }
            }
            const advance = @as(u64, file.secondary_count) + 1;
            if (malformed or on_disk.setChecksum(checksum_bytes[0..set_bytes]) != file.set_checksum) {
                index += advance;
                continue; // a set that does not check out is not a file
            }

            const node = Node{
                .first_cluster = stream.first_cluster,
                .size = clampU32(stream.data_length),
                .is_directory = file.file_attributes & on_disk.attribute_directory != 0,
                .no_fat_chain = stream.general_secondary_flags & on_disk.secondary_flag_no_fat_chain != 0,
                .valid_data_length = clampU32(stream.valid_data_length),
                .mtime = on_disk.timestampToEpoch(file.last_modified_timestamp),
                .parent_first_cluster = dir.first_cluster,
                .parent_no_fat_chain = dir.no_fat_chain,
                .entry_index = index,
                .secondary_count = file.secondary_count,
                .has_entry = true,
            };
            if (visit(context, node, name_buf[0..@min(name_len, name_buf.len)])) return;
            index += advance;
        }
    }

    const FindResult = struct { found: bool = false, node: Node = undefined };
    const FindContext = struct { fs: *FileSystem, query: []const u8, result: *FindResult };

    fn findVisit(context: *FindContext, node: Node, name: []const u8) bool {
        if (!context.fs.nameMatches(name, context.query)) return false;
        context.result.* = .{ .found = true, .node = node };
        return true;
    }

    fn findChild(self: *FileSystem, dir: Node, name: []const u8) ?Node {
        var result = FindResult{};
        var context = FindContext{ .fs = self, .query = name, .result = &result };
        self.scanDirectory(dir, &context, findVisit);
        return if (result.found) result.node else null;
    }

    /// Resolve an absolute or "/"-relative path to a node. "/" is the root.
    pub fn resolve(self: *FileSystem, path: []const u8) ?Node {
        var node = self.rootNode();
        var it = std.mem.tokenizeScalar(u8, path, '/');
        while (it.next()) |component| {
            if (component.len == 0) continue;
            if (!node.is_directory) return null;
            node = self.findChild(node, component) orelse return null;
        }
        return node;
    }

    const ListContext = struct { target: u32, index: u32 = 0, out: *Listing, done: bool = false };

    fn listVisit(context: *ListContext, node: Node, name: []const u8) bool {
        if (context.index == context.target) {
            const n = @min(name.len, context.out.name_buffer.len);
            @memcpy(context.out.name_buffer[0..n], name[0..n]);
            context.out.name_len = n;
            context.out.is_directory = node.is_directory;
            context.out.size = node.size;
            context.out.mtime = node.mtime;
            context.done = true;
            return true;
        }
        context.index += 1;
        return false;
    }

    /// The `cursor`th entry of a directory (for readdir): name, kind, size, mtime.
    pub fn listEntry(self: *FileSystem, dir: Node, cursor: u32) ?Listing {
        var listing = Listing{};
        var context = ListContext{ .target = cursor, .out = &listing };
        self.scanDirectory(dir, &context, listVisit);
        return if (context.done) listing else null;
    }

    // --- read ---------------------------------------------------------------

    /// Read up to `buffer.len` bytes of `node` from `offset`. Bytes at or past the
    /// stream's valid-data-length read as zero even though clusters are allocated.
    pub fn readFile(self: *FileSystem, node: Node, offset: u32, buffer: []u8) usize {
        if (offset >= node.size or !self.validCluster(node.first_cluster)) return 0;
        const want = @min(buffer.len, node.size - offset);
        const got = self.readChain(node.first_cluster, node.no_fat_chain, offset, buffer[0..want]);
        // Zero the region beyond valid_data_length (allocated but never written).
        if (offset + got > node.valid_data_length) {
            const zero_from: usize = if (offset >= node.valid_data_length) 0 else node.valid_data_length - offset;
            if (zero_from < got) @memset(buffer[zero_from..got], 0);
        }
        return got;
    }
};

fn clampU32(value: u64) u32 {
    return @intCast(@min(value, @as(u64, std.math.maxInt(u32))));
}

// --- tests: a RAM-backed exFAT image -----------------------------------------

const RamDisk = struct {
    bytes: []u8,
    fn readBlocks(context: *anyopaque, lba: u64, count: u32, buffer: []u8) bool {
        const self: *RamDisk = @ptrCast(@alignCast(context));
        const len = @as(usize, count) * sector_size;
        const start = lba * sector_size;
        if (start + len > self.bytes.len or buffer.len < len) return false;
        @memcpy(buffer[0..len], self.bytes[start .. start + len]);
        return true;
    }
    fn writeBlocks(context: *anyopaque, lba: u64, count: u32, buffer: []const u8) bool {
        const self: *RamDisk = @ptrCast(@alignCast(context));
        const len = @as(usize, count) * sector_size;
        const start = lba * sector_size;
        if (start + len > self.bytes.len or buffer.len < len) return false;
        @memcpy(self.bytes[start .. start + len], buffer[0..len]);
        return true;
    }
    fn device(self: *RamDisk) BlockDevice {
        return .{
            .context = self,
            .block_size = sector_size,
            .block_count = self.bytes.len / sector_size,
            .readBlocksFn = readBlocks,
            .writeBlocksFn = writeBlocks,
        };
    }
};

// A minimal exFAT layout for the tests: 512-byte clusters (spc=1), FAT at sector
// 8, cluster heap at sector 9. Cluster 2 = allocation bitmap, 3 = up-case table,
// 4 = root. Two files: HELLO (contiguous, clusters 5-6) and SPLIT (fragmented,
// clusters 7,9 linked through the FAT), each 1024 bytes (two clusters, so a read
// crosses a cluster boundary).
const test_clusters = 64;
const test_fat_sector = 8;
const test_heap_sector = 9;
const test_read_bytes = 1024; // the two-cluster test files are 1024 bytes

fn testCluster(cluster: u32) usize {
    return (test_heap_sector + (cluster - 2)) * sector_size;
}

fn writeFatEntry(bytes: []u8, cluster: u32, value: u32) void {
    std.mem.writeInt(u32, bytes[test_fat_sector * sector_size + cluster * 4 ..][0..4], value, .little);
}

fn asciiUpper(c: u8) u16 {
    return if (c >= 'a' and c <= 'z') c - 'a' + 'A' else c;
}

// Lay a File+Stream+Name set into the root at `entry_index`, naming `name` and
// pointing at `first_cluster`/`length`, contiguous or FAT-linked.
fn writeFileSet(bytes: []u8, entry_index: usize, name: []const u8, first_cluster: u32, length: u64, no_fat_chain: bool) void {
    const root = testCluster(4);
    var set: [on_disk.entry_bytes * 3]u8 = [_]u8{0} ** (on_disk.entry_bytes * 3);
    // File entry (0x85).
    set[0] = on_disk.entry_type_file;
    set[1] = 2; // stream + one name entry (names <= 15 units)
    std.mem.writeInt(u16, set[4..6], on_disk.attribute_archive, .little);
    // Stream entry (0xC0).
    const s = on_disk.entry_bytes;
    set[s + 0] = on_disk.entry_type_stream_extension;
    set[s + 1] = on_disk.secondary_flag_allocation_possible | (if (no_fat_chain) on_disk.secondary_flag_no_fat_chain else 0);
    set[s + 3] = @intCast(name.len); // name_length
    var upname: [name_maximum]u16 = undefined;
    for (name, 0..) |c, i| upname[i] = asciiUpper(c);
    std.mem.writeInt(u16, set[s + 4 ..][0..2], on_disk.nameHash(upname[0..name.len]), .little);
    std.mem.writeInt(u64, set[s + 8 ..][0..8], length, .little); // valid_data_length
    std.mem.writeInt(u32, set[s + 20 ..][0..4], first_cluster, .little);
    std.mem.writeInt(u64, set[s + 24 ..][0..8], length, .little); // data_length
    // File Name entry (0xC1).
    const f = on_disk.entry_bytes * 2;
    set[f + 0] = on_disk.entry_type_file_name;
    for (name, 0..) |c, i| std.mem.writeInt(u16, set[f + 2 + i * 2 ..][0..2], c, .little);
    // Set checksum (over all three entries, skipping its own two bytes).
    std.mem.writeInt(u16, set[2..4], on_disk.setChecksum(&set), .little);
    @memcpy(bytes[root + entry_index * on_disk.entry_bytes ..][0 .. on_disk.entry_bytes * 3], &set);
}

fn formatExfat(bytes: []u8) void {
    @memset(bytes, 0);
    // VBR (sector 0).
    @memcpy(bytes[3..11], "EXFAT   ");
    std.mem.writeInt(u64, bytes[72..80], bytes.len / sector_size, .little); // volume_length
    std.mem.writeInt(u32, bytes[80..84], test_fat_sector, .little); // fat_offset
    std.mem.writeInt(u32, bytes[84..88], 1, .little); // fat_length
    std.mem.writeInt(u32, bytes[88..92], test_heap_sector, .little); // cluster_heap_offset
    std.mem.writeInt(u32, bytes[92..96], test_clusters, .little); // cluster_count
    std.mem.writeInt(u32, bytes[96..100], 4, .little); // first_cluster_of_root
    std.mem.writeInt(u32, bytes[100..104], 0x1234ABCD, .little); // volume_serial_number
    bytes[108] = 9; // bytes_per_sector_shift = 512
    bytes[109] = 0; // sectors_per_cluster_shift = 1
    bytes[110] = 1; // number_of_fats
    bytes[510] = 0x55;
    bytes[511] = 0xAA;

    // FAT: reserved entries + the chains that must be walkable.
    writeFatEntry(bytes, 0, 0xFFFFFFF8);
    writeFatEntry(bytes, 1, 0xFFFFFFFF);
    for ([_]u32{ 2, 3, 4, 5, 6 }) |c| writeFatEntry(bytes, c, 0xFFFFFFFF); // metadata + contiguous file (single-cluster chains / EOC)
    writeFatEntry(bytes, 7, 9); // SPLIT: cluster 7 -> 9
    writeFatEntry(bytes, 9, 0xFFFFFFFF); // SPLIT ends

    // Allocation bitmap (cluster 2): clusters 2,3,4,5,6,7,9 in use.
    const bitmap = testCluster(2);
    for ([_]u32{ 2, 3, 4, 5, 6, 7, 9 }) |c| {
        const bit = c - 2;
        bytes[bitmap + bit / 8] |= @as(u8, 1) << @intCast(bit % 8);
    }

    // Up-case table (cluster 3): 256 explicit units, a-z -> A-Z.
    const upcase = testCluster(3);
    var i: u32 = 0;
    while (i < upcase_fold_limit) : (i += 1) {
        std.mem.writeInt(u16, bytes[upcase + i * 2 ..][0..2], asciiUpper(@intCast(i)), .little);
    }
    const table_checksum = on_disk.upcaseChecksum(bytes[upcase .. upcase + upcase_fold_limit * 2]);

    // Root directory (cluster 4): bitmap entry, up-case entry, then the two files.
    const root = testCluster(4);
    var bmp = std.mem.zeroes(on_disk.AllocationBitmapEntry);
    bmp.entry_type = on_disk.entry_type_allocation_bitmap;
    bmp.first_cluster = 2;
    bmp.data_length = (test_clusters + 7) / 8;
    @memcpy(bytes[root..][0..on_disk.entry_bytes], std.mem.asBytes(&bmp));
    var uct = std.mem.zeroes(on_disk.UpcaseTableEntry);
    uct.entry_type = on_disk.entry_type_upcase_table;
    uct.first_cluster = 3;
    uct.data_length = upcase_fold_limit * 2;
    uct.table_checksum = table_checksum;
    @memcpy(bytes[root + on_disk.entry_bytes ..][0..on_disk.entry_bytes], std.mem.asBytes(&uct));

    writeFileSet(bytes, 2, "HELLO", 5, 1024, true); // contiguous (clusters 5-6)
    writeFileSet(bytes, 5, "SPLIT", 7, 1024, false); // fragmented (clusters 7,9)

    // File contents: a distinct byte pattern per file, spanning both clusters.
    var b: usize = 0;
    while (b < 1024) : (b += 1) {
        bytes[testCluster(5) + b] = @truncate(b); // HELLO (5,6 contiguous)
    }
    b = 0;
    while (b < 512) : (b += 1) bytes[testCluster(7) + b] = @truncate(b +% 100); // SPLIT first cluster
    b = 0;
    while (b < 512) : (b += 1) bytes[testCluster(9) + b] = @truncate((b + 512) +% 100); // SPLIT second cluster
}

test "mount an exFAT image and read its geometry + up-case table" {
    const allocator = std.testing.allocator;
    const bytes = try allocator.alloc(u8, 128 * sector_size);
    defer allocator.free(bytes);
    formatExfat(bytes);

    var disk = RamDisk{ .bytes = bytes };
    var fs = FileSystem.mount(disk.device()) orelse return error.ShouldMount;
    try std.testing.expectEqual(@as(u32, 512), fs.geometry.bytes_per_sector);
    try std.testing.expectEqual(@as(u32, 4), fs.geometry.first_cluster_of_root);
    try std.testing.expectEqual(@as(u32, 2), fs.bitmap_first_cluster);
    // The up-case table loaded and folds ASCII.
    try std.testing.expectEqual(@as(u16, 'A'), fs.fold('a'));
    try std.testing.expectEqual(@as(u16, 'Z'), fs.fold('z'));
    try std.testing.expectEqual(@as(u16, '5'), fs.fold('5'));
}

test "list the root directory (skipping the bitmap/up-case entries)" {
    const allocator = std.testing.allocator;
    const bytes = try allocator.alloc(u8, 128 * sector_size);
    defer allocator.free(bytes);
    formatExfat(bytes);
    var disk = RamDisk{ .bytes = bytes };
    var fs = FileSystem.mount(disk.device()).?;

    const first = fs.listEntry(fs.rootNode(), 0).?;
    try std.testing.expectEqualStrings("HELLO", first.name_buffer[0..first.name_len]);
    try std.testing.expectEqual(@as(u32, 1024), first.size);
    const second = fs.listEntry(fs.rootNode(), 1).?;
    try std.testing.expectEqualStrings("SPLIT", second.name_buffer[0..second.name_len]);
    try std.testing.expect(fs.listEntry(fs.rootNode(), 2) == null);
}

test "resolve is case-insensitive through the up-case table" {
    const allocator = std.testing.allocator;
    const bytes = try allocator.alloc(u8, 128 * sector_size);
    defer allocator.free(bytes);
    formatExfat(bytes);
    var disk = RamDisk{ .bytes = bytes };
    var fs = FileSystem.mount(disk.device()).?;

    try std.testing.expect(fs.resolve("/hello") != null); // lower-case query matches HELLO
    try std.testing.expect(fs.resolve("/Hello") != null);
    try std.testing.expect(fs.resolve("/NOPE") == null);
    const node = fs.resolve("/HELLO").?;
    try std.testing.expectEqual(@as(u32, 5), node.first_cluster);
    try std.testing.expect(node.no_fat_chain);
}

test "read a contiguous file across its cluster boundary" {
    const allocator = std.testing.allocator;
    const bytes = try allocator.alloc(u8, 128 * sector_size);
    defer allocator.free(bytes);
    formatExfat(bytes);
    var disk = RamDisk{ .bytes = bytes };
    var fs = FileSystem.mount(disk.device()).?;

    const node = fs.resolve("/HELLO").?;
    var readback: [test_read_bytes]u8 = undefined;
    const got = fs.readFile(node, 0, &readback);
    try std.testing.expectEqual(@as(usize, 1024), got);
    for (readback, 0..) |byte, i| try std.testing.expectEqual(@as(u8, @truncate(i)), byte);
}

test "read a fragmented file follows the FAT across non-contiguous clusters" {
    const allocator = std.testing.allocator;
    const bytes = try allocator.alloc(u8, 128 * sector_size);
    defer allocator.free(bytes);
    formatExfat(bytes);
    var disk = RamDisk{ .bytes = bytes };
    var fs = FileSystem.mount(disk.device()).?;

    const node = fs.resolve("/SPLIT").?;
    try std.testing.expect(!node.no_fat_chain);
    var readback: [test_read_bytes]u8 = undefined;
    const got = fs.readFile(node, 0, &readback);
    try std.testing.expectEqual(@as(usize, 1024), got);
    // Cluster 7 held b+100; cluster 9 (the FAT-linked second) held (b+512)+100.
    for (readback, 0..) |byte, i| try std.testing.expectEqual(@as(u8, @truncate(i +% 100)), byte);
    // A mid-file read that starts in the second cluster still lands right.
    const mid = fs.readFile(node, 600, readback[0..10]);
    try std.testing.expectEqual(@as(usize, 10), mid);
    for (readback[0..10], 600..) |byte, i| try std.testing.expectEqual(@as(u8, @truncate(i +% 100)), byte);
}