checksmix 0.3.10

use std::collections::{BTreeMap, HashMap};
#[cfg(any(unix, windows))]
use std::io::{stderr, stdin, stdout};
#[cfg(unix)]
use std::os::unix::io::AsRawFd;
#[cfg(windows)]
use std::os::windows::io::AsRawHandle;
use std::path::{Path, PathBuf};
use tracing::{debug, instrument};

use crate::mmix::{STACK_SEGMENT_START, TrapCode};
use pest_derive::Parser;
use regex::Regex;

const DATA_SEGMENT_START: u64 = 0x2000000000000000;

const POOL_SEGMENT_START: u64 = 0x4000000000000000;

#[cfg(unix)]
fn stdio_raw_identifiers() -> (u64, u64, u64) {
    (
        stdin().as_raw_fd() as u64,
        stdout().as_raw_fd() as u64,
        stderr().as_raw_fd() as u64,
    )
}

#[cfg(windows)]
fn stdio_raw_identifiers() -> (u64, u64, u64) {
    (
        stdin().as_raw_handle() as usize as u64,
        stdout().as_raw_handle() as usize as u64,
        stderr().as_raw_handle() as usize as u64,
    )
}

#[cfg(not(any(unix, windows)))]
fn stdio_raw_identifiers() -> (u64, u64, u64) {
    // Fallback: conventional descriptor ordering
    (0, 1, 2)
}

#[derive(Parser)]
#[grammar = "mmixal.pest"]
struct MMixalParser;

/// Type of symbol defined by IS directive
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum SymbolType {
    Register(u8),  // Register alias: "Zero IS $255" -> Register(255)
    Constant(u64), // Numeric constant: "MAXLIMBS IS 32" -> Constant(32)
}

impl std::fmt::Display for SymbolType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            SymbolType::Register(reg) => write!(f, "${}", reg),
            SymbolType::Constant(val) => write!(f, "{}", val),
        }
    }
}

/// MMIX Assembly Language Parser
/// Parses MMIX assembly language into binary object code (.mmo)
#[allow(clippy::upper_case_acronyms)]
#[derive(Debug, Clone, PartialEq)]
pub enum MMixInstruction {
    // Immediate load instructions
    SET(u8, u64),    // SET $X, value - pseudo-instruction
    SETRR(u8, u8),   // SET $X, $Y - register copy (emits ORI $X, $Y, 0)
    SETL(u8, u16),   // SETL $X, YZ - set low wyde
    SETH(u8, u16),   // SETH $X, YZ - set high wyde
    SETMH(u8, u16),  // SETMH $X, YZ - set medium high wyde
    SETML(u8, u16),  // SETML $X, YZ - set medium low wyde
    INCH(u8, u16),   // INCH $X, YZ - increment high wyde
    INCMH(u8, u16),  // INCMH $X, YZ - increment medium high wyde
    INCML(u8, u16),  // INCML $X, YZ - increment medium low wyde
    ORH(u8, u16),    // ORH $X, YZ - or high wyde
    ORMH(u8, u16),   // ORMH $X, YZ - or medium high wyde
    ORML(u8, u16),   // ORML $X, YZ - or medium low wyde
    ORL(u8, u16),    // ORL $X, YZ - or low wyde
    ANDNH(u8, u16),  // ANDNH $X, YZ - and-not high wyde
    ANDNMH(u8, u16), // ANDNMH $X, YZ - and-not medium high wyde
    ANDNML(u8, u16), // ANDNML $X, YZ - and-not medium low wyde
    ANDNL(u8, u16),  // ANDNL $X, YZ - and-not low wyde

    // Load instructions
    LDB(u8, u8, u8),    // LDB $X, $Y, $Z - load byte signed
    LDBI(u8, u8, u8),   // LDB $X, $Y, Z - load byte signed (immediate)
    LDBU(u8, u8, u8),   // LDBU $X, $Y, $Z - load byte unsigned
    LDBUI(u8, u8, u8),  // LDBU $X, $Y, Z - load byte unsigned (immediate)
    LDW(u8, u8, u8),    // LDW $X, $Y, $Z - load wyde signed
    LDWI(u8, u8, u8),   // LDW $X, $Y, Z - load wyde signed (immediate)
    LDWU(u8, u8, u8),   // LDWU $X, $Y, $Z - load wyde unsigned
    LDWUI(u8, u8, u8),  // LDWU $X, $Y, Z - load wyde unsigned (immediate)
    LDT(u8, u8, u8),    // LDT $X, $Y, $Z - load tetra signed
    LDTI(u8, u8, u8),   // LDT $X, $Y, Z - load tetra signed (immediate)
    LDTU(u8, u8, u8),   // LDTU $X, $Y, $Z - load tetra unsigned
    LDTUI(u8, u8, u8),  // LDTU $X, $Y, Z - load tetra unsigned (immediate)
    LDO(u8, u8, u8),    // LDO $X, $Y, $Z - load octa
    LDOI(u8, u8, u8),   // LDO $X, $Y, Z - load octa (immediate)
    LDOU(u8, u8, u8),   // LDOU $X, $Y, $Z - load octa unsigned
    LDOUI(u8, u8, u8),  // LDOU $X, $Y, Z - load octa unsigned (immediate)
    LDUNC(u8, u8, u8),  // LDUNC $X, $Y, $Z - load octa uncached
    LDUNCI(u8, u8, u8), // LDUNC $X, $Y, Z - load octa uncached (immediate)
    LDHT(u8, u8, u8),   // LDHT $X, $Y, $Z - load high tetra
    LDHTI(u8, u8, u8),  // LDHT $X, $Y, Z - load high tetra (immediate)
    LDSF(u8, u8, u8),   // LDSF $X, $Y, $Z - load short float
    LDSFI(u8, u8, u8),  // LDSF $X, $Y, Z - load short float (immediate)
    LDVTS(u8, u8, u8),  // LDVTS $X, $Y, $Z - load virtual translation status
    LDVTSI(u8, u8, u8), // LDVTS $X, $Y, Z - load virtual translation status (immediate)
    CSWAP(u8, u8, u8),  // CSWAP $X, $Y, $Z - compare and swap
    CSWAPI(u8, u8, u8), // CSWAP $X, $Y, Z - compare and swap (immediate)
    LDA(u8, u8, u8),    // LDA $X, $Y, $Z - load address (ADDU)
    LDAI(u8, u8, u8),   // LDA $X, $Y, Z - load address (immediate)

    // Store instructions
    STB(u8, u8, u8),    // STB $X, $Y, $Z - store byte signed
    STBI(u8, u8, u8),   // STB $X, $Y, Z - store byte signed (immediate)
    STBU(u8, u8, u8),   // STBU $X, $Y, $Z - store byte unsigned
    STBUI(u8, u8, u8),  // STBU $X, $Y, Z - store byte unsigned (immediate)
    STW(u8, u8, u8),    // STW $X, $Y, $Z - store wyde signed
    STWI(u8, u8, u8),   // STW $X, $Y, Z - store wyde signed (immediate)
    STWU(u8, u8, u8),   // STWU $X, $Y, $Z - store wyde unsigned
    STWUI(u8, u8, u8),  // STWU $X, $Y, Z - store wyde unsigned (immediate)
    STT(u8, u8, u8),    // STT $X, $Y, $Z - store tetra signed
    STTI(u8, u8, u8),   // STT $X, $Y, Z - store tetra signed (immediate)
    STTU(u8, u8, u8),   // STTU $X, $Y, $Z - store tetra unsigned
    STTUI(u8, u8, u8),  // STTU $X, $Y, Z - store tetra unsigned (immediate)
    STO(u8, u8, u8),    // STO $X, $Y, $Z - store octa
    STOI(u8, u8, u8),   // STO $X, $Y, Z - store octa (immediate)
    STOU(u8, u8, u8),   // STOU $X, $Y, $Z - store octa unsigned
    STOUI(u8, u8, u8),  // STOU $X, $Y, Z - store octa unsigned (immediate)
    STUNC(u8, u8, u8),  // STUNC $X, $Y, $Z - store octa uncached
    STUNCI(u8, u8, u8), // STUNC $X, $Y, Z - store octa uncached (immediate)
    STCO(u8, u8, u8),   // STCO X, $Y, $Z - store constant octabyte
    STCOI(u8, u8, u8),  // STCO X, $Y, Z - store constant octabyte (immediate)
    STHT(u8, u8, u8),   // STHT $X, $Y, $Z - store high tetra
    STHTI(u8, u8, u8),  // STHT $X, $Y, Z - store high tetra (immediate)
    STSF(u8, u8, u8),   // STSF $X, $Y, $Z - store short float
    STSFI(u8, u8, u8),  // STSF $X, $Y, Z - store short float (immediate)

    // Arithmetic - Add and Subtract
    ADD(u8, u8, u8),     // ADD $X, $Y, $Z - add with overflow
    ADDI(u8, u8, u8),    // ADD $X, $Y, Z - add immediate with overflow
    ADDU(u8, u8, u8),    // ADDU $X, $Y, $Z - add unsigned (same as LDA)
    ADDUI(u8, u8, u8),   // ADDU $X, $Y, Z - add unsigned immediate
    ADDU2(u8, u8, u8),   // 2ADDU $X, $Y, $Z - times 2 and add unsigned
    ADDU2I(u8, u8, u8),  // 2ADDU $X, $Y, Z - times 2 and add unsigned immediate
    ADDU4(u8, u8, u8),   // 4ADDU $X, $Y, $Z - times 4 and add unsigned
    ADDU4I(u8, u8, u8),  // 4ADDU $X, $Y, Z - times 4 and add unsigned immediate
    ADDU8(u8, u8, u8),   // 8ADDU $X, $Y, $Z - times 8 and add unsigned
    ADDU8I(u8, u8, u8),  // 8ADDU $X, $Y, Z - times 8 and add unsigned immediate
    ADDU16(u8, u8, u8),  // 16ADDU $X, $Y, $Z - times 16 and add unsigned
    ADDU16I(u8, u8, u8), // 16ADDU $X, $Y, Z - times 16 and add unsigned immediate
    SUB(u8, u8, u8),     // SUB $X, $Y, $Z - subtract with overflow
    SUBI(u8, u8, u8),    // SUB $X, $Y, Z - subtract immediate with overflow
    SUBU(u8, u8, u8),    // SUBU $X, $Y, $Z - subtract unsigned
    SUBUI(u8, u8, u8),   // SUBU $X, $Y, Z - subtract unsigned immediate
    NEG(u8, u8, u8),     // NEG $X, Y, $Z - negate with overflow (Y is immediate)
    NEGI(u8, u8, u8),    // NEG $X, Y, Z - negate immediate with overflow
    NEGU(u8, u8, u8),    // NEGU $X, Y, $Z - negate unsigned
    NEGUI(u8, u8, u8),   // NEGU $X, Y, Z - negate unsigned immediate

    MUL(u8, u8, u8),   // MUL $X, $Y, $Z - multiply
    MULI(u8, u8, u8),  // MUL $X, $Y, Z - multiply immediate
    MULU(u8, u8, u8),  // MULU $X, $Y, $Z - multiply unsigned
    MULUI(u8, u8, u8), // MULU $X, $Y, Z - multiply unsigned immediate
    DIV(u8, u8, u8),   // DIV $X, $Y, $Z - divide
    DIVI(u8, u8, u8),  // DIV $X, $Y, Z - divide immediate
    DIVU(u8, u8, u8),  // DIVU $X, $Y, $Z - divide unsigned
    DIVUI(u8, u8, u8), // DIVU $X, $Y, Z - divide unsigned immediate

    // Floating point instructions
    FCMP(u8, u8, u8),    // FCMP $X, $Y, $Z - floating compare
    FUN(u8, u8, u8),     // FUN $X, $Y, $Z - floating unordered
    FEQL(u8, u8, u8),    // FEQL $X, $Y, $Z - floating equal
    FCMPE(u8, u8, u8),   // FCMPE $X, $Y, $Z - floating compare with epsilon (rE)
    FUNE(u8, u8, u8),    // FUNE $X, $Y, $Z - floating unordered with epsilon (rE)
    FEQLE(u8, u8, u8),   // FEQLE $X, $Y, $Z - floating equivalent with epsilon (rE)
    FADD(u8, u8, u8),    // FADD $X, $Y, $Z - floating add
    FIX(u8, u8, u8),     // FIX $X, $Y, $Z - convert float to fixed
    FSUB(u8, u8, u8),    // FSUB $X, $Y, $Z - floating subtract
    FIXU(u8, u8, u8),    // FIXU $X, $Y, $Z - convert float to fixed unsigned
    FLOT(u8, u8, u8),    // FLOT $X, $Y, $Z - convert fixed to float
    FLOTI(u8, u8, u8),   // FLOTI $X, $Y, Z - convert fixed to float immediate
    FLOTU(u8, u8, u8),   // FLOTU $X, $Y, $Z - convert fixed unsigned to float
    FLOTUI(u8, u8, u8),  // FLOTUI $X, $Y, Z - convert fixed unsigned to float immediate
    SFLOT(u8, u8, u8),   // SFLOT $X, $Y, $Z - convert fixed to short float
    SFLOTI(u8, u8, u8),  // SFLOTI $X, $Y, Z - convert fixed to short float immediate
    SFLOTU(u8, u8, u8),  // SFLOTU $X, $Y, $Z - convert fixed unsigned to short float
    SFLOTUI(u8, u8, u8), // SFLOTUI $X, $Y, Z - convert fixed unsigned to short float immediate
    FMUL(u8, u8, u8),    // FMUL $X, $Y, $Z - floating multiply
    FDIV(u8, u8, u8),    // FDIV $X, $Y, $Z - floating divide
    FREM(u8, u8, u8),    // FREM $X, $Y, $Z - floating remainder
    FSQRT(u8, u8, u8),   // FSQRT $X, $Y, $Z - floating square root
    FINT(u8, u8, u8),    // FINT $X, $Y, $Z - floating round to integer

    // Comparison instructions
    CMP(u8, u8, u8),   // CMP $X, $Y, $Z - compare signed
    CMPI(u8, u8, u8),  // CMP $X, $Y, Z - compare signed immediate
    CMPU(u8, u8, u8),  // CMPU $X, $Y, $Z - compare unsigned
    CMPUI(u8, u8, u8), // CMPU $X, $Y, Z - compare unsigned immediate

    INCL(u8, u16), // INCL $X, YZ - increment low wyde

    // Bitwise operations
    AND(u8, u8, u8),   // AND $X, $Y, $Z - bitwise and
    ANDI(u8, u8, u8),  // AND $X, $Y, Z - bitwise and immediate
    OR(u8, u8, u8),    // OR $X, $Y, $Z - bitwise or
    ORI(u8, u8, u8),   // OR $X, $Y, Z - bitwise or immediate
    XOR(u8, u8, u8),   // XOR $X, $Y, $Z - bitwise exclusive-or
    XORI(u8, u8, u8),  // XOR $X, $Y, Z - bitwise exclusive-or immediate
    ANDN(u8, u8, u8),  // ANDN $X, $Y, $Z - bitwise and-not
    ANDNI(u8, u8, u8), // ANDN $X, $Y, Z - bitwise and-not immediate
    ORN(u8, u8, u8),   // ORN $X, $Y, $Z - bitwise or-not
    ORNI(u8, u8, u8),  // ORN $X, $Y, Z - bitwise or-not immediate
    NAND(u8, u8, u8),  // NAND $X, $Y, $Z - bitwise not-and
    NANDI(u8, u8, u8), // NAND $X, $Y, Z - bitwise not-and immediate
    NOR(u8, u8, u8),   // NOR $X, $Y, $Z - bitwise not-or
    NORI(u8, u8, u8),  // NOR $X, $Y, Z - bitwise not-or immediate
    NXOR(u8, u8, u8),  // NXOR $X, $Y, $Z - bitwise not-exclusive-or
    NXORI(u8, u8, u8), // NXOR $X, $Y, Z - bitwise not-exclusive-or immediate
    MUX(u8, u8, u8),   // MUX $X, $Y, $Z - bitwise multiplex
    MUXI(u8, u8, u8),  // MUX $X, $Y, Z - bitwise multiplex immediate

    // Bit fiddling operations
    BDIF(u8, u8, u8),  // BDIF $X, $Y, $Z - byte difference
    BDIFI(u8, u8, u8), // BDIF $X, $Y, Z - byte difference immediate
    WDIF(u8, u8, u8),  // WDIF $X, $Y, $Z - wyde difference
    WDIFI(u8, u8, u8), // WDIF $X, $Y, Z - wyde difference immediate
    TDIF(u8, u8, u8),  // TDIF $X, $Y, $Z - tetra difference
    TDIFI(u8, u8, u8), // TDIF $X, $Y, Z - tetra difference immediate
    ODIF(u8, u8, u8),  // ODIF $X, $Y, $Z - octa difference
    ODIFI(u8, u8, u8), // ODIF $X, $Y, Z - octa difference immediate
    SADD(u8, u8, u8),  // SADD $X, $Y, $Z - sideways add
    SADDI(u8, u8, u8), // SADD $X, $Y, Z - sideways add immediate
    MOR(u8, u8, u8),   // MOR $X, $Y, $Z - multiple or
    MORI(u8, u8, u8),  // MOR $X, $Y, Z - multiple or immediate
    MXOR(u8, u8, u8),  // MXOR $X, $Y, $Z - multiple exclusive-or
    MXORI(u8, u8, u8), // MXOR $X, $Y, Z - multiple exclusive-or immediate

    // Shift instructions
    SL(u8, u8, u8),   // SL $X, $Y, $Z - shift left
    SLI(u8, u8, u8),  // SL $X, $Y, Z - shift left immediate
    SLU(u8, u8, u8),  // SLU $X, $Y, $Z - shift left unsigned
    SLUI(u8, u8, u8), // SLU $X, $Y, Z - shift left unsigned immediate
    SR(u8, u8, u8),   // SR $X, $Y, $Z - shift right
    SRI(u8, u8, u8),  // SR $X, $Y, Z - shift right immediate
    SRU(u8, u8, u8),  // SRU $X, $Y, $Z - shift right unsigned
    SRUI(u8, u8, u8), // SRU $X, $Y, Z - shift right unsigned immediate

    // Branch instructions
    JMP(u32),          // JMP XYZ (24-bit), jump to @ + 4*XYZ
    JMPB(u32),         // JMPB XYZ (24-bit), jump to @ + 4*(XYZ - 2^24)
    BN(u8, u16),       // BN $X, offset - branch if negative
    BNB(u8, u16),      // BNB $X, offset - branch if negative backward
    BZ(u8, u16),       // BZ $X, offset - branch if zero
    BZB(u8, u16),      // BZB $X, offset - branch if zero backward
    BP(u8, u16),       // BP $X, offset - branch if positive
    BPB(u8, u16),      // BPB $X, offset - branch if positive backward
    BOD(u8, u16),      // BOD $X, offset - branch if odd
    BODB(u8, u16),     // BODB $X, offset - branch if odd backward
    BNN(u8, u16),      // BNN $X, offset - branch if non-negative
    BNNB(u8, u16),     // BNNB $X, offset - branch if non-negative backward
    BNZ(u8, u16),      // BNZ $X, offset - branch if non-zero
    BNZB(u8, u16),     // BNZB $X, offset - branch if non-zero backward
    BNP(u8, u16),      // BNP $X, offset - branch if non-positive
    BNPB(u8, u16),     // BNPB $X, offset - branch if non-positive backward
    BEV(u8, u16),      // BEV $X, offset - branch if even
    BEVB(u8, u16),     // BEVB $X, offset - branch if even backward
    PBN(u8, u8, u8),   // PBN $X, Y, Z - probable branch negative (Y,Z = offset)
    PBNB(u8, u8, u8),  // PBNB $X, Y, Z - probable branch negative backward
    PBZ(u8, u8, u8),   // PBZ $X, Y, Z - probable branch zero
    PBZB(u8, u8, u8),  // PBZB $X, Y, Z - probable branch zero backward
    PBP(u8, u8, u8),   // PBP $X, Y, Z - probable branch positive
    PBPB(u8, u8, u8),  // PBPB $X, Y, Z - probable branch positive backward
    PBOD(u8, u8, u8),  // PBOD $X, Y, Z - probable branch odd
    PBODB(u8, u8, u8), // PBODB $X, Y, Z - probable branch odd backward
    PBNN(u8, u8, u8),  // PBNN $X, Y, Z - probable branch nonnegative
    PBNNB(u8, u8, u8), // PBNNB $X, Y, Z - probable branch nonnegative backward
    PBNZ(u8, u8, u8),  // PBNZ $X, Y, Z - probable branch nonzero
    PBNZB(u8, u8, u8), // PBNZB $X, Y, Z - probable branch nonzero backward
    PBNP(u8, u8, u8),  // PBNP $X, Y, Z - probable branch nonpositive
    PBNPB(u8, u8, u8), // PBNPB $X, Y, Z - probable branch nonpositive backward
    PBEV(u8, u8, u8),  // PBEV $X, Y, Z - probable branch even
    PBEVB(u8, u8, u8), // PBEVB $X, Y, Z - probable branch even backward

    // Conditional set instructions
    CSN(u8, u8, u8),   // CSN $X, $Y, $Z - conditional set if negative
    CSNI(u8, u8, u8),  // CSNI $X, $Y, Z - conditional set if negative immediate
    CSZ(u8, u8, u8),   // CSZ $X, $Y, $Z - conditional set if zero
    CSZI(u8, u8, u8),  // CSZI $X, $Y, Z - conditional set if zero immediate
    CSP(u8, u8, u8),   // CSP $X, $Y, $Z - conditional set if positive
    CSPI(u8, u8, u8),  // CSPI $X, $Y, Z - conditional set if positive immediate
    CSOD(u8, u8, u8),  // CSOD $X, $Y, $Z - conditional set if odd
    CSODI(u8, u8, u8), // CSODI $X, $Y, Z - conditional set if odd immediate
    CSNN(u8, u8, u8),  // CSNN $X, $Y, $Z - conditional set if non-negative
    CSNNI(u8, u8, u8), // CSNNI $X, $Y, Z - conditional set if non-negative immediate
    CSNZ(u8, u8, u8),  // CSNZ $X, $Y, $Z - conditional set if non-zero
    CSNZI(u8, u8, u8), // CSNZI $X, $Y, Z - conditional set if non-zero immediate
    CSNP(u8, u8, u8),  // CSNP $X, $Y, $Z - conditional set if non-positive
    CSNPI(u8, u8, u8), // CSNPI $X, $Y, Z - conditional set if non-positive immediate
    CSEV(u8, u8, u8),  // CSEV $X, $Y, $Z - conditional set if even
    CSEVI(u8, u8, u8), // CSEVI $X, $Y, Z - conditional set if even immediate

    // Zero or set instructions
    ZSN(u8, u8, u8),   // ZSN $X, $Y, $Z - zero or set if negative
    ZSNI(u8, u8, u8),  // ZSNI $X, $Y, Z - zero or set if negative immediate
    ZSZ(u8, u8, u8),   // ZSZ $X, $Y, $Z - zero or set if zero
    ZSZI(u8, u8, u8),  // ZSZI $X, $Y, Z - zero or set if zero immediate
    ZSP(u8, u8, u8),   // ZSP $X, $Y, $Z - zero or set if positive
    ZSPI(u8, u8, u8),  // ZSPI $X, $Y, Z - zero or set if positive immediate
    ZSOD(u8, u8, u8),  // ZSOD $X, $Y, $Z - zero or set if odd
    ZSODI(u8, u8, u8), // ZSODI $X, $Y, Z - zero or set if odd immediate
    ZSNN(u8, u8, u8),  // ZSNN $X, $Y, $Z - zero or set if non-negative
    ZSNNI(u8, u8, u8), // ZSNNI $X, $Y, Z - zero or set if non-negative immediate
    ZSNZ(u8, u8, u8),  // ZSNZ $X, $Y, $Z - zero or set if non-zero
    ZSNZI(u8, u8, u8), // ZSNZI $X, $Y, Z - zero or set if non-zero immediate
    ZSNP(u8, u8, u8),  // ZSNP $X, $Y, $Z - zero or set if non-positive
    ZSNPI(u8, u8, u8), // ZSNPI $X, $Y, Z - zero or set if non-positive immediate
    ZSEV(u8, u8, u8),  // ZSEV $X, $Y, $Z - zero or set if even
    ZSEVI(u8, u8, u8), // ZSEVI $X, $Y, Z - zero or set if even immediate

    // System instructions
    TRAP(u8, u8, u8),    // TRAP X, Y, Z - trap/system call
    TRIP(u8, u8, u8),    // TRIP X, Y, Z - trip (forced trap)
    PUSHJ(u8, u8, u8),   // PUSHJ $X, YZ - push registers and jump
    PUSHJB(u8, u8, u8),  // PUSHJB $X, YZ - push registers and jump backward
    PUSHGO(u8, u8, u8),  // PUSHGO $X, $Y, $Z - push registers and go
    PUSHGOI(u8, u8, u8), // PUSHGOI $X, $Y, Z - push registers and go (immediate)
    POP(u8, u8, u8),     // POP X, Y, Z - pop registers and return (YZ combined is a 16-bit field)
    GO(u8, u8, u8),      // GO $X, $Y, $Z - go to location
    GOI(u8, u8, u8),     // GOI $X, $Y, Z - go to location (immediate)
    GET(u8, u8),         // GET $X, Z - get from special register
    PUT(u8, u8),         // PUT X, $Z - put into special register
    PUTI(u8, u8),        // PUTI X, Z - put immediate into special register
    SAVE(u8, u8),        // SAVE $X, 0 - save context
    UNSAVE(u8, u8),      // UNSAVE 0, $Z - unsave/restore context
    RESUME(u8),          // RESUME XYZ - resume after interrupt
    SYNC(u8),            // SYNC XYZ - synchronize
    SWYM(u8, u8, u8),    // SWYM X, Y, Z - sympathize with your machinery (nop)
    PRELD(u8, u8, u8),   // PRELD X, $Y, $Z - preload data
    PRELDI(u8, u8, u8),  // PRELDI X, $Y, Z - preload data (immediate)
    PREGO(u8, u8, u8),   // PREGO X, $Y, $Z - prefetch to go
    PREGOI(u8, u8, u8),  // PREGOI X, $Y, Z - prefetch to go (immediate)
    PREST(u8, u8, u8),   // PREST X, $Y, $Z - prestore data
    PRESTI(u8, u8, u8),  // PRESTI X, $Y, Z - prestore data (immediate)
    SYNCD(u8, u8, u8),   // SYNCD X, $Y, $Z - synchronize data
    SYNCDI(u8, u8, u8),  // SYNCDI X, $Y, Z - synchronize data (immediate)
    SYNCID(u8, u8, u8),  // SYNCID X, $Y, $Z - synchronize instructions and data
    SYNCIDI(u8, u8, u8), // SYNCIDI X, $Y, Z - synchronize instructions and data (immediate)
    GETA(u8, u8, u8),    // GETA $X, $Y, $Z or GETA $X, addr - get address
    GETAB(u8, u8, u8),   // GETAB $X, $Y, $Z or GETAB $X, addr - get address backward

    // Data directives
    BYTE(u8),   // BYTE - 1 byte of data
    WYDE(u16),  // WYDE - 2 bytes of data
    TETRA(u32), // TETRA - 4 bytes of data
    OCTA(u64),  // OCTA - 8 bytes of data

    // Control
    HALT, // HALT - stop execution
}

/// MMIX Operation Codes
/// This enum represents just the opcode byte (not the full instruction with operands)
#[repr(u8)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[allow(clippy::upper_case_acronyms)]
pub enum Opcode {
    // Floating Point instructions (0x00-0x17)
    TRAP = 0x00,
    FCMP = 0x01,
    FUN = 0x02,
    FEQL = 0x03,
    FADD = 0x04,
    FIX = 0x05,
    FSUB = 0x06,
    FIXU = 0x07,
    FLOT = 0x08,
    FLOTI = 0x09,
    FLOTU = 0x0A,
    FLOTUI = 0x0B,
    SFLOT = 0x0C,
    SFLOTI = 0x0D,
    SFLOTU = 0x0E,
    SFLOTUI = 0x0F,
    FMUL = 0x10,
    FCMPE = 0x11,
    FUNE = 0x12,
    FEQLE = 0x13,
    FDIV = 0x14,
    FSQRT = 0x15,
    FREM = 0x16,
    FINT = 0x17,

    // Multiplication and Division (0x18-0x1F)
    MUL = 0x18,
    MULI = 0x19,
    MULU = 0x1A,
    MULUI = 0x1B,
    DIV = 0x1C,
    DIVI = 0x1D,
    DIVU = 0x1E,
    DIVUI = 0x1F,

    // Addition and Subtraction (0x20-0x3F)
    ADD = 0x20,
    ADDI = 0x21,
    ADDU = 0x22,
    ADDUI = 0x23,
    SUB = 0x24,
    SUBI = 0x25,
    SUBU = 0x26,
    SUBUI = 0x27,
    ADDU2 = 0x28,
    ADDU2I = 0x29,
    ADDU4 = 0x2A,
    ADDU4I = 0x2B,
    ADDU8 = 0x2C,
    ADDU8I = 0x2D,
    ADDU16 = 0x2E,
    ADDU16I = 0x2F,
    CMP = 0x30,
    CMPI = 0x31,
    CMPU = 0x32,
    CMPUI = 0x33,
    NEG = 0x34,
    NEGI = 0x35,
    NEGU = 0x36,
    NEGUI = 0x37,
    SL = 0x38,
    SLI = 0x39,
    SLU = 0x3A,
    SLUI = 0x3B,
    SR = 0x3C,
    SRI = 0x3D,
    SRU = 0x3E,
    SRUI = 0x3F,

    // Branch instructions (0x40-0x5F)
    BN = 0x40,
    BNB = 0x41,
    BZ = 0x42,
    BZB = 0x43,
    BP = 0x44,
    BPB = 0x45,
    BOD = 0x46,
    BODB = 0x47,
    BNN = 0x48,
    BNNB = 0x49,
    BNZ = 0x4A,
    BNZB = 0x4B,
    BNP = 0x4C,
    BNPB = 0x4D,
    BEV = 0x4E,
    BEVB = 0x4F,
    PBN = 0x50,
    PBNB = 0x51,
    PBZ = 0x52,
    PBZB = 0x53,
    PBP = 0x54,
    PBPB = 0x55,
    PBOD = 0x56,
    PBODB = 0x57,
    PBNN = 0x58,
    PBNNB = 0x59,
    PBNZ = 0x5A,
    PBNZB = 0x5B,
    PBNP = 0x5C,
    PBNPB = 0x5D,
    PBEV = 0x5E,
    PBEVB = 0x5F,

    // Conditional set (0x60-0x6F)
    CSN = 0x60,
    CSNI = 0x61,
    CSZ = 0x62,
    CSZI = 0x63,
    CSP = 0x64,
    CSPI = 0x65,
    CSOD = 0x66,
    CSODI = 0x67,
    CSNN = 0x68,
    CSNNI = 0x69,
    CSNZ = 0x6A,
    CSNZI = 0x6B,
    CSNP = 0x6C,
    CSNPI = 0x6D,
    CSEV = 0x6E,
    CSEVI = 0x6F,

    // Zero or set (0x70-0x7F)
    ZSN = 0x70,
    ZSNI = 0x71,
    ZSZ = 0x72,
    ZSZI = 0x73,
    ZSP = 0x74,
    ZSPI = 0x75,
    ZSOD = 0x76,
    ZSODI = 0x77,
    ZSNN = 0x78,
    ZSNNI = 0x79,
    ZSNZ = 0x7A,
    ZSNZI = 0x7B,
    ZSNP = 0x7C,
    ZSNPI = 0x7D,
    ZSEV = 0x7E,
    ZSEVI = 0x7F,

    // Load instructions (0x80-0x9F)
    LDB = 0x80,
    LDBI = 0x81,
    LDBU = 0x82,
    LDBUI = 0x83,
    LDW = 0x84,
    LDWI = 0x85,
    LDWU = 0x86,
    LDWUI = 0x87,
    LDT = 0x88,
    LDTI = 0x89,
    LDTU = 0x8A,
    LDTUI = 0x8B,
    LDO = 0x8C,
    LDOI = 0x8D,
    LDOU = 0x8E,
    LDOUI = 0x8F,
    LDSF = 0x90,
    LDSFI = 0x91,
    LDHT = 0x92,
    LDHTI = 0x93,
    CSWAP = 0x94,
    CSWAPI = 0x95,
    LDUNC = 0x96,
    LDUNCI = 0x97,
    LDVTS = 0x98,
    LDVTSI = 0x99,
    PRELD = 0x9A,
    PRELDI = 0x9B,
    PREGO = 0x9C,
    PREGOI = 0x9D,
    GO = 0x9E,
    GOI = 0x9F,

    // Store instructions (0xA0-0xBF)
    STB = 0xA0,
    STBI = 0xA1,
    STBU = 0xA2,
    STBUI = 0xA3,
    STW = 0xA4,
    STWI = 0xA5,
    STWU = 0xA6,
    STWUI = 0xA7,
    STT = 0xA8,
    STTI = 0xA9,
    STTU = 0xAA,
    STTUI = 0xAB,
    STO = 0xAC,
    STOI = 0xAD,
    STOU = 0xAE,
    STOUI = 0xAF,
    STSF = 0xB0,
    STSFI = 0xB1,
    STHT = 0xB2,
    STHTI = 0xB3,
    STCO = 0xB4,
    STCOI = 0xB5,
    STUNC = 0xB6,
    STUNCI = 0xB7,
    SYNCD = 0xB8,
    SYNCDI = 0xB9,
    PREST = 0xBA,
    PRESTI = 0xBB,
    SYNCID = 0xBC,
    SYNCIDI = 0xBD,
    PUSHGO = 0xBE,
    PUSHGOI = 0xBF,

    // Bitwise operations (0xC0-0xCF)
    OR = 0xC0,
    ORI = 0xC1,
    ORN = 0xC2,
    ORNI = 0xC3,
    NOR = 0xC4,
    NORI = 0xC5,
    XOR = 0xC6,
    XORI = 0xC7,
    AND = 0xC8,
    ANDI = 0xC9,
    ANDN = 0xCA,
    ANDNI = 0xCB,
    NAND = 0xCC,
    NANDI = 0xCD,
    NXOR = 0xCE,
    NXORI = 0xCF,

    // Bit manipulation (0xD0-0xDF)
    BDIF = 0xD0,
    BDIFI = 0xD1,
    WDIF = 0xD2,
    WDIFI = 0xD3,
    TDIF = 0xD4,
    TDIFI = 0xD5,
    ODIF = 0xD6,
    ODIFI = 0xD7,
    MUX = 0xD8,
    MUXI = 0xD9,
    SADD = 0xDA,
    SADDI = 0xDB,
    MOR = 0xDC,
    MORI = 0xDD,
    MXOR = 0xDE,
    MXORI = 0xDF,

    // SET family (0xE0-0xEF)
    SETH = 0xE0,
    SETMH = 0xE1,
    SETML = 0xE2,
    SETL = 0xE3,
    INCH = 0xE4,
    INCMH = 0xE5,
    INCML = 0xE6,
    INCL = 0xE7,
    ORH = 0xE8,
    ORMH = 0xE9,
    ORML = 0xEA,
    ORL = 0xEB,
    ANDNH = 0xEC,
    ANDNMH = 0xED,
    ANDNML = 0xEE,
    ANDNL = 0xEF,

    // System operations (0xF0-0xFF)
    JMP = 0xF0,
    JMPB = 0xF1,
    PUSHJ = 0xF2,
    PUSHJB = 0xF3,
    GETA = 0xF4,
    GETAB = 0xF5,
    PUT = 0xF6,
    PUTI = 0xF7,
    POP = 0xF8,
    RESUME = 0xF9,
    SAVE = 0xFA,
    UNSAVE = 0xFB,
    SYNC = 0xFC,
    SWYM = 0xFD,
    GET = 0xFE,
    TRIP = 0xFF,
}

impl TryFrom<u8> for Opcode {
    type Error = String;

    #[allow(unreachable_patterns)]
    fn try_from(value: u8) -> Result<Self, Self::Error> {
        match value {
            0x00 => Ok(Opcode::TRAP),
            0x01 => Ok(Opcode::FCMP),
            0x02 => Ok(Opcode::FUN),
            0x03 => Ok(Opcode::FEQL),
            0x04 => Ok(Opcode::FADD),
            0x05 => Ok(Opcode::FIX),
            0x06 => Ok(Opcode::FSUB),
            0x07 => Ok(Opcode::FIXU),
            0x08 => Ok(Opcode::FLOT),
            0x09 => Ok(Opcode::FLOTI),
            0x0A => Ok(Opcode::FLOTU),
            0x0B => Ok(Opcode::FLOTUI),
            0x0C => Ok(Opcode::SFLOT),
            0x0D => Ok(Opcode::SFLOTI),
            0x0E => Ok(Opcode::SFLOTU),
            0x0F => Ok(Opcode::SFLOTUI),
            0x10 => Ok(Opcode::FMUL),
            0x11 => Ok(Opcode::FCMPE),
            0x12 => Ok(Opcode::FUNE),
            0x13 => Ok(Opcode::FEQLE),
            0x14 => Ok(Opcode::FDIV),
            0x15 => Ok(Opcode::FSQRT),
            0x16 => Ok(Opcode::FREM),
            0x17 => Ok(Opcode::FINT),
            0x18 => Ok(Opcode::MUL),
            0x19 => Ok(Opcode::MULI),
            0x1A => Ok(Opcode::MULU),
            0x1B => Ok(Opcode::MULUI),
            0x1C => Ok(Opcode::DIV),
            0x1D => Ok(Opcode::DIVI),
            0x1E => Ok(Opcode::DIVU),
            0x1F => Ok(Opcode::DIVUI),
            0x20 => Ok(Opcode::ADD),
            0x21 => Ok(Opcode::ADDI),
            0x22 => Ok(Opcode::ADDU),
            0x23 => Ok(Opcode::ADDUI),
            0x24 => Ok(Opcode::SUB),
            0x25 => Ok(Opcode::SUBI),
            0x26 => Ok(Opcode::SUBU),
            0x27 => Ok(Opcode::SUBUI),
            0x28 => Ok(Opcode::ADDU2),
            0x29 => Ok(Opcode::ADDU2I),
            0x2A => Ok(Opcode::ADDU4),
            0x2B => Ok(Opcode::ADDU4I),
            0x2C => Ok(Opcode::ADDU8),
            0x2D => Ok(Opcode::ADDU8I),
            0x2E => Ok(Opcode::ADDU16),
            0x2F => Ok(Opcode::ADDU16I),
            0x30 => Ok(Opcode::CMP),
            0x31 => Ok(Opcode::CMPI),
            0x32 => Ok(Opcode::CMPU),
            0x33 => Ok(Opcode::CMPUI),
            0x34 => Ok(Opcode::NEG),
            0x35 => Ok(Opcode::NEGI),
            0x36 => Ok(Opcode::NEGU),
            0x37 => Ok(Opcode::NEGUI),
            0x38 => Ok(Opcode::SL),
            0x39 => Ok(Opcode::SLI),
            0x3A => Ok(Opcode::SLU),
            0x3B => Ok(Opcode::SLUI),
            0x3C => Ok(Opcode::SR),
            0x3D => Ok(Opcode::SRI),
            0x3E => Ok(Opcode::SRU),
            0x3F => Ok(Opcode::SRUI),
            0x40 => Ok(Opcode::BN),
            0x41 => Ok(Opcode::BNB),
            0x42 => Ok(Opcode::BZ),
            0x43 => Ok(Opcode::BZB),
            0x44 => Ok(Opcode::BP),
            0x45 => Ok(Opcode::BPB),
            0x46 => Ok(Opcode::BOD),
            0x47 => Ok(Opcode::BODB),
            0x48 => Ok(Opcode::BNN),
            0x49 => Ok(Opcode::BNNB),
            0x4A => Ok(Opcode::BNZ),
            0x4B => Ok(Opcode::BNZB),
            0x4C => Ok(Opcode::BNP),
            0x4D => Ok(Opcode::BNPB),
            0x4E => Ok(Opcode::BEV),
            0x4F => Ok(Opcode::BEVB),
            0x50 => Ok(Opcode::PBN),
            0x51 => Ok(Opcode::PBNB),
            0x52 => Ok(Opcode::PBZ),
            0x53 => Ok(Opcode::PBZB),
            0x54 => Ok(Opcode::PBP),
            0x55 => Ok(Opcode::PBPB),
            0x56 => Ok(Opcode::PBOD),
            0x57 => Ok(Opcode::PBODB),
            0x58 => Ok(Opcode::PBNN),
            0x59 => Ok(Opcode::PBNNB),
            0x5A => Ok(Opcode::PBNZ),
            0x5B => Ok(Opcode::PBNZB),
            0x5C => Ok(Opcode::PBNP),
            0x5D => Ok(Opcode::PBNPB),
            0x5E => Ok(Opcode::PBEV),
            0x5F => Ok(Opcode::PBEVB),
            0x60 => Ok(Opcode::CSN),
            0x61 => Ok(Opcode::CSNI),
            0x62 => Ok(Opcode::CSZ),
            0x63 => Ok(Opcode::CSZI),
            0x64 => Ok(Opcode::CSP),
            0x65 => Ok(Opcode::CSPI),
            0x66 => Ok(Opcode::CSOD),
            0x67 => Ok(Opcode::CSODI),
            0x68 => Ok(Opcode::CSNN),
            0x69 => Ok(Opcode::CSNNI),
            0x6A => Ok(Opcode::CSNZ),
            0x6B => Ok(Opcode::CSNZI),
            0x6C => Ok(Opcode::CSNP),
            0x6D => Ok(Opcode::CSNPI),
            0x6E => Ok(Opcode::CSEV),
            0x6F => Ok(Opcode::CSEVI),
            0x70 => Ok(Opcode::ZSN),
            0x71 => Ok(Opcode::ZSNI),
            0x72 => Ok(Opcode::ZSZ),
            0x73 => Ok(Opcode::ZSZI),
            0x74 => Ok(Opcode::ZSP),
            0x75 => Ok(Opcode::ZSPI),
            0x76 => Ok(Opcode::ZSOD),
            0x77 => Ok(Opcode::ZSODI),
            0x78 => Ok(Opcode::ZSNN),
            0x79 => Ok(Opcode::ZSNNI),
            0x7A => Ok(Opcode::ZSNZ),
            0x7B => Ok(Opcode::ZSNZI),
            0x7C => Ok(Opcode::ZSNP),
            0x7D => Ok(Opcode::ZSNPI),
            0x7E => Ok(Opcode::ZSEV),
            0x7F => Ok(Opcode::ZSEVI),
            0x80 => Ok(Opcode::LDB),
            0x81 => Ok(Opcode::LDBI),
            0x82 => Ok(Opcode::LDBU),
            0x83 => Ok(Opcode::LDBUI),
            0x84 => Ok(Opcode::LDW),
            0x85 => Ok(Opcode::LDWI),
            0x86 => Ok(Opcode::LDWU),
            0x87 => Ok(Opcode::LDWUI),
            0x88 => Ok(Opcode::LDT),
            0x89 => Ok(Opcode::LDTI),
            0x8A => Ok(Opcode::LDTU),
            0x8B => Ok(Opcode::LDTUI),
            0x8C => Ok(Opcode::LDO),
            0x8D => Ok(Opcode::LDOI),
            0x8E => Ok(Opcode::LDOU),
            0x8F => Ok(Opcode::LDOUI),
            0x90 => Ok(Opcode::LDSF),
            0x91 => Ok(Opcode::LDSFI),
            0x92 => Ok(Opcode::LDHT),
            0x93 => Ok(Opcode::LDHTI),
            0x94 => Ok(Opcode::CSWAP),
            0x95 => Ok(Opcode::CSWAPI),
            0x96 => Ok(Opcode::LDUNC),
            0x97 => Ok(Opcode::LDUNCI),
            0x98 => Ok(Opcode::LDVTS),
            0x99 => Ok(Opcode::LDVTSI),
            0x9A => Ok(Opcode::PRELD),
            0x9B => Ok(Opcode::PRELDI),
            0x9C => Ok(Opcode::PREGO),
            0x9D => Ok(Opcode::PREGOI),
            0x9E => Ok(Opcode::GO),
            0x9F => Ok(Opcode::GOI),
            0xA0 => Ok(Opcode::STB),
            0xA1 => Ok(Opcode::STBI),
            0xA2 => Ok(Opcode::STBU),
            0xA3 => Ok(Opcode::STBUI),
            0xA4 => Ok(Opcode::STW),
            0xA5 => Ok(Opcode::STWI),
            0xA6 => Ok(Opcode::STWU),
            0xA7 => Ok(Opcode::STWUI),
            0xA8 => Ok(Opcode::STT),
            0xA9 => Ok(Opcode::STTI),
            0xAA => Ok(Opcode::STTU),
            0xAB => Ok(Opcode::STTUI),
            0xAC => Ok(Opcode::STO),
            0xAD => Ok(Opcode::STOI),
            0xAE => Ok(Opcode::STOU),
            0xAF => Ok(Opcode::STOUI),
            0xB0 => Ok(Opcode::STSF),
            0xB1 => Ok(Opcode::STSFI),
            0xB2 => Ok(Opcode::STHT),
            0xB3 => Ok(Opcode::STHTI),
            0xB4 => Ok(Opcode::STCO),
            0xB5 => Ok(Opcode::STCOI),
            0xB6 => Ok(Opcode::STUNC),
            0xB7 => Ok(Opcode::STUNCI),
            0xB8 => Ok(Opcode::SYNCD),
            0xB9 => Ok(Opcode::SYNCDI),
            0xBA => Ok(Opcode::PREST),
            0xBB => Ok(Opcode::PRESTI),
            0xBC => Ok(Opcode::SYNCID),
            0xBD => Ok(Opcode::SYNCIDI),
            0xBE => Ok(Opcode::PUSHGO),
            0xBF => Ok(Opcode::PUSHGOI),
            0xC0 => Ok(Opcode::OR),
            0xC1 => Ok(Opcode::ORI),
            0xC2 => Ok(Opcode::ORN),
            0xC3 => Ok(Opcode::ORNI),
            0xC4 => Ok(Opcode::NOR),
            0xC5 => Ok(Opcode::NORI),
            0xC6 => Ok(Opcode::XOR),
            0xC7 => Ok(Opcode::XORI),
            0xC8 => Ok(Opcode::AND),
            0xC9 => Ok(Opcode::ANDI),
            0xCA => Ok(Opcode::ANDN),
            0xCB => Ok(Opcode::ANDNI),
            0xCC => Ok(Opcode::NAND),
            0xCD => Ok(Opcode::NANDI),
            0xCE => Ok(Opcode::NXOR),
            0xCF => Ok(Opcode::NXORI),
            0xD0 => Ok(Opcode::BDIF),
            0xD1 => Ok(Opcode::BDIFI),
            0xD2 => Ok(Opcode::WDIF),
            0xD3 => Ok(Opcode::WDIFI),
            0xD4 => Ok(Opcode::TDIF),
            0xD5 => Ok(Opcode::TDIFI),
            0xD6 => Ok(Opcode::ODIF),
            0xD7 => Ok(Opcode::ODIFI),
            0xD8 => Ok(Opcode::MUX),
            0xD9 => Ok(Opcode::MUXI),
            0xDA => Ok(Opcode::SADD),
            0xDB => Ok(Opcode::SADDI),
            0xDC => Ok(Opcode::MOR),
            0xDD => Ok(Opcode::MORI),
            0xDE => Ok(Opcode::MXOR),
            0xDF => Ok(Opcode::MXORI),
            0xE0 => Ok(Opcode::SETH),
            0xE1 => Ok(Opcode::SETMH),
            0xE2 => Ok(Opcode::SETML),
            0xE3 => Ok(Opcode::SETL),
            0xE4 => Ok(Opcode::INCH),
            0xE5 => Ok(Opcode::INCMH),
            0xE6 => Ok(Opcode::INCML),
            0xE7 => Ok(Opcode::INCL),
            0xE8 => Ok(Opcode::ORH),
            0xE9 => Ok(Opcode::ORMH),
            0xEA => Ok(Opcode::ORML),
            0xEB => Ok(Opcode::ORL),
            0xEC => Ok(Opcode::ANDNH),
            0xED => Ok(Opcode::ANDNMH),
            0xEE => Ok(Opcode::ANDNML),
            0xEF => Ok(Opcode::ANDNL),
            0xF0 => Ok(Opcode::JMP),
            0xF1 => Ok(Opcode::JMPB),
            0xF2 => Ok(Opcode::PUSHJ),
            0xF3 => Ok(Opcode::PUSHJB),
            0xF4 => Ok(Opcode::GETA),
            0xF5 => Ok(Opcode::GETAB),
            0xF6 => Ok(Opcode::PUT),
            0xF7 => Ok(Opcode::PUTI),
            0xF8 => Ok(Opcode::POP),
            0xF9 => Ok(Opcode::RESUME),
            0xFA => Ok(Opcode::SAVE),
            0xFB => Ok(Opcode::UNSAVE),
            0xFC => Ok(Opcode::SYNC),
            0xFD => Ok(Opcode::SWYM),
            0xFE => Ok(Opcode::GET),
            0xFF => Ok(Opcode::TRIP),
            _ => Err(format!("Invalid opcode: {:#04x}", value)),
        }
    }
}

/// Resolved Z operand for an auto-immediate base mnemonic. The parser uses
/// this to choose between the RRR and RRI variants of an instruction.
#[derive(Debug, Clone, Copy)]
enum ZForm {
    Reg(u8),
    Imm(u8),
}

/// A PC-relative displacement in the instruction encoding: the forward opcode
/// carries `field` directly, the backward opcode carries `2^bits - magnitude`.
#[derive(Debug, Clone, Copy)]
struct RelativeField {
    backward: bool,
    field: u32,
}

/// One input translation unit: its filename, the PREPROCESSED source the
/// parser walks, and enough of the ORIGINAL (un-preprocessed) source to
/// support source-level debug info (`SourceLoc`, `source_text`).
#[derive(Clone)]
struct SourceUnit {
    filename: String,
    preprocessed: String,
    /// Original, un-preprocessed source text as the user wrote it.
    original: String,
    /// Preprocessed line N (1-based; `line_map[N - 1]`) is the original
    /// line it came from. A `debug` directive expands to two preprocessed
    /// lines that both map to its own original line; every other line
    /// maps to itself. A preprocessed line past the end of this map is
    /// compiler-generated code (the appended `debug` subroutine block)
    /// with no original line at all.
    line_map: Vec<usize>,
}

pub struct MMixAssembler {
    /// Input translation units in command-line order.
    sources: Vec<SourceUnit>,
    /// Filename of the source currently being walked (set during each pass).
    current_filename: String,
    /// Active PREFIX value applied to unqualified identifiers.
    /// Names starting with ':' bypass the prefix.
    current_prefix: String,
    pub labels: HashMap<String, u64>,
    pub symbols: HashMap<String, SymbolType>, // For IS directive - symbolic names with type
    /// First-definition site for user-defined labels: stored name -> (filename, line).
    /// Predefined symbols are not tracked here, so user code may shadow them.
    label_origins: HashMap<String, (String, usize)>,
    /// First-definition site for user-defined IS/GREG symbols.
    symbol_origins: HashMap<String, (String, usize)>,
    pub instructions: Vec<(u64, MMixInstruction)>,
    current_addr: u64,
    next_greg: u8, // Next global register to allocate (starts at 254, counts down)
    pub greg_inits: Vec<(u8, u64)>, // Global register initialization values: (register, value)
    /// Index into `sources` of the translation unit currently being walked
    /// (command-line order), set at the start of each unit in both passes.
    /// Used, rather than `current_filename` alone, to resolve `line_map`
    /// unambiguously even when two inputs share a filename.
    current_unit_index: usize,
    /// Address -> original source location, populated during pass 2.
    /// Only addresses whose statement came from a real user line (not the
    /// appended debug-subroutine block) get an entry.
    debug_info: BTreeMap<u64, SourceLoc>,
}

/// The original (user-facing) source location of an assembled instruction:
/// the file as given on the command line, and the 1-based line in that
/// file's ORIGINAL (un-preprocessed) text.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SourceLoc {
    pub file: String,
    pub line: usize,
}

impl MMixAssembler {
    /// Preprocess the source to expand `debug "text"` directives, returning
    /// the preprocessed text and its line map (`SourceUnit::line_map`).
    ///
    /// `debug "text"` becomes a `JMP` to a generated subroutine and, right
    /// after it on its own line, a `SWYM` no-op labelled with a fresh
    /// `DbgRet_NNNN` -- the landing pad the subroutine jumps back to.
    /// Neither instruction inspects or depends on anything past the
    /// directive's own line, so whatever follows -- end of file, a blank or
    /// comment line, another label, a `GREG` or `IS` line -- assembles
    /// exactly as if `debug` were not there. `DbgRet_NNNN` shares the
    /// generated-label prefix family with the stub label `DbgStr_NNNN`.
    ///
    /// The subroutine `SAVE`s the full machine state before printing and
    /// `UNSAVE`s it after, so every general register and every special
    /// register but `rJ` -- `rL` and `rG` included, whatever their values
    /// -- comes back exactly as it was; `rJ` is simply never written, by
    /// either instruction the directive expands to.
    fn preprocess_debug(source: &str) -> (String, Vec<usize>) {
        // A directive, optionally preceded by its own label. A fixed,
        // valid pattern compiled once per call: infallible.
        let debug_re = Regex::new(r#"(?m)^([^\s]*\s+)?debug\s+"([^"]*)"\s*$"#).unwrap();

        let mut result = String::new();
        let mut line_map = Vec::new();
        let mut stubs = Vec::new();
        let mut counter = 0usize;

        for (index, line) in source.lines().enumerate() {
            let original_line = index + 1;
            match debug_re.captures(line) {
                Some(caps) => {
                    counter += 1;
                    let label = caps.get(1).map(|m| m.as_str().trim()).unwrap_or("");
                    let stub_label = format!("DbgStr_{counter:04}");
                    let ret_label = format!("DbgRet_{counter:04}");
                    Self::emit_debug_call(&mut result, label, &stub_label, &ret_label);
                    line_map.push(original_line);
                    line_map.push(original_line);
                    stubs.push((stub_label, caps[2].to_string(), ret_label));
                }
                None => {
                    result.push_str(line);
                    result.push('\n');
                    line_map.push(original_line);
                }
            }
        }

        if !stubs.is_empty() {
            result.push('\n');
            result.push_str("; debug subroutines generated by the preprocessor\n");
            // A program that falls off its own last real statement with no
            // explicit HALT -- `debug` as that statement included -- must
            // not fall into a stub instead: SAVE/GETA/TRAP/UNSAVE misreads
            // whatever state is live there, and the final JMP back to its
            // own landing pad loops forever. Guard the block with a halt
            // no well-formed program ever reaches.
            result.push_str("\tTRAP\t0,Halt,0\n");
            for (stub_label, text, ret_label) in &stubs {
                Self::emit_debug_stub(&mut result, stub_label, text, ret_label);
            }
        }

        debug!("Preprocessed source:\n{}", result);
        (result, line_map)
    }

    /// The two lines that replace one `debug` directive: its own label, if
    /// any, on a jump to `stub_label`, then the no-op labelled `ret_label`
    /// that the stub jumps back to.
    fn emit_debug_call(out: &mut String, label: &str, stub_label: &str, ret_label: &str) {
        out.push_str(label);
        out.push_str(&format!("\tJMP\t{stub_label}\n"));
        out.push_str(&format!("{ret_label}\tSWYM\n"));
    }

    /// The generated subroutine for one `debug` directive: print `text`,
    /// restore the state `SAVE` captured, and jump back to `ret_label`.
    fn emit_debug_stub(out: &mut String, stub_label: &str, text: &str, ret_label: &str) {
        out.push_str(&format!("{stub_label}\tSAVE\t$254,0\n"));
        out.push_str(&format!("\tGETA\t$255,{stub_label}Str\n"));
        out.push_str("\tTRAP\t0,Fputs,StdOut\n");
        out.push_str("\tUNSAVE\t0,$254\n");
        out.push_str(&format!("\tJMP\t{ret_label}\n"));
        out.push_str(&format!("{stub_label}Str\tBYTE\t\"{text}\",#a,0\n"));
    }

    /// Count the actual number of bytes in a string literal, accounting for escape sequences
    fn count_string_bytes(content: &str) -> usize {
        Self::decode_byte_string(content).len()
    }

    /// Decode a data directive's string literal content into the bytes it
    /// represents, resolving the escape sequences `\n`, `\r`, `\t`, `\0`,
    /// `\\`, `\'`, `\"`. Any other escaped character decodes to that
    /// character's own byte value. Pass-1 (`count_string_bytes`) and pass-2
    /// (`parse_data_directive`) both go through this single function so they
    /// cannot disagree on size.
    fn decode_byte_string(content: &str) -> Vec<u8> {
        let mut bytes = Vec::new();
        let mut chars = content.chars().peekable();

        while let Some(ch) = chars.next() {
            if ch == '\\' {
                if let Some(next_ch) = chars.next() {
                    let decoded = match next_ch {
                        'n' => b'\n',
                        'r' => b'\r',
                        't' => b'\t',
                        '0' => 0u8,
                        '\\' => b'\\',
                        '\'' => b'\'',
                        '"' => b'"',
                        other => other as u8,
                    };
                    bytes.push(decoded);
                } else {
                    // Backslash at end of string
                    bytes.push(b'\\');
                }
            } else {
                bytes.push(ch as u8);
            }
        }

        bytes
    }

    /// Insert a predefined symbol under both `name` and `:name` so it remains
    /// reachable from inside any PREFIX region. Predefined entries are not
    /// tracked in `symbol_origins`, so user code may shadow them without
    /// triggering a redefinition error.
    fn seed_predefined(symbols: &mut HashMap<String, SymbolType>, name: &str, ty: SymbolType) {
        symbols.insert(name.to_string(), ty);
        symbols.insert(format!(":{}", name), ty);
    }

    pub fn new(source: &str, filename: &str) -> Self {
        let mut symbols = HashMap::new();

        // Standard MMIXAL predefined symbols
        // Segment constants
        Self::seed_predefined(
            &mut symbols,
            "Data_Segment",
            SymbolType::Constant(DATA_SEGMENT_START),
        );
        Self::seed_predefined(
            &mut symbols,
            "Pool_Segment",
            SymbolType::Constant(POOL_SEGMENT_START),
        );
        Self::seed_predefined(
            &mut symbols,
            "Stack_Segment",
            SymbolType::Constant(STACK_SEGMENT_START),
        );

        // OS-specific raw stdio identifiers (fds on Unix, handles on Windows)
        let (stdin_file_no, stdout_file_no, stderr_file_no) = stdio_raw_identifiers();

        // Standard I/O handles
        Self::seed_predefined(&mut symbols, "StdIn", SymbolType::Constant(stdin_file_no));
        Self::seed_predefined(&mut symbols, "StdOut", SymbolType::Constant(stdout_file_no));
        Self::seed_predefined(&mut symbols, "StdErr", SymbolType::Constant(stderr_file_no));
        // Common TRAP function codes (C library emulation)
        for (name, code) in [
            ("Halt", TrapCode::Halt),
            ("Trip", TrapCode::Trip),
            ("Fopen", TrapCode::Fopen),
            ("Fclose", TrapCode::Fclose),
            ("Fread", TrapCode::Fread),
            ("Fgets", TrapCode::Fgets),
            ("Fgetws", TrapCode::Fgetws),
            ("Fwrite", TrapCode::Fwrite),
            ("Fputs", TrapCode::Fputs),
            ("Fputc", TrapCode::Fputc),
            ("Fputws", TrapCode::Fputws),
            ("Fseek", TrapCode::Fseek),
            ("Ftell", TrapCode::Ftell),
            ("Time", TrapCode::Time),
        ] {
            Self::seed_predefined(&mut symbols, name, SymbolType::Constant(code as u64));
        }

        // Special register names (for use with GET and PUT instructions)
        for (name, num) in [
            ("rB", 0u64),
            ("rD", 1),
            ("rE", 2),
            ("rH", 3),
            ("rJ", 4),
            ("rM", 5),
            ("rR", 6),
            ("rBB", 7),
            ("rC", 8),
            ("rN", 9),
            ("rO", 10),
            ("rS", 11),
            ("rI", 12),
            ("rT", 13),
            ("rTT", 14),
            ("rK", 15),
            ("rQ", 16),
            ("rU", 17),
            ("rV", 18),
            ("rG", 19),
            ("rL", 20),
            ("rA", 21),
            ("rF", 22),
            ("rP", 23),
            ("rW", 24),
            ("rX", 25),
            ("rY", 26),
            ("rZ", 27),
            ("rWW", 28),
            ("rXX", 29),
            ("rYY", 30),
            ("rZZ", 31),
        ] {
            Self::seed_predefined(&mut symbols, name, SymbolType::Constant(num));
        }

        // Y rounding-mode override values for FIX, FIXU, FSQRT, FINT, and the
        // FLOT/SFLOT families (MMIXAL reference). Numbered independently of
        // rA's own persistent-mode field (`RA_ROUND_SHIFT`): rA's ROUND_NEAR
        // is 0, but Y's is 4, since Y=0 is reserved to mean "no override".
        for (name, mode) in [
            ("ROUND_CURRENT", 0u64),
            ("ROUND_OFF", 1),
            ("ROUND_UP", 2),
            ("ROUND_DOWN", 3),
            ("ROUND_NEAR", 4),
        ] {
            Self::seed_predefined(&mut symbols, name, SymbolType::Constant(mode));
        }

        // Preprocess the source to expand debug directives
        let (preprocessed_source, line_map) = Self::preprocess_debug(source);

        Self {
            sources: vec![SourceUnit {
                filename: filename.to_string(),
                preprocessed: preprocessed_source,
                original: source.to_string(),
                line_map,
            }],
            current_filename: filename.to_string(),
            current_prefix: String::new(),
            labels: HashMap::new(),
            symbols,
            label_origins: HashMap::new(),
            symbol_origins: HashMap::new(),
            instructions: Vec::new(),
            current_addr: 0,
            next_greg: 254, // Start allocating from $254, count down
            greg_inits: Vec::new(),
            current_unit_index: 0,
            debug_info: BTreeMap::new(),
        }
    }

    /// Append another translation unit. Files are processed in the order they
    /// are added; symbols, labels, GREG state, and `current_addr` carry over,
    /// so the result is identical to assembling the concatenation of inputs.
    pub fn add_source(&mut self, source: &str, filename: &str) {
        let (preprocessed, line_map) = Self::preprocess_debug(source);
        self.sources.push(SourceUnit {
            filename: filename.to_string(),
            preprocessed,
            original: source.to_string(),
            line_map,
        });
    }

    /// Apply the active PREFIX to a raw identifier. Names starting with ':'
    /// (the global namespace marker) are returned verbatim.
    fn qualify_name(&self, raw: &str) -> String {
        if raw.starts_with(':') {
            raw.to_string()
        } else {
            format!("{}{}", self.current_prefix, raw)
        }
    }

    /// Define a label (instruction/data/standalone) at the current address.
    /// Returns an error if the qualified name was already defined by user code.
    fn define_label(&mut self, raw: &str, addr: u64, line: usize) -> Result<(), String> {
        let name = self.qualify_name(raw);
        if let Some((prev_file, prev_line)) = self.label_origins.get(&name) {
            return Err(format!(
                "{}:{}: symbol '{}' redefined (first defined at {}:{})",
                self.current_filename, line, name, prev_file, prev_line
            ));
        }
        if let Some((prev_file, prev_line)) = self.symbol_origins.get(&name) {
            return Err(format!(
                "{}:{}: symbol '{}' redefined (first defined at {}:{})",
                self.current_filename, line, name, prev_file, prev_line
            ));
        }
        self.label_origins
            .insert(name.clone(), (self.current_filename.clone(), line));
        self.labels.insert(name, addr);
        Ok(())
    }

    /// Define an IS- or GREG-bound symbol. Returns an error if the qualified
    /// name was already defined by user code (predefined symbols are not
    /// tracked, so user code may shadow them as before).
    fn define_symbol(&mut self, raw: &str, ty: SymbolType, line: usize) -> Result<(), String> {
        let name = self.qualify_name(raw);
        if let Some((prev_file, prev_line)) = self.symbol_origins.get(&name) {
            return Err(format!(
                "{}:{}: symbol '{}' redefined (first defined at {}:{})",
                self.current_filename, line, name, prev_file, prev_line
            ));
        }
        if let Some((prev_file, prev_line)) = self.label_origins.get(&name) {
            return Err(format!(
                "{}:{}: symbol '{}' redefined (first defined at {}:{})",
                self.current_filename, line, name, prev_file, prev_line
            ));
        }
        self.symbol_origins
            .insert(name.clone(), (self.current_filename.clone(), line));
        self.symbols.insert(name, ty);
        Ok(())
    }

    /// Format Pest parse errors in a user-friendly way. `line_map` translates
    /// the preprocessed line Pest reports back to the line the user wrote;
    /// a line past the map's end (compiler-generated code) reports as-is.
    fn format_parse_error(
        error: &pest::error::Error<Rule>,
        filename: &str,
        line_map: &[usize],
    ) -> String {
        use pest::error::LineColLocation;

        let (line, col) = match error.line_col {
            LineColLocation::Pos((l, c)) => (l, c),
            LineColLocation::Span((l, c), _) => (l, c),
        };
        let line = line_map.get(line - 1).copied().unwrap_or(line);

        // Create a user-friendly error message based on what was expected
        let expected_msg = match &error.variant {
            pest::error::ErrorVariant::ParsingError { positives, .. } => {
                if positives.is_empty() {
                    "valid MMIX instruction or directive".to_string()
                } else {
                    // Try to make the expected rules more user-friendly
                    let friendly: Vec<String> = positives
                        .iter()
                        .map(|r| match r {
                            Rule::instruction => "instruction".to_string(),
                            Rule::directive => "directive".to_string(),
                            Rule::directive_is => "IS directive (symbol definition)".to_string(),
                            Rule::directive_loc => "LOC directive".to_string(),
                            Rule::register => "register (e.g., $0, $1, $255)".to_string(),
                            Rule::expr_value => "number or expression".to_string(),
                            Rule::identifier => "label or symbol name".to_string(),
                            _ => format!("{:?}", r),
                        })
                        .collect();

                    if friendly.len() == 1 {
                        friendly[0].clone()
                    } else {
                        format!("one of: {}", friendly.join(", "))
                    }
                }
            }
            pest::error::ErrorVariant::CustomError { message } => message.clone(),
        };

        format!(
            "{}:{}:{}: syntax error: expected {}",
            filename, line, col, expected_msg
        )
    }

    #[instrument(skip(self))]
    pub fn parse(&mut self) -> Result<(), String> {
        debug!("Starting MMIXAL parsing (two-pass)");
        match self.parse_two_pass() {
            Ok(_) => {
                debug!(
                    instruction_count = self.instructions.len(),
                    label_count = self.labels.len(),
                    symbol_count = self.symbols.len(),
                    "Parsing completed successfully"
                );
                Ok(())
            }
            Err(e) => Err(e),
        }
    }

    /// Two-pass assembler:
    /// Pass 1: Collect all labels and their addresses, process IS directives
    /// Pass 2: Generate instructions with resolved label references
    ///
    /// Each pass walks every translation unit in command-line order, threading
    /// `current_addr`, `current_prefix`, and the symbol tables across files so
    /// the result matches assembling the concatenation of the inputs. The
    /// PREFIX state is reset at the start of each pass.
    #[instrument(skip(self))]
    fn parse_two_pass(&mut self) -> Result<(), String> {
        use pest::Parser;

        let sources = self.sources.clone();
        debug!("Pass 1: Collecting labels and symbols");
        self.current_prefix.clear();

        for (index, unit) in sources.iter().enumerate() {
            self.current_filename = unit.filename.clone();
            self.current_unit_index = index;
            let pairs = MMixalParser::parse(Rule::program, &unit.preprocessed)
                .map_err(|e| Self::format_parse_error(&e, &unit.filename, &unit.line_map))?;
            for pair in pairs {
                if pair.as_rule() == Rule::program {
                    for line_pair in pair.into_inner() {
                        if line_pair.as_rule() == Rule::line {
                            for stmt_pair in line_pair.into_inner() {
                                if stmt_pair.as_rule() == Rule::statement {
                                    self.first_pass_statement(stmt_pair)?;
                                }
                            }
                        }
                    }
                }
            }
        }

        debug!(
            "Pass 1 complete: {} labels, {} symbols",
            self.labels.len(),
            self.symbols.len()
        );

        let saved_addr = self.current_addr;
        self.current_addr = 0;
        self.current_prefix.clear();

        debug!("Pass 2: Generating instructions");

        for (index, unit) in sources.iter().enumerate() {
            self.current_filename = unit.filename.clone();
            self.current_unit_index = index;
            let pairs = MMixalParser::parse(Rule::program, &unit.preprocessed)
                .map_err(|e| Self::format_parse_error(&e, &unit.filename, &unit.line_map))?;
            for pair in pairs {
                if pair.as_rule() == Rule::program {
                    for line_pair in pair.into_inner() {
                        if line_pair.as_rule() == Rule::line {
                            for stmt_pair in line_pair.into_inner() {
                                if stmt_pair.as_rule() == Rule::statement {
                                    self.second_pass_statement(stmt_pair)?;
                                }
                            }
                        }
                    }
                }
            }
        }

        self.current_addr = saved_addr;
        Ok(())
    }

    /// First pass: collect labels and process IS/PREFIX directives.
    /// Redefinition errors are reported here; the second pass overwrites
    /// silently because every label collected here will be re-encountered
    /// at the same address.
    #[instrument(skip(self, pair), fields(current_addr = format!("0x{:X}", self.current_addr)))]
    fn first_pass_statement(&mut self, pair: pest::iterators::Pair<Rule>) -> Result<(), String> {
        let mut pending_label: Option<(String, usize)> = None;

        for inner_pair in pair.into_inner() {
            match inner_pair.as_rule() {
                Rule::label_def => {
                    let (line, _) = inner_pair.line_col();
                    let line = self.original_line(line).unwrap_or(line);
                    let ident = inner_pair.into_inner().next().unwrap();
                    pending_label = Some((ident.as_str().to_string(), line));
                }
                Rule::instruction => {
                    self.align_current_addr(Self::INSTRUCTION_ALIGNMENT);
                    let inst = self.peek_instruction_type(inner_pair)?;
                    let size = Self::instruction_size(&inst);
                    if let Some((raw, line)) = pending_label.take() {
                        self.define_label(&raw, self.current_addr, line)?;
                    }
                    self.current_addr += size;
                }
                Rule::directive => {
                    let directive_pair = inner_pair.into_inner().next().unwrap();
                    match directive_pair.as_rule() {
                        Rule::data_directive => {
                            let alignment = Self::data_directive_alignment(&directive_pair)?;
                            self.align_current_addr(alignment);
                            let size = self.data_directive_size(directive_pair.clone())?;
                            if let Some((raw, line)) = pending_label.take() {
                                self.define_label(&raw, self.current_addr, line)?;
                            }
                            self.current_addr += size;
                        }
                        Rule::loc_directive => {
                            self.parse_loc_directive(directive_pair)?;
                            if let Some((raw, line)) = pending_label.take() {
                                self.define_label(&raw, self.current_addr, line)?;
                            }
                        }
                        Rule::greg_directive => {
                            // GREG allocates a global register; an attached
                            // label aliases the register, not an address.
                            let allocated_reg = if self.next_greg == 0 {
                                return Err(
                                    "Too many GREG directives - ran out of global registers"
                                        .to_string(),
                                );
                            } else {
                                let reg = self.next_greg;
                                self.next_greg -= 1;
                                reg
                            };

                            if let Some((raw, line)) = pending_label.take() {
                                self.define_symbol(
                                    &raw,
                                    SymbolType::Register(allocated_reg),
                                    line,
                                )?;
                            }

                            let mut greg_parts = directive_pair.clone().into_inner();
                            let _directive = greg_parts.next();
                            let value = self.parse_number(greg_parts.next().unwrap())?;
                            self.greg_inits.push((allocated_reg, value));
                        }
                        Rule::is_directive => {
                            self.parse_is_directive(directive_pair, true)?;
                            // IS directive doesn't advance current_addr.
                        }
                        Rule::prefix_directive => {
                            self.parse_prefix_directive(directive_pair);
                        }
                        _ => {}
                    }
                }
                _ => {}
            }
        }

        // Standalone labels (no instruction or directive on the line)
        if let Some((raw, line)) = pending_label {
            self.define_label(&raw, self.current_addr, line)?;
        }

        Ok(())
    }

    /// Second pass: generate actual instructions with resolved labels.
    /// Labels and IS-bound symbols are re-inserted (overwriting the pass-1
    /// values with the same value) without redefinition checking, since
    /// PREFIX state is replayed identically and produces the same names.
    #[instrument(skip(self, pair), fields(current_addr = format!("0x{:X}", self.current_addr)))]
    fn second_pass_statement(&mut self, pair: pest::iterators::Pair<Rule>) -> Result<(), String> {
        // Captured before `into_inner()` consumes `pair`: the statement's
        // line in the ACTIVE translation unit's PREPROCESSED text.
        // `record_debug_info` maps it back to the original source line.
        let (line, _) = pair.line_col();
        let mut label_name: Option<String> = None;
        let mut inst: Option<MMixInstruction> = None;

        for inner_pair in pair.into_inner() {
            match inner_pair.as_rule() {
                Rule::label_def => {
                    let ident = inner_pair.into_inner().next().unwrap();
                    label_name = Some(ident.as_str().to_string());
                }
                Rule::instruction => {
                    self.align_current_addr(Self::INSTRUCTION_ALIGNMENT);
                    if let Some(raw) = label_name.take() {
                        let qualified = self.qualify_name(&raw);
                        self.labels.insert(qualified, self.current_addr);
                    }
                    inst = Some(self.parse_instruction(inner_pair)?);
                }
                Rule::directive => {
                    let directive_pair = inner_pair.into_inner().next().unwrap();
                    match directive_pair.as_rule() {
                        Rule::data_directive => {
                            let alignment = Self::data_directive_alignment(&directive_pair)?;
                            self.align_current_addr(alignment);
                            if let Some(raw) = label_name.take() {
                                let qualified = self.qualify_name(&raw);
                                self.labels.insert(qualified, self.current_addr);
                            }
                            let instructions = self.parse_data_directive(directive_pair)?;
                            for instruction in instructions {
                                let size = Self::instruction_size(&instruction);
                                self.record_debug_info(self.current_addr, line);
                                self.instructions.push((self.current_addr, instruction));
                                self.current_addr += size;
                            }
                        }
                        Rule::loc_directive => {
                            self.parse_loc_directive(directive_pair)?;
                        }
                        Rule::greg_directive => {
                            // GREG was already processed in first pass.
                            if let Some(raw) = label_name.take() {
                                let qualified = self.qualify_name(&raw);
                                if !self.symbols.contains_key(&qualified) {
                                    return Err(format!(
                                        "Internal error: GREG label '{}' not found in symbols from first pass",
                                        qualified
                                    ));
                                }
                            }
                        }
                        Rule::is_directive => {
                            self.parse_is_directive(directive_pair, false)?;
                        }
                        Rule::prefix_directive => {
                            self.parse_prefix_directive(directive_pair);
                        }
                        _ => {}
                    }
                }
                _ => {}
            }
        }

        if let Some(instruction) = inst {
            let size = Self::instruction_size(&instruction);
            debug!(inst = ?instruction, addr = format!("0x{:X}", self.current_addr), size, "Added instruction");
            self.record_debug_info(self.current_addr, line);
            self.instructions.push((self.current_addr, instruction));
            self.current_addr += size;
        }

        // Standalone labels (no instruction or directive on the line)
        if let Some(raw) = label_name {
            let qualified = self.qualify_name(&raw);
            self.labels.insert(qualified, self.current_addr);
        }

        Ok(())
    }

    /// Translate `preprocessed`, a line in the active translation unit's
    /// (`current_unit_index`) preprocessed text, back to its original line
    /// through that unit's `line_map`. `None` for a line past the map's
    /// end: compiler-generated code (the appended debug-subroutine block),
    /// which has no original line.
    fn original_line(&self, preprocessed: usize) -> Option<usize> {
        self.sources[self.current_unit_index]
            .line_map
            .get(preprocessed - 1)
            .copied()
    }

    /// Record `addr`'s source location in the active translation unit, or
    /// skip it if `line` maps to no original line at all (generated code).
    fn record_debug_info(&mut self, addr: u64, line: usize) {
        let Some(original_line) = self.original_line(line) else {
            return;
        };
        let file = self.sources[self.current_unit_index].filename.clone();
        self.debug_info.insert(
            addr,
            SourceLoc {
                file,
                line: original_line,
            },
        );
    }

    /// Peek at instruction type to determine size without modifying state
    fn peek_instruction_type(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let inner = pair.into_inner().next().ok_or("Empty instruction")?;

        match inner.as_rule() {
            // SET is one tetra whichever variant it selects.
            Rule::inst_set => Ok(MMixInstruction::SETRR(0, 0)),
            Rule::inst_seti => Ok(MMixInstruction::SET(0, 0)), // Placeholder: SETI $X,IMM (will expand)
            Rule::inst_setl_ri => Ok(MMixInstruction::SETL(0, 0)),
            Rule::inst_seth_ri => Ok(MMixInstruction::SETH(0, 0)),
            Rule::inst_setmh_ri => Ok(MMixInstruction::SETMH(0, 0)),
            Rule::inst_setml_ri => Ok(MMixInstruction::SETML(0, 0)),
            Rule::inst_incl_ri => Ok(MMixInstruction::INCL(0, 0)),
            // LDA $X,$Y,Z (3-operand form): parse_inst_lda_rri always emits a
            // real 4-byte LDA regardless of Z's value -- it never expands to
            // SET, unlike the 2-operand form below.
            Rule::inst_lda_rri => Ok(MMixInstruction::LDA(0, 0, 0)),
            Rule::inst_lda_ri => {
                // Check if LDA will expand to SET (address > 0xFF)
                // We need to peek at the operand to determine this
                let mut parts = inner.clone().into_inner();
                let _mnem = parts.next();
                let operands = parts.next().unwrap();
                let mut ops = operands.into_inner();
                let _x = ops.next(); // skip register
                let addr_pair = ops.next().unwrap();

                // Try to resolve the address
                match self.parse_number(addr_pair) {
                    Ok(addr) if addr <= 0xFF => Ok(MMixInstruction::LDA(0, 0, 0)), // 4 bytes
                    _ => Ok(MMixInstruction::SET(0, 0)), // 16 bytes (will expand)
                }
            }
            Rule::inst_halt => Ok(MMixInstruction::HALT),
            // For all other instructions, return a standard 4-byte instruction
            _ => Ok(MMixInstruction::ADDU(0, 0, 0)),
        }
    }

    /// Round the location counter up to `alignment`, the way MMIXAL does
    /// before it assembles an item: a label on that line names the rounded
    /// address, and the skipped bytes are a gap rather than emitted padding.
    ///
    /// Both passes round at the same point, ahead of the item's operands.
    /// `peek_instruction_type` sizes the two-operand `LDA` from its operand's
    /// value, so rounding on opposite sides of operand evaluation would let
    /// the passes disagree about a forward reference with no other symptom.
    fn align_current_addr(&mut self, alignment: u64) {
        self.current_addr = self.current_addr.next_multiple_of(alignment);
    }

    /// Alignment of a data directive, taken from the directive's kind and
    /// never from the number of bytes it emits. `BYTE` stays unaligned
    /// however long its operand list; `WYDE`, `TETRA` and `OCTA` round to
    /// their own width.
    fn data_directive_alignment(pair: &pest::iterators::Pair<Rule>) -> Result<u64, String> {
        let directive = pair
            .clone()
            .into_inner()
            .next()
            .ok_or("Empty data directive")?;

        match directive.as_rule() {
            Rule::directive_byte => Ok(1),
            Rule::directive_wyde => Ok(2),
            Rule::directive_tetra => Ok(4),
            Rule::directive_octa => Ok(8),
            _ => Err(format!("Unknown data directive: {:?}", directive.as_rule())),
        }
    }

    /// Calculate the actual size of a data directive: its unit width times
    /// its unit count, where a string contributes one unit per decoded byte.
    fn data_directive_size(&self, pair: pest::iterators::Pair<Rule>) -> Result<u64, String> {
        let mut parts = pair.clone().into_inner();
        let directive = parts.next().ok_or("Empty data directive")?;

        let unit_width = Self::data_directive_unit_width(directive.as_rule())?;
        let values = parts.next().ok_or("Missing data values")?;

        let mut unit_count = 0u64;
        for value in values.into_inner() {
            let first = value.into_inner().next().unwrap();

            if first.as_rule() == Rule::string_literal {
                let text = first.as_str();
                let content = &text[1..text.len() - 1]; // Remove surrounding quotes
                unit_count += Self::count_string_bytes(content) as u64;
            } else {
                unit_count += 1;
            }
        }
        let total_size = unit_width * unit_count;
        debug!(
            "Data directive size: {} units x {} bytes = {} bytes",
            unit_count, unit_width, total_size
        );
        Ok(total_size)
    }

    /// The unit width, in bytes, that a data directive assembles per value.
    fn data_directive_unit_width(directive_kind: Rule) -> Result<u64, String> {
        match directive_kind {
            Rule::directive_byte => Ok(1),
            Rule::directive_wyde => Ok(2),
            Rule::directive_tetra => Ok(4),
            Rule::directive_octa => Ok(8),
            _ => Err(format!("Unknown data directive: {:?}", directive_kind)),
        }
    }

    fn parse_instruction(
        &mut self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let inner = pair.into_inner().next().ok_or("Empty instruction")?;

        match inner.as_rule() {
            Rule::inst_set => self.parse_inst_set(inner),
            Rule::inst_seti => self.parse_inst_seti(inner),
            Rule::inst_setl_ri => self.parse_inst_setl(inner),
            Rule::inst_seth_ri => self.parse_inst_seth(inner),
            Rule::inst_setmh_ri => self.parse_inst_setmh(inner),
            Rule::inst_setml_ri => self.parse_inst_setml(inner),
            Rule::inst_incl_ri => self.parse_inst_incl(inner),
            Rule::inst_inch_ri => self.parse_inst_inch(inner),
            Rule::inst_incmh_ri => self.parse_inst_incmh(inner),
            Rule::inst_incml_ri => self.parse_inst_incml(inner),
            Rule::inst_orh_ri => self.parse_inst_orh(inner),
            Rule::inst_ormh_ri => self.parse_inst_ormh(inner),
            Rule::inst_orml_ri => self.parse_inst_orml(inner),
            Rule::inst_orl_ri => self.parse_inst_orl(inner),
            Rule::inst_andnh_ri => self.parse_inst_andnh(inner),
            Rule::inst_andnmh_ri => self.parse_inst_andnmh(inner),
            Rule::inst_andnml_ri => self.parse_inst_andnml(inner),
            Rule::inst_andnl_ri => self.parse_inst_andnl(inner),
            Rule::inst_load_store_auto => self.parse_inst_load_store_auto(inner),
            Rule::inst_load_store_rri => self.parse_inst_load_store_rri(inner),
            Rule::inst_lda_auto => self.parse_inst_lda_auto(inner),
            Rule::inst_lda_rri => self.parse_inst_lda_rri(inner),
            Rule::inst_lda_ri => self.parse_inst_lda_ri(inner),
            Rule::inst_arith_auto => self.parse_inst_arith_auto(inner),
            Rule::inst_arith_rri => self.parse_inst_arith_rri(inner),
            Rule::inst_flot_round => self.parse_inst_flot_round(inner),
            Rule::inst_flot_auto => self.parse_inst_flot_auto(inner),
            Rule::inst_float_round_rrz => self.parse_inst_float_round_rrz(inner),
            Rule::inst_float_round_rr => self.parse_inst_float_round_rr(inner),
            Rule::inst_float_round_rri => self.parse_inst_float_round_rri(inner),
            Rule::inst_float_rri => self.parse_inst_float_rri(inner),
            Rule::inst_float_rrr => self.parse_inst_float_rrr(inner),
            Rule::inst_neg_auto => self.parse_inst_neg_auto(inner),
            Rule::inst_neg_rri => self.parse_inst_neg_rri(inner),
            Rule::inst_bitwise_auto => self.parse_inst_bitwise_auto(inner),
            Rule::inst_bitwise_rri => self.parse_inst_bitwise_rri(inner),
            Rule::inst_bitfiddle_auto => self.parse_inst_bitfiddle_auto(inner),
            Rule::inst_bitfiddle_rri => self.parse_inst_bitfiddle_rri(inner),
            Rule::inst_shift_auto => self.parse_inst_shift_auto(inner),
            Rule::inst_shift_rri => self.parse_inst_shift_rri(inner),
            Rule::inst_conditional_set_auto => self.parse_inst_conditional_set_auto(inner),
            Rule::inst_conditional_set_rri => self.parse_inst_conditional_set_rri(inner),
            Rule::inst_zero_or_set_auto => self.parse_inst_zero_or_set_auto(inner),
            Rule::inst_zero_or_set_rri => self.parse_inst_zero_or_set_rri(inner),
            Rule::inst_pbranch => self.parse_inst_pbranch(inner),
            Rule::inst_branch => self.parse_inst_branch(inner),
            Rule::inst_jmp => self.parse_inst_jmp(inner),
            Rule::inst_geta => self.parse_inst_geta(inner),
            Rule::inst_getab => self.parse_inst_getab(inner),
            Rule::inst_pushj => self.parse_inst_pushj(inner),
            Rule::inst_pushjb => self.parse_inst_pushjb(inner),
            Rule::inst_go_auto => self.parse_inst_go_auto(inner),
            Rule::inst_pushgo_rri => self.parse_inst_pushgo_rri(inner),
            Rule::inst_pop => self.parse_inst_pop(inner),
            Rule::inst_go_rri => self.parse_inst_go_rri(inner),
            Rule::inst_get => self.parse_inst_get(inner),
            Rule::inst_put_auto => self.parse_inst_put_auto(inner),
            Rule::inst_puti => self.parse_inst_puti(inner),
            Rule::inst_save => self.parse_inst_save(inner),
            Rule::inst_unsave => self.parse_inst_unsave(inner),
            Rule::inst_ldunc_rri => self.parse_inst_ldunc_rri(inner),
            Rule::inst_stunc_rri => self.parse_inst_stunc_rri(inner),
            Rule::inst_ldht_rri => self.parse_inst_ldht_rri(inner),
            Rule::inst_stht_rri => self.parse_inst_stht_rri(inner),
            Rule::inst_ldsf_rri => self.parse_inst_ldsf_rri(inner),
            Rule::inst_stsf_rri => self.parse_inst_stsf_rri(inner),
            Rule::inst_ldvts_rri => self.parse_inst_ldvts_rri(inner),
            Rule::inst_cswap_rri => self.parse_inst_cswap_rri(inner),
            Rule::inst_stco_auto => self.parse_inst_stco_auto(inner),
            Rule::inst_stco_rri => self.parse_inst_stco_rri(inner),
            Rule::inst_cache_auto => self.parse_inst_cache_auto(inner),
            Rule::inst_preld_rri => self.parse_inst_preld_rri(inner),
            Rule::inst_prego_rri => self.parse_inst_prego_rri(inner),
            Rule::inst_prest_rri => self.parse_inst_prest_rri(inner),
            Rule::inst_syncd_rri => self.parse_inst_syncd_rri(inner),
            Rule::inst_syncid_rri => self.parse_inst_syncid_rri(inner),
            Rule::inst_resume => self.parse_inst_resume(inner),
            Rule::inst_trip => self.parse_inst_trip(inner),
            Rule::inst_swym => self.parse_inst_swym(inner),
            Rule::inst_sync => self.parse_inst_sync(inner),
            Rule::inst_trap => self.parse_inst_trap(inner),
            Rule::inst_halt => Ok(MMixInstruction::HALT),
            _ => Err(format!(
                "Unsupported instruction rule: {:?}",
                inner.as_rule()
            )),
        }
    }

    fn parse_inst_set(&self, pair: pest::iterators::Pair<Rule>) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next(); // mnemonic_set
        let operands = parts.next().unwrap(); // operand_reg_z
        let mut ops = operands.into_inner();
        let dest = self.parse_register(ops.next().unwrap())?;
        self.lower_set_source(dest, ops.next().unwrap())
    }

    /// Resolve `SET`'s source operand into the instruction it selects: a
    /// register reference copies, anything else sets the low wyde. `SET`
    /// is one tetra, so the immediate form carries 16 bits.
    fn lower_set_source(
        &self,
        dest: u8,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let (line, col) = pair.line_col();
        let line = self.original_line(line).unwrap_or(line);

        let value_pair = if pair.as_rule() == Rule::register {
            let inner = pair
                .clone()
                .into_inner()
                .next()
                .expect("register rule has at least one child");
            if inner.as_rule() == Rule::register_num {
                return Ok(MMixInstruction::SETRR(dest, self.parse_register(pair)?));
            }
            let qualified = self.qualify_name(inner.as_str());
            if let Some(SymbolType::Register(r)) = self.symbols.get(&qualified).copied() {
                return Ok(MMixInstruction::SETRR(dest, r));
            }
            inner
        } else {
            pair
        };

        // A negative literal wraps into the field it names, as the 8-bit
        // immediates do; SETI is the sign-extended 64-bit form.
        let negative = value_pair
            .clone()
            .into_inner()
            .next()
            .is_some_and(|inner| inner.as_rule() == Rule::signed_number_literal);
        let value = self.parse_number(value_pair)?;

        if !negative && value > 0xFFFF {
            return Err(format!(
                "{}:{}:{}: immediate operand {} out of range 0..65535 for SET; use SETI for a wider constant",
                self.current_filename, line, col, value
            ));
        }
        Ok(MMixInstruction::SETL(dest, value as u16))
    }

    fn parse_inst_seti(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next(); // mnemonic_seti  
        let operands = parts.next().unwrap(); // operand_reg_imm
        let mut ops = operands.into_inner();
        let dest_reg = self.parse_register(ops.next().unwrap())?;
        let val = self.parse_number(ops.next().unwrap())?;

        Ok(MMixInstruction::SET(dest_reg, val))
    }

    fn parse_inst_setl(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let reg = self.parse_register(ops.next().unwrap())?;
        let val = self.parse_number(ops.next().unwrap())? as u16;
        Ok(MMixInstruction::SETL(reg, val))
    }

    fn parse_inst_seth(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let reg = self.parse_register(ops.next().unwrap())?;
        let val = self.parse_number(ops.next().unwrap())? as u16;
        Ok(MMixInstruction::SETH(reg, val))
    }

    fn parse_inst_setmh(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let reg = self.parse_register(ops.next().unwrap())?;
        let val = self.parse_number(ops.next().unwrap())? as u16;
        Ok(MMixInstruction::SETMH(reg, val))
    }

    fn parse_inst_setml(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let reg = self.parse_register(ops.next().unwrap())?;
        let val = self.parse_number(ops.next().unwrap())? as u16;
        Ok(MMixInstruction::SETML(reg, val))
    }

    fn parse_inst_incl(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let reg = self.parse_register(ops.next().unwrap())?;
        let val = self.parse_number(ops.next().unwrap())? as u16;
        Ok(MMixInstruction::INCL(reg, val))
    }

    fn parse_inst_inch(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let reg = self.parse_register(ops.next().unwrap())?;
        let val = self.parse_number(ops.next().unwrap())? as u16;
        Ok(MMixInstruction::INCH(reg, val))
    }

    fn parse_inst_incmh(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let reg = self.parse_register(ops.next().unwrap())?;
        let val = self.parse_number(ops.next().unwrap())? as u16;
        Ok(MMixInstruction::INCMH(reg, val))
    }

    fn parse_inst_incml(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let reg = self.parse_register(ops.next().unwrap())?;
        let val = self.parse_number(ops.next().unwrap())? as u16;
        Ok(MMixInstruction::INCML(reg, val))
    }

    fn parse_inst_orh(&self, pair: pest::iterators::Pair<Rule>) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let reg = self.parse_register(ops.next().unwrap())?;
        let val = self.parse_number(ops.next().unwrap())? as u16;
        Ok(MMixInstruction::ORH(reg, val))
    }

    fn parse_inst_ormh(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let reg = self.parse_register(ops.next().unwrap())?;
        let val = self.parse_number(ops.next().unwrap())? as u16;
        Ok(MMixInstruction::ORMH(reg, val))
    }

    fn parse_inst_orml(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let reg = self.parse_register(ops.next().unwrap())?;
        let val = self.parse_number(ops.next().unwrap())? as u16;
        Ok(MMixInstruction::ORML(reg, val))
    }

    fn parse_inst_orl(&self, pair: pest::iterators::Pair<Rule>) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let reg = self.parse_register(ops.next().unwrap())?;
        let val = self.parse_number(ops.next().unwrap())? as u16;
        Ok(MMixInstruction::ORL(reg, val))
    }

    fn parse_inst_andnh(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let reg = self.parse_register(ops.next().unwrap())?;
        let val = self.parse_number(ops.next().unwrap())? as u16;
        Ok(MMixInstruction::ANDNH(reg, val))
    }

    fn parse_inst_andnmh(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let reg = self.parse_register(ops.next().unwrap())?;
        let val = self.parse_number(ops.next().unwrap())? as u16;
        Ok(MMixInstruction::ANDNMH(reg, val))
    }

    fn parse_inst_andnml(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let reg = self.parse_register(ops.next().unwrap())?;
        let val = self.parse_number(ops.next().unwrap())? as u16;
        Ok(MMixInstruction::ANDNML(reg, val))
    }

    fn parse_inst_andnl(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let reg = self.parse_register(ops.next().unwrap())?;
        let val = self.parse_number(ops.next().unwrap())? as u16;
        Ok(MMixInstruction::ANDNL(reg, val))
    }

    fn parse_inst_load_store_auto(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem_pair = parts.next().unwrap();
        let mnem = mnem_pair.as_str().to_uppercase();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;
        let z_pair = ops.next().unwrap();
        let z = self.lower_z_operand(z_pair, &mnem)?;

        match (mnem.as_str(), z) {
            ("LDB", ZForm::Reg(z)) => Ok(MMixInstruction::LDB(x, y, z)),
            ("LDB", ZForm::Imm(z)) => Ok(MMixInstruction::LDBI(x, y, z)),
            ("LDBU", ZForm::Reg(z)) => Ok(MMixInstruction::LDBU(x, y, z)),
            ("LDBU", ZForm::Imm(z)) => Ok(MMixInstruction::LDBUI(x, y, z)),
            ("LDW", ZForm::Reg(z)) => Ok(MMixInstruction::LDW(x, y, z)),
            ("LDW", ZForm::Imm(z)) => Ok(MMixInstruction::LDWI(x, y, z)),
            ("LDWU", ZForm::Reg(z)) => Ok(MMixInstruction::LDWU(x, y, z)),
            ("LDWU", ZForm::Imm(z)) => Ok(MMixInstruction::LDWUI(x, y, z)),
            ("LDT", ZForm::Reg(z)) => Ok(MMixInstruction::LDT(x, y, z)),
            ("LDT", ZForm::Imm(z)) => Ok(MMixInstruction::LDTI(x, y, z)),
            ("LDTU", ZForm::Reg(z)) => Ok(MMixInstruction::LDTU(x, y, z)),
            ("LDTU", ZForm::Imm(z)) => Ok(MMixInstruction::LDTUI(x, y, z)),
            ("LDO", ZForm::Reg(z)) => Ok(MMixInstruction::LDO(x, y, z)),
            ("LDO", ZForm::Imm(z)) => Ok(MMixInstruction::LDOI(x, y, z)),
            ("LDOU", ZForm::Reg(z)) => Ok(MMixInstruction::LDOU(x, y, z)),
            ("LDOU", ZForm::Imm(z)) => Ok(MMixInstruction::LDOUI(x, y, z)),
            ("STB", ZForm::Reg(z)) => Ok(MMixInstruction::STB(x, y, z)),
            ("STB", ZForm::Imm(z)) => Ok(MMixInstruction::STBI(x, y, z)),
            ("STBU", ZForm::Reg(z)) => Ok(MMixInstruction::STBU(x, y, z)),
            ("STBU", ZForm::Imm(z)) => Ok(MMixInstruction::STBUI(x, y, z)),
            ("STW", ZForm::Reg(z)) => Ok(MMixInstruction::STW(x, y, z)),
            ("STW", ZForm::Imm(z)) => Ok(MMixInstruction::STWI(x, y, z)),
            ("STWU", ZForm::Reg(z)) => Ok(MMixInstruction::STWU(x, y, z)),
            ("STWU", ZForm::Imm(z)) => Ok(MMixInstruction::STWUI(x, y, z)),
            ("STT", ZForm::Reg(z)) => Ok(MMixInstruction::STT(x, y, z)),
            ("STT", ZForm::Imm(z)) => Ok(MMixInstruction::STTI(x, y, z)),
            ("STTU", ZForm::Reg(z)) => Ok(MMixInstruction::STTU(x, y, z)),
            ("STTU", ZForm::Imm(z)) => Ok(MMixInstruction::STTUI(x, y, z)),
            ("STO", ZForm::Reg(z)) => Ok(MMixInstruction::STO(x, y, z)),
            ("STO", ZForm::Imm(z)) => Ok(MMixInstruction::STOI(x, y, z)),
            ("STOU", ZForm::Reg(z)) => Ok(MMixInstruction::STOU(x, y, z)),
            ("STOU", ZForm::Imm(z)) => Ok(MMixInstruction::STOUI(x, y, z)),
            ("LDUNC", ZForm::Reg(z)) => Ok(MMixInstruction::LDUNC(x, y, z)),
            ("LDUNC", ZForm::Imm(z)) => Ok(MMixInstruction::LDUNCI(x, y, z)),
            ("STUNC", ZForm::Reg(z)) => Ok(MMixInstruction::STUNC(x, y, z)),
            ("STUNC", ZForm::Imm(z)) => Ok(MMixInstruction::STUNCI(x, y, z)),
            ("LDHT", ZForm::Reg(z)) => Ok(MMixInstruction::LDHT(x, y, z)),
            ("LDHT", ZForm::Imm(z)) => Ok(MMixInstruction::LDHTI(x, y, z)),
            ("STHT", ZForm::Reg(z)) => Ok(MMixInstruction::STHT(x, y, z)),
            ("STHT", ZForm::Imm(z)) => Ok(MMixInstruction::STHTI(x, y, z)),
            ("LDSF", ZForm::Reg(z)) => Ok(MMixInstruction::LDSF(x, y, z)),
            ("LDSF", ZForm::Imm(z)) => Ok(MMixInstruction::LDSFI(x, y, z)),
            ("STSF", ZForm::Reg(z)) => Ok(MMixInstruction::STSF(x, y, z)),
            ("STSF", ZForm::Imm(z)) => Ok(MMixInstruction::STSFI(x, y, z)),
            ("LDVTS", ZForm::Reg(z)) => Ok(MMixInstruction::LDVTS(x, y, z)),
            ("LDVTS", ZForm::Imm(z)) => Ok(MMixInstruction::LDVTSI(x, y, z)),
            ("CSWAP", ZForm::Reg(z)) => Ok(MMixInstruction::CSWAP(x, y, z)),
            ("CSWAP", ZForm::Imm(z)) => Ok(MMixInstruction::CSWAPI(x, y, z)),
            _ => Err(format!("Unknown load/store instruction: {}", mnem)),
        }
    }

    fn parse_inst_load_store_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;
        let z = self.parse_number(ops.next().unwrap())? as u8;

        match mnem.as_str().to_uppercase().as_str() {
            "LDBI" => Ok(MMixInstruction::LDBI(x, y, z)),
            "LDBUI" => Ok(MMixInstruction::LDBUI(x, y, z)),
            "LDWI" => Ok(MMixInstruction::LDWI(x, y, z)),
            "LDWUI" => Ok(MMixInstruction::LDWUI(x, y, z)),
            "LDTI" => Ok(MMixInstruction::LDTI(x, y, z)),
            "LDTUI" => Ok(MMixInstruction::LDTUI(x, y, z)),
            "LDOI" => Ok(MMixInstruction::LDOI(x, y, z)),
            "LDOUI" => Ok(MMixInstruction::LDOUI(x, y, z)),
            "STBI" => Ok(MMixInstruction::STBI(x, y, z)),
            "STBUI" => Ok(MMixInstruction::STBUI(x, y, z)),
            "STWI" => Ok(MMixInstruction::STWI(x, y, z)),
            "STWUI" => Ok(MMixInstruction::STWUI(x, y, z)),
            "STTI" => Ok(MMixInstruction::STTI(x, y, z)),
            "STTUI" => Ok(MMixInstruction::STTUI(x, y, z)),
            "STOI" => Ok(MMixInstruction::STOI(x, y, z)),
            "STOUI" => Ok(MMixInstruction::STOUI(x, y, z)),
            _ => Err(format!("Unknown load/store instruction: {}", mnem.as_str())),
        }
    }

    /// `LDA $X,$Y,$Z` is `ADDU $X,$Y,$Z` and `LDA $X,$Y,Z` is `ADDU $X,$Y,Z`,
    /// so Z selects the same pair of opcodes ADDU selects.
    fn parse_inst_lda_auto(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;

        match self.lower_z_operand(ops.next().unwrap(), "LDA")? {
            ZForm::Reg(z) => Ok(MMixInstruction::LDA(x, y, z)),
            ZForm::Imm(z) => Ok(MMixInstruction::LDAI(x, y, z)),
        }
    }

    fn parse_inst_lda_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        self.parse_rri(pair, MMixInstruction::LDAI)
    }

    fn parse_inst_lda_ri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let addr_value = self.parse_number(ops.next().unwrap())?;

        // LDA $X,Label where Label is a full 64-bit address should become SET
        // LDA is really ADDU $X,$0,Z where Z is an 8-bit immediate
        // If the address doesn't fit in 8 bits, use SET instead
        match mnem.as_str().to_uppercase().as_str() {
            "LDA" => {
                if addr_value <= 0xFF {
                    Ok(MMixInstruction::LDA(x, 0, addr_value as u8))
                } else {
                    // Address too large for LDA immediate form - use SET instead
                    debug!("LDA with large address {:#x} converted to SET", addr_value);
                    Ok(MMixInstruction::SET(x, addr_value))
                }
            }
            "LDAI" => {
                if addr_value <= 0xFF {
                    Ok(MMixInstruction::LDAI(x, 0, addr_value as u8))
                } else {
                    Ok(MMixInstruction::SET(x, addr_value))
                }
            }
            _ => Err(format!("Unknown LDA instruction: {}", mnem.as_str())),
        }
    }

    fn parse_inst_arith_auto(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem_pair = parts.next().unwrap();
        let mnem = mnem_pair.as_str().to_uppercase();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;
        let z_pair = ops.next().unwrap();
        let z = self.lower_z_operand(z_pair, &mnem)?;

        match (mnem.as_str(), z) {
            ("ADD", ZForm::Reg(z)) => Ok(MMixInstruction::ADD(x, y, z)),
            ("ADD", ZForm::Imm(z)) => Ok(MMixInstruction::ADDI(x, y, z)),
            ("ADDU", ZForm::Reg(z)) => Ok(MMixInstruction::ADDU(x, y, z)),
            ("ADDU", ZForm::Imm(z)) => Ok(MMixInstruction::ADDUI(x, y, z)),
            ("2ADDU", ZForm::Reg(z)) => Ok(MMixInstruction::ADDU2(x, y, z)),
            ("2ADDU", ZForm::Imm(z)) => Ok(MMixInstruction::ADDU2I(x, y, z)),
            ("4ADDU", ZForm::Reg(z)) => Ok(MMixInstruction::ADDU4(x, y, z)),
            ("4ADDU", ZForm::Imm(z)) => Ok(MMixInstruction::ADDU4I(x, y, z)),
            ("8ADDU", ZForm::Reg(z)) => Ok(MMixInstruction::ADDU8(x, y, z)),
            ("8ADDU", ZForm::Imm(z)) => Ok(MMixInstruction::ADDU8I(x, y, z)),
            ("16ADDU", ZForm::Reg(z)) => Ok(MMixInstruction::ADDU16(x, y, z)),
            ("16ADDU", ZForm::Imm(z)) => Ok(MMixInstruction::ADDU16I(x, y, z)),
            ("SUB", ZForm::Reg(z)) => Ok(MMixInstruction::SUB(x, y, z)),
            ("SUB", ZForm::Imm(z)) => Ok(MMixInstruction::SUBI(x, y, z)),
            ("SUBU", ZForm::Reg(z)) => Ok(MMixInstruction::SUBU(x, y, z)),
            ("SUBU", ZForm::Imm(z)) => Ok(MMixInstruction::SUBUI(x, y, z)),
            ("MUL", ZForm::Reg(z)) => Ok(MMixInstruction::MUL(x, y, z)),
            ("MUL", ZForm::Imm(z)) => Ok(MMixInstruction::MULI(x, y, z)),
            ("MULU", ZForm::Reg(z)) => Ok(MMixInstruction::MULU(x, y, z)),
            ("MULU", ZForm::Imm(z)) => Ok(MMixInstruction::MULUI(x, y, z)),
            ("DIV", ZForm::Reg(z)) => Ok(MMixInstruction::DIV(x, y, z)),
            ("DIV", ZForm::Imm(z)) => Ok(MMixInstruction::DIVI(x, y, z)),
            ("DIVU", ZForm::Reg(z)) => Ok(MMixInstruction::DIVU(x, y, z)),
            ("DIVU", ZForm::Imm(z)) => Ok(MMixInstruction::DIVUI(x, y, z)),
            ("CMP", ZForm::Reg(z)) => Ok(MMixInstruction::CMP(x, y, z)),
            ("CMP", ZForm::Imm(z)) => Ok(MMixInstruction::CMPI(x, y, z)),
            ("CMPU", ZForm::Reg(z)) => Ok(MMixInstruction::CMPU(x, y, z)),
            ("CMPU", ZForm::Imm(z)) => Ok(MMixInstruction::CMPUI(x, y, z)),
            _ => Err(format!("Unknown arithmetic instruction: {}", mnem)),
        }
    }

    fn parse_inst_arith_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;
        let z = self.parse_number(ops.next().unwrap())? as u8;

        match mnem.as_str().to_uppercase().as_str() {
            "ADDI" => Ok(MMixInstruction::ADDI(x, y, z)),
            "ADDUI" => Ok(MMixInstruction::ADDUI(x, y, z)),
            "2ADDUI" => Ok(MMixInstruction::ADDU2I(x, y, z)),
            "4ADDUI" => Ok(MMixInstruction::ADDU4I(x, y, z)),
            "8ADDUI" => Ok(MMixInstruction::ADDU8I(x, y, z)),
            "16ADDUI" => Ok(MMixInstruction::ADDU16I(x, y, z)),
            "SUBI" => Ok(MMixInstruction::SUBI(x, y, z)),
            "SUBUI" => Ok(MMixInstruction::SUBUI(x, y, z)),
            "MULI" => Ok(MMixInstruction::MULI(x, y, z)),
            "MULUI" => Ok(MMixInstruction::MULUI(x, y, z)),
            "DIVI" => Ok(MMixInstruction::DIVI(x, y, z)),
            "DIVUI" => Ok(MMixInstruction::DIVUI(x, y, z)),
            "CMPI" => Ok(MMixInstruction::CMPI(x, y, z)),
            "CMPUI" => Ok(MMixInstruction::CMPUI(x, y, z)),
            _ => Err(format!("Unknown arithmetic instruction: {}", mnem.as_str())),
        }
    }

    fn parse_inst_neg_auto(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap().as_str().to_uppercase();
        // No operand wrapper for inst_neg_auto - operands are directly in the rule
        let x = self.parse_register(parts.next().unwrap())?;
        let y = self.parse_number(parts.next().unwrap())? as u8;
        let z = self.lower_z_operand(parts.next().unwrap(), &mnem)?;

        match (mnem.as_str(), z) {
            ("NEG", ZForm::Reg(z)) => Ok(MMixInstruction::NEG(x, y, z)),
            ("NEG", ZForm::Imm(z)) => Ok(MMixInstruction::NEGI(x, y, z)),
            ("NEGU", ZForm::Reg(z)) => Ok(MMixInstruction::NEGU(x, y, z)),
            ("NEGU", ZForm::Imm(z)) => Ok(MMixInstruction::NEGUI(x, y, z)),
            _ => Err(format!("Unknown NEG instruction: {}", mnem)),
        }
    }

    fn parse_inst_neg_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap();
        let name = mnem.as_str().to_uppercase();
        // No operand wrapper for inst_neg_rri - operands are directly in the rule
        let x = self.parse_register(parts.next().unwrap())?;
        let y = self.parse_number(parts.next().unwrap())? as u8;
        let z_operand = parts.next().unwrap();
        let (line, col) = z_operand.line_col();
        let line = self.original_line(line).unwrap_or(line);
        let z = self.imm_byte(self.parse_number(z_operand)?, &name, line, col)?;

        match name.as_str() {
            "NEGI" => Ok(MMixInstruction::NEGI(x, y, z)),
            "NEGUI" => Ok(MMixInstruction::NEGUI(x, y, z)),
            _ => Err(format!("Unknown NEG instruction: {}", mnem.as_str())),
        }
    }

    fn parse_inst_float_rrr(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;
        let z = self.parse_register(ops.next().unwrap())?;

        match mnem.as_str().to_uppercase().as_str() {
            "FCMP" => Ok(MMixInstruction::FCMP(x, y, z)),
            "FUN" => Ok(MMixInstruction::FUN(x, y, z)),
            "FEQL" => Ok(MMixInstruction::FEQL(x, y, z)),
            "FCMPE" => Ok(MMixInstruction::FCMPE(x, y, z)),
            "FUNE" => Ok(MMixInstruction::FUNE(x, y, z)),
            "FEQLE" => Ok(MMixInstruction::FEQLE(x, y, z)),
            "FADD" => Ok(MMixInstruction::FADD(x, y, z)),
            "FSUB" => Ok(MMixInstruction::FSUB(x, y, z)),
            "FMUL" => Ok(MMixInstruction::FMUL(x, y, z)),
            "FDIV" => Ok(MMixInstruction::FDIV(x, y, z)),
            "FREM" => Ok(MMixInstruction::FREM(x, y, z)),
            _ => Err(format!(
                "Unknown floating point instruction: {}",
                mnem.as_str()
            )),
        }
    }

    /// `FIX`/`FIXU`/`FSQRT`/`FINT`, 3-operand form: `Y` is a rounding-mode
    /// value (`0..=4`, `ROUND_CURRENT`/`ROUND_OFF`/`ROUND_UP`/`ROUND_DOWN`/
    /// `ROUND_NEAR`), range-checked at runtime (`Y > 4` halts), not here —
    /// mirrors how `NEG`'s own value-typed `Y` is parsed.
    fn parse_inst_float_round_rrz(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap();
        let x = self.parse_register(parts.next().unwrap())?;
        let y = self.parse_number(parts.next().unwrap())? as u8;
        let z = self.parse_register(parts.next().unwrap())?;

        match mnem.as_str().to_uppercase().as_str() {
            "FIX" => Ok(MMixInstruction::FIX(x, y, z)),
            "FIXU" => Ok(MMixInstruction::FIXU(x, y, z)),
            "FSQRT" => Ok(MMixInstruction::FSQRT(x, y, z)),
            "FINT" => Ok(MMixInstruction::FINT(x, y, z)),
            _ => Err(format!(
                "Unknown floating point instruction: {}",
                mnem.as_str()
            )),
        }
    }

    /// `FIX`/`FIXU`/`FSQRT`/`FINT`, 2-operand form: `Y` is implicitly 0
    /// (`ROUND_CURRENT` — no override, use rA's mode).
    fn parse_inst_float_round_rr(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let z = self.parse_register(ops.next().unwrap())?;

        match mnem.as_str().to_uppercase().as_str() {
            "FIX" => Ok(MMixInstruction::FIX(x, 0, z)),
            "FIXU" => Ok(MMixInstruction::FIXU(x, 0, z)),
            "FSQRT" => Ok(MMixInstruction::FSQRT(x, 0, z)),
            "FINT" => Ok(MMixInstruction::FINT(x, 0, z)),
            _ => Err(format!(
                "Unknown floating point instruction: {}",
                mnem.as_str()
            )),
        }
    }

    /// `FLOT`/`FLOTU`/`SFLOT`/`SFLOTU`, 3-operand form: `Y` forces a
    /// rounding mode, `Z` auto-selects register or immediate.
    fn parse_inst_flot_round(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap().as_str().to_uppercase();
        let x = self.parse_register(parts.next().unwrap())?;
        let y = self.parse_number(parts.next().unwrap())? as u8;
        let z = self.lower_z_operand(parts.next().unwrap(), &mnem)?;

        match (mnem.as_str(), z) {
            ("FLOT", ZForm::Reg(z)) => Ok(MMixInstruction::FLOT(x, y, z)),
            ("FLOT", ZForm::Imm(z)) => Ok(MMixInstruction::FLOTI(x, y, z)),
            ("FLOTU", ZForm::Reg(z)) => Ok(MMixInstruction::FLOTU(x, y, z)),
            ("FLOTU", ZForm::Imm(z)) => Ok(MMixInstruction::FLOTUI(x, y, z)),
            ("SFLOT", ZForm::Reg(z)) => Ok(MMixInstruction::SFLOT(x, y, z)),
            ("SFLOT", ZForm::Imm(z)) => Ok(MMixInstruction::SFLOTI(x, y, z)),
            ("SFLOTU", ZForm::Reg(z)) => Ok(MMixInstruction::SFLOTU(x, y, z)),
            ("SFLOTU", ZForm::Imm(z)) => Ok(MMixInstruction::SFLOTUI(x, y, z)),
            _ => Err(format!("Unknown float conversion instruction: {}", mnem)),
        }
    }

    /// `FLOT`/`FLOTU`/`SFLOT`/`SFLOTU`, 2-operand form: `Y` implicitly 0.
    fn parse_inst_flot_auto(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap().as_str().to_uppercase();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let z = self.lower_z_operand(ops.next().unwrap(), &mnem)?;

        match (mnem.as_str(), z) {
            ("FLOT", ZForm::Reg(z)) => Ok(MMixInstruction::FLOT(x, 0, z)),
            ("FLOT", ZForm::Imm(z)) => Ok(MMixInstruction::FLOTI(x, 0, z)),
            ("FLOTU", ZForm::Reg(z)) => Ok(MMixInstruction::FLOTU(x, 0, z)),
            ("FLOTU", ZForm::Imm(z)) => Ok(MMixInstruction::FLOTUI(x, 0, z)),
            ("SFLOT", ZForm::Reg(z)) => Ok(MMixInstruction::SFLOT(x, 0, z)),
            ("SFLOT", ZForm::Imm(z)) => Ok(MMixInstruction::SFLOTI(x, 0, z)),
            ("SFLOTU", ZForm::Reg(z)) => Ok(MMixInstruction::SFLOTU(x, 0, z)),
            ("SFLOTU", ZForm::Imm(z)) => Ok(MMixInstruction::SFLOTUI(x, 0, z)),
            _ => Err(format!("Unknown float conversion instruction: {}", mnem)),
        }
    }

    /// `FLOTI`/`FLOTUI`/`SFLOTI`/`SFLOTUI`, 3-operand form: `Y` forces a
    /// rounding mode, `Z` stays immediate-only.
    fn parse_inst_float_round_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap();
        let x = self.parse_register(parts.next().unwrap())?;
        let y = self.parse_number(parts.next().unwrap())? as u8;
        let z = self.parse_number(parts.next().unwrap())? as u8;

        match mnem.as_str().to_uppercase().as_str() {
            "FLOTI" => Ok(MMixInstruction::FLOTI(x, y, z)),
            "FLOTUI" => Ok(MMixInstruction::FLOTUI(x, y, z)),
            "SFLOTI" => Ok(MMixInstruction::SFLOTI(x, y, z)),
            "SFLOTUI" => Ok(MMixInstruction::SFLOTUI(x, y, z)),
            _ => Err(format!(
                "Unknown floating point immediate instruction: {}",
                mnem.as_str()
            )),
        }
    }

    /// `FLOTI`/`FLOTUI`/`SFLOTI`/`SFLOTUI`, 2-operand form: `Y` implicitly 0.
    fn parse_inst_float_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let z = self.parse_number(ops.next().unwrap())? as u8;

        match mnem.as_str().to_uppercase().as_str() {
            "FLOTI" => Ok(MMixInstruction::FLOTI(x, 0, z)),
            "FLOTUI" => Ok(MMixInstruction::FLOTUI(x, 0, z)),
            "SFLOTI" => Ok(MMixInstruction::SFLOTI(x, 0, z)),
            "SFLOTUI" => Ok(MMixInstruction::SFLOTUI(x, 0, z)),
            _ => Err(format!(
                "Unknown floating point immediate instruction: {}",
                mnem.as_str()
            )),
        }
    }

    fn parse_inst_bitwise_auto(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem_pair = parts.next().unwrap();
        let mnem = mnem_pair.as_str().to_uppercase();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;
        let z_pair = ops.next().unwrap();
        let z = self.lower_z_operand(z_pair, &mnem)?;

        match (mnem.as_str(), z) {
            ("AND", ZForm::Reg(z)) => Ok(MMixInstruction::AND(x, y, z)),
            ("AND", ZForm::Imm(z)) => Ok(MMixInstruction::ANDI(x, y, z)),
            ("OR", ZForm::Reg(z)) => Ok(MMixInstruction::OR(x, y, z)),
            ("OR", ZForm::Imm(z)) => Ok(MMixInstruction::ORI(x, y, z)),
            ("XOR", ZForm::Reg(z)) => Ok(MMixInstruction::XOR(x, y, z)),
            ("XOR", ZForm::Imm(z)) => Ok(MMixInstruction::XORI(x, y, z)),
            ("ANDN", ZForm::Reg(z)) => Ok(MMixInstruction::ANDN(x, y, z)),
            ("ANDN", ZForm::Imm(z)) => Ok(MMixInstruction::ANDNI(x, y, z)),
            ("ORN", ZForm::Reg(z)) => Ok(MMixInstruction::ORN(x, y, z)),
            ("ORN", ZForm::Imm(z)) => Ok(MMixInstruction::ORNI(x, y, z)),
            ("NAND", ZForm::Reg(z)) => Ok(MMixInstruction::NAND(x, y, z)),
            ("NAND", ZForm::Imm(z)) => Ok(MMixInstruction::NANDI(x, y, z)),
            ("NOR", ZForm::Reg(z)) => Ok(MMixInstruction::NOR(x, y, z)),
            ("NOR", ZForm::Imm(z)) => Ok(MMixInstruction::NORI(x, y, z)),
            ("NXOR", ZForm::Reg(z)) => Ok(MMixInstruction::NXOR(x, y, z)),
            ("NXOR", ZForm::Imm(z)) => Ok(MMixInstruction::NXORI(x, y, z)),
            ("MUX", ZForm::Reg(z)) => Ok(MMixInstruction::MUX(x, y, z)),
            ("MUX", ZForm::Imm(z)) => Ok(MMixInstruction::MUXI(x, y, z)),
            _ => Err(format!("Unknown bitwise instruction: {}", mnem)),
        }
    }

    fn parse_inst_bitwise_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;
        let z = self.parse_number(ops.next().unwrap())? as u8;

        match mnem.as_str().to_uppercase().as_str() {
            "ANDI" => Ok(MMixInstruction::ANDI(x, y, z)),
            "ORI" => Ok(MMixInstruction::ORI(x, y, z)),
            "XORI" => Ok(MMixInstruction::XORI(x, y, z)),
            "ANDNI" => Ok(MMixInstruction::ANDNI(x, y, z)),
            "ORNI" => Ok(MMixInstruction::ORNI(x, y, z)),
            "NANDI" => Ok(MMixInstruction::NANDI(x, y, z)),
            "NORI" => Ok(MMixInstruction::NORI(x, y, z)),
            "NXORI" => Ok(MMixInstruction::NXORI(x, y, z)),
            "MUXI" => Ok(MMixInstruction::MUXI(x, y, z)),
            _ => Err(format!("Unknown bitwise instruction: {}", mnem.as_str())),
        }
    }

    fn parse_inst_bitfiddle_auto(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem_pair = parts.next().unwrap();
        let mnem = mnem_pair.as_str().to_uppercase();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;
        let z_pair = ops.next().unwrap();
        let z = self.lower_z_operand(z_pair, &mnem)?;

        match (mnem.as_str(), z) {
            ("BDIF", ZForm::Reg(z)) => Ok(MMixInstruction::BDIF(x, y, z)),
            ("BDIF", ZForm::Imm(z)) => Ok(MMixInstruction::BDIFI(x, y, z)),
            ("WDIF", ZForm::Reg(z)) => Ok(MMixInstruction::WDIF(x, y, z)),
            ("WDIF", ZForm::Imm(z)) => Ok(MMixInstruction::WDIFI(x, y, z)),
            ("TDIF", ZForm::Reg(z)) => Ok(MMixInstruction::TDIF(x, y, z)),
            ("TDIF", ZForm::Imm(z)) => Ok(MMixInstruction::TDIFI(x, y, z)),
            ("ODIF", ZForm::Reg(z)) => Ok(MMixInstruction::ODIF(x, y, z)),
            ("ODIF", ZForm::Imm(z)) => Ok(MMixInstruction::ODIFI(x, y, z)),
            ("SADD", ZForm::Reg(z)) => Ok(MMixInstruction::SADD(x, y, z)),
            ("SADD", ZForm::Imm(z)) => Ok(MMixInstruction::SADDI(x, y, z)),
            ("MOR", ZForm::Reg(z)) => Ok(MMixInstruction::MOR(x, y, z)),
            ("MOR", ZForm::Imm(z)) => Ok(MMixInstruction::MORI(x, y, z)),
            ("MXOR", ZForm::Reg(z)) => Ok(MMixInstruction::MXOR(x, y, z)),
            ("MXOR", ZForm::Imm(z)) => Ok(MMixInstruction::MXORI(x, y, z)),
            _ => Err(format!("Unknown bit fiddling instruction: {}", mnem)),
        }
    }

    fn parse_inst_bitfiddle_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;
        let z = self.parse_number(ops.next().unwrap())? as u8;

        match mnem.as_str().to_uppercase().as_str() {
            "BDIFI" => Ok(MMixInstruction::BDIFI(x, y, z)),
            "WDIFI" => Ok(MMixInstruction::WDIFI(x, y, z)),
            "TDIFI" => Ok(MMixInstruction::TDIFI(x, y, z)),
            "ODIFI" => Ok(MMixInstruction::ODIFI(x, y, z)),
            "SADDI" => Ok(MMixInstruction::SADDI(x, y, z)),
            "MORI" => Ok(MMixInstruction::MORI(x, y, z)),
            "MXORI" => Ok(MMixInstruction::MXORI(x, y, z)),
            _ => Err(format!(
                "Unknown bit fiddling instruction: {}",
                mnem.as_str()
            )),
        }
    }

    fn parse_inst_shift_auto(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem_pair = parts.next().unwrap();
        let mnem = mnem_pair.as_str().to_uppercase();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;
        let z_pair = ops.next().unwrap();
        let z = self.lower_z_operand(z_pair, &mnem)?;

        match (mnem.as_str(), z) {
            ("SL", ZForm::Reg(z)) => Ok(MMixInstruction::SL(x, y, z)),
            ("SL", ZForm::Imm(z)) => Ok(MMixInstruction::SLI(x, y, z)),
            ("SLU", ZForm::Reg(z)) => Ok(MMixInstruction::SLU(x, y, z)),
            ("SLU", ZForm::Imm(z)) => Ok(MMixInstruction::SLUI(x, y, z)),
            ("SR", ZForm::Reg(z)) => Ok(MMixInstruction::SR(x, y, z)),
            ("SR", ZForm::Imm(z)) => Ok(MMixInstruction::SRI(x, y, z)),
            ("SRU", ZForm::Reg(z)) => Ok(MMixInstruction::SRU(x, y, z)),
            ("SRU", ZForm::Imm(z)) => Ok(MMixInstruction::SRUI(x, y, z)),
            _ => Err(format!("Unknown shift instruction: {}", mnem)),
        }
    }

    fn parse_inst_shift_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;
        let z = self.parse_number(ops.next().unwrap())? as u8;

        match mnem.as_str().to_uppercase().as_str() {
            "SLI" => Ok(MMixInstruction::SLI(x, y, z)),
            "SLUI" => Ok(MMixInstruction::SLUI(x, y, z)),
            "SRI" => Ok(MMixInstruction::SRI(x, y, z)),
            "SRUI" => Ok(MMixInstruction::SRUI(x, y, z)),
            _ => Err(format!("Unknown shift instruction: {}", mnem.as_str())),
        }
    }

    fn parse_inst_conditional_set_auto(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem_pair = parts.next().unwrap();
        let mnem = mnem_pair.as_str().to_uppercase();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;
        let z_pair = ops.next().unwrap();
        let z = self.lower_z_operand(z_pair, &mnem)?;

        match (mnem.as_str(), z) {
            ("CSN", ZForm::Reg(z)) => Ok(MMixInstruction::CSN(x, y, z)),
            ("CSN", ZForm::Imm(z)) => Ok(MMixInstruction::CSNI(x, y, z)),
            ("CSZ", ZForm::Reg(z)) => Ok(MMixInstruction::CSZ(x, y, z)),
            ("CSZ", ZForm::Imm(z)) => Ok(MMixInstruction::CSZI(x, y, z)),
            ("CSP", ZForm::Reg(z)) => Ok(MMixInstruction::CSP(x, y, z)),
            ("CSP", ZForm::Imm(z)) => Ok(MMixInstruction::CSPI(x, y, z)),
            ("CSOD", ZForm::Reg(z)) => Ok(MMixInstruction::CSOD(x, y, z)),
            ("CSOD", ZForm::Imm(z)) => Ok(MMixInstruction::CSODI(x, y, z)),
            ("CSNN", ZForm::Reg(z)) => Ok(MMixInstruction::CSNN(x, y, z)),
            ("CSNN", ZForm::Imm(z)) => Ok(MMixInstruction::CSNNI(x, y, z)),
            ("CSNZ", ZForm::Reg(z)) => Ok(MMixInstruction::CSNZ(x, y, z)),
            ("CSNZ", ZForm::Imm(z)) => Ok(MMixInstruction::CSNZI(x, y, z)),
            ("CSNP", ZForm::Reg(z)) => Ok(MMixInstruction::CSNP(x, y, z)),
            ("CSNP", ZForm::Imm(z)) => Ok(MMixInstruction::CSNPI(x, y, z)),
            ("CSEV", ZForm::Reg(z)) => Ok(MMixInstruction::CSEV(x, y, z)),
            ("CSEV", ZForm::Imm(z)) => Ok(MMixInstruction::CSEVI(x, y, z)),
            _ => Err(format!("Unknown conditional set instruction: {}", mnem)),
        }
    }

    fn parse_inst_conditional_set_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;
        let z = self.parse_number(ops.next().unwrap())? as u8;

        match mnem.as_str().to_uppercase().as_str() {
            "CSNI" => Ok(MMixInstruction::CSNI(x, y, z)),
            "CSZI" => Ok(MMixInstruction::CSZI(x, y, z)),
            "CSPI" => Ok(MMixInstruction::CSPI(x, y, z)),
            "CSODI" => Ok(MMixInstruction::CSODI(x, y, z)),
            "CSNNI" => Ok(MMixInstruction::CSNNI(x, y, z)),
            "CSNZI" => Ok(MMixInstruction::CSNZI(x, y, z)),
            "CSNPI" => Ok(MMixInstruction::CSNPI(x, y, z)),
            "CSEVI" => Ok(MMixInstruction::CSEVI(x, y, z)),
            _ => Err(format!(
                "Unknown conditional set immediate instruction: {}",
                mnem.as_str()
            )),
        }
    }

    fn parse_inst_zero_or_set_auto(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem_pair = parts.next().unwrap();
        let mnem = mnem_pair.as_str().to_uppercase();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;
        let z_pair = ops.next().unwrap();
        let z = self.lower_z_operand(z_pair, &mnem)?;

        match (mnem.as_str(), z) {
            ("ZSN", ZForm::Reg(z)) => Ok(MMixInstruction::ZSN(x, y, z)),
            ("ZSN", ZForm::Imm(z)) => Ok(MMixInstruction::ZSNI(x, y, z)),
            ("ZSZ", ZForm::Reg(z)) => Ok(MMixInstruction::ZSZ(x, y, z)),
            ("ZSZ", ZForm::Imm(z)) => Ok(MMixInstruction::ZSZI(x, y, z)),
            ("ZSP", ZForm::Reg(z)) => Ok(MMixInstruction::ZSP(x, y, z)),
            ("ZSP", ZForm::Imm(z)) => Ok(MMixInstruction::ZSPI(x, y, z)),
            ("ZSOD", ZForm::Reg(z)) => Ok(MMixInstruction::ZSOD(x, y, z)),
            ("ZSOD", ZForm::Imm(z)) => Ok(MMixInstruction::ZSODI(x, y, z)),
            ("ZSNN", ZForm::Reg(z)) => Ok(MMixInstruction::ZSNN(x, y, z)),
            ("ZSNN", ZForm::Imm(z)) => Ok(MMixInstruction::ZSNNI(x, y, z)),
            ("ZSNZ", ZForm::Reg(z)) => Ok(MMixInstruction::ZSNZ(x, y, z)),
            ("ZSNZ", ZForm::Imm(z)) => Ok(MMixInstruction::ZSNZI(x, y, z)),
            ("ZSNP", ZForm::Reg(z)) => Ok(MMixInstruction::ZSNP(x, y, z)),
            ("ZSNP", ZForm::Imm(z)) => Ok(MMixInstruction::ZSNPI(x, y, z)),
            ("ZSEV", ZForm::Reg(z)) => Ok(MMixInstruction::ZSEV(x, y, z)),
            ("ZSEV", ZForm::Imm(z)) => Ok(MMixInstruction::ZSEVI(x, y, z)),
            _ => Err(format!("Unknown zero or set instruction: {}", mnem)),
        }
    }

    fn parse_inst_zero_or_set_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;
        let z = self.parse_number(ops.next().unwrap())? as u8;

        match mnem.as_str().to_uppercase().as_str() {
            "ZSNI" => Ok(MMixInstruction::ZSNI(x, y, z)),
            "ZSZI" => Ok(MMixInstruction::ZSZI(x, y, z)),
            "ZSPI" => Ok(MMixInstruction::ZSPI(x, y, z)),
            "ZSODI" => Ok(MMixInstruction::ZSODI(x, y, z)),
            "ZSNNI" => Ok(MMixInstruction::ZSNNI(x, y, z)),
            "ZSNZI" => Ok(MMixInstruction::ZSNZI(x, y, z)),
            "ZSNPI" => Ok(MMixInstruction::ZSNPI(x, y, z)),
            "ZSEVI" => Ok(MMixInstruction::ZSEVI(x, y, z)),
            _ => Err(format!(
                "Unknown zero or set immediate instruction: {}",
                mnem.as_str()
            )),
        }
    }

    /// Resolve a PC-relative target into the field a `bits`-wide operand
    /// carries. Forward reaches `0..=2^bits - 1` tetras and backward
    /// `1..=2^bits`, so a displacement of zero takes the forward opcode. A
    /// mnemonic spelled with a trailing `B` asserts a backward target and
    /// rejects a forward one; every other mnemonic takes its direction from
    /// the sign of the displacement. `absolute_alternative` names an absolute
    /// instruction to suggest when the target is unreachable, or is empty.
    fn relative_field(
        &self,
        mnemonic: &str,
        target: u64,
        bits: u32,
        (line, col): (usize, usize),
        absolute_alternative: &str,
    ) -> Result<RelativeField, String> {
        let delta = target.wrapping_sub(self.current_addr) as i64;
        if delta % 4 != 0 {
            return Err(format!(
                "{}:{}:{}: {} target 0x{:X} is not 4-byte aligned relative to the current instruction (byte delta {})",
                self.current_filename, line, col, mnemonic, target, delta
            ));
        }
        let tetras = delta / 4;
        if let Some(forward_sibling) = mnemonic.strip_suffix('B')
            && tetras >= 0
        {
            return Err(format!(
                "{}:{}:{}: {} target 0x{:X} is not behind the current instruction ({} only encodes backward addresses; use {} instead)",
                self.current_filename, line, col, mnemonic, target, mnemonic, forward_sibling
            ));
        }
        let span = 1i64 << bits;
        let out_of_range = |direction: &str, reach_tetras: i64| {
            format!(
                "{}:{}:{}: {} target 0x{:X} is out of range: {} byte delta {} exceeds {}'s {}-byte {} reach{}",
                self.current_filename,
                line,
                col,
                mnemonic,
                target,
                direction,
                delta.unsigned_abs(),
                mnemonic,
                reach_tetras * 4,
                direction,
                absolute_alternative
            )
        };
        if tetras >= 0 {
            if tetras >= span {
                return Err(out_of_range("forward", span - 1));
            }
            return Ok(RelativeField {
                backward: false,
                field: tetras as u32,
            });
        }
        if -tetras > span {
            return Err(out_of_range("backward", span));
        }
        Ok(RelativeField {
            backward: true,
            field: (span + tetras) as u32,
        })
    }

    fn parse_inst_branch(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let (line, col) = pair.line_col();
        let line = self.original_line(line).unwrap_or(line);
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let target = self.parse_number(ops.next().unwrap())?;

        // Each mnemonic names the variant to emit for a forward target and
        // the one for a backward target.
        type Branch = fn(u8, u16) -> MMixInstruction;
        let mnem = mnem.as_str().to_uppercase();
        let (forward, backward): (Branch, Branch) = match mnem.as_str() {
            "BN" | "BNB" => (MMixInstruction::BN, MMixInstruction::BNB),
            "BZ" | "BZB" => (MMixInstruction::BZ, MMixInstruction::BZB),
            "BP" | "BPB" => (MMixInstruction::BP, MMixInstruction::BPB),
            "BOD" | "BODB" => (MMixInstruction::BOD, MMixInstruction::BODB),
            "BNN" | "BNNB" => (MMixInstruction::BNN, MMixInstruction::BNNB),
            "BNZ" | "BNZB" => (MMixInstruction::BNZ, MMixInstruction::BNZB),
            "BNP" | "BNPB" => (MMixInstruction::BNP, MMixInstruction::BNPB),
            "BEV" | "BEVB" => (MMixInstruction::BEV, MMixInstruction::BEVB),
            _ => return Err(format!("Unknown branch instruction: {mnem}")),
        };

        let resolved = self.relative_field(&mnem, target, 16, (line, col), "")?;
        let field = resolved.field as u16;
        Ok(if resolved.backward {
            backward(x, field)
        } else {
            forward(x, field)
        })
    }

    fn parse_inst_jmp(&self, pair: pest::iterators::Pair<Rule>) -> Result<MMixInstruction, String> {
        let (line, col) = pair.line_col();
        let line = self.original_line(line).unwrap_or(line);
        let mut parts = pair.into_inner();
        let mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let target = self.parse_number(ops.next().unwrap())?;
        let mnem = mnem.map_or_else(|| "JMP".to_string(), |m| m.as_str().to_uppercase());
        let resolved = self.relative_field(&mnem, target, 24, (line, col), " (use GO instead)")?;
        Ok(if resolved.backward {
            MMixInstruction::JMPB(resolved.field)
        } else {
            MMixInstruction::JMP(resolved.field)
        })
    }

    fn parse_inst_pbranch(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let (line, col) = pair.line_col();
        let line = self.original_line(line).unwrap_or(line);
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let target = self.parse_number(ops.next().unwrap())?;

        type ProbableBranch = fn(u8, u8, u8) -> MMixInstruction;
        let mnem = mnem.as_str().to_uppercase();
        let (forward, backward): (ProbableBranch, ProbableBranch) = match mnem.as_str() {
            "PBN" | "PBNB" => (MMixInstruction::PBN, MMixInstruction::PBNB),
            "PBZ" | "PBZB" => (MMixInstruction::PBZ, MMixInstruction::PBZB),
            "PBP" | "PBPB" => (MMixInstruction::PBP, MMixInstruction::PBPB),
            "PBOD" | "PBODB" => (MMixInstruction::PBOD, MMixInstruction::PBODB),
            "PBNN" | "PBNNB" => (MMixInstruction::PBNN, MMixInstruction::PBNNB),
            "PBNZ" | "PBNZB" => (MMixInstruction::PBNZ, MMixInstruction::PBNZB),
            "PBNP" | "PBNPB" => (MMixInstruction::PBNP, MMixInstruction::PBNPB),
            "PBEV" | "PBEVB" => (MMixInstruction::PBEV, MMixInstruction::PBEVB),
            _ => return Err(format!("Unknown probable branch instruction: {mnem}")),
        };

        let resolved = self.relative_field(&mnem, target, 16, (line, col), "")?;
        let y = (resolved.field >> 8) as u8;
        let z = (resolved.field & 0xFF) as u8;
        Ok(if resolved.backward {
            backward(x, y, z)
        } else {
            forward(x, y, z)
        })
    }

    fn parse_inst_geta(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let (line, col) = pair.line_col();
        let line = self.original_line(line).unwrap_or(line);
        let mut parts = pair.into_inner();
        let _mnem = parts.next(); // Skip mnemonic
        let operand = parts.next().unwrap(); // Get operand_reg_imm

        let mut operand_parts = operand.into_inner();
        let reg_pair = operand_parts.next().unwrap();
        let addr_pair = operand_parts.next().unwrap();

        let x = self.parse_register(reg_pair)?;
        let addr = self.parse_number(addr_pair)?;

        debug!(
            "GETA: current_addr=0x{:X}, target_addr=0x{:X}",
            self.current_addr, addr
        );

        // GETA reaches 65535 tetras forward; a backward target takes GETAB.
        let resolved = self.relative_field(
            "GETA",
            addr,
            16,
            (line, col),
            " (use LDA for longer-range addresses)",
        )?;
        let y = (resolved.field >> 8) as u8;
        let z = (resolved.field & 0xFF) as u8;

        debug!(
            "GETA: backward={}, field=0x{:X}, y=0x{:X}, z=0x{:X}",
            resolved.backward, resolved.field, y, z
        );

        Ok(if resolved.backward {
            MMixInstruction::GETAB(x, y, z)
        } else {
            MMixInstruction::GETA(x, y, z)
        })
    }

    fn parse_inst_getab(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let (line, col) = pair.line_col();
        let line = self.original_line(line).unwrap_or(line);
        let mut parts = pair.into_inner();
        let _mnem = parts.next(); // Skip mnemonic
        let operand = parts.next().unwrap(); // Get operand_reg_imm

        let mut operand_parts = operand.into_inner();
        let reg_pair = operand_parts.next().unwrap();
        let addr_pair = operand_parts.next().unwrap();

        let x = self.parse_register(reg_pair)?;
        let addr = self.parse_number(addr_pair)?;

        let resolved = self.relative_field(
            "GETAB",
            addr,
            16,
            (line, col),
            " (use LDA for longer-range addresses)",
        )?;
        let y = (resolved.field >> 8) as u8;
        let z = (resolved.field & 0xFF) as u8;

        Ok(MMixInstruction::GETAB(x, y, z))
    }

    fn parse_inst_trap(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let x = self.parse_number(parts.next().unwrap())? as u8;
        let y = self.parse_number(parts.next().unwrap())? as u8;
        let z = self.parse_number(parts.next().unwrap())? as u8;
        Ok(MMixInstruction::TRAP(x, y, z))
    }

    // Helper: parse instruction with format (reg, reg, imm)
    fn parse_rri<F>(
        &self,
        pair: pest::iterators::Pair<Rule>,
        f: F,
    ) -> Result<MMixInstruction, String>
    where
        F: FnOnce(u8, u8, u8) -> MMixInstruction,
    {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;
        let z = self.parse_number(ops.next().unwrap())? as u8;
        Ok(f(x, y, z))
    }

    // PUSHJ/PUSHJB: format (reg, imm) where imm is 16-bit offset
    fn parse_inst_pushj(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let (line, col) = pair.line_col();
        let line = self.original_line(line).unwrap_or(line);
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operand = parts.next().unwrap();
        let mut ops = operand.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let addr = self.parse_number(ops.next().unwrap())?;
        let resolved = self.relative_field("PUSHJ", addr, 16, (line, col), "")?;
        let y = (resolved.field >> 8) as u8;
        let z = (resolved.field & 0xFF) as u8;
        Ok(if resolved.backward {
            MMixInstruction::PUSHJB(x, y, z)
        } else {
            MMixInstruction::PUSHJ(x, y, z)
        })
    }

    fn parse_inst_pushjb(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let (line, col) = pair.line_col();
        let line = self.original_line(line).unwrap_or(line);
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let operand = parts.next().unwrap();
        let mut ops = operand.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let addr = self.parse_number(ops.next().unwrap())?;
        let resolved = self.relative_field("PUSHJB", addr, 16, (line, col), "")?;
        let y = (resolved.field >> 8) as u8;
        let z = (resolved.field & 0xFF) as u8;
        Ok(MMixInstruction::PUSHJB(x, y, z))
    }

    fn parse_inst_go_auto(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap().as_str().to_uppercase();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;
        let z = self.lower_z_operand(ops.next().unwrap(), &mnem)?;

        match (mnem.as_str(), z) {
            ("GO", ZForm::Reg(z)) => Ok(MMixInstruction::GO(x, y, z)),
            ("GO", ZForm::Imm(z)) => Ok(MMixInstruction::GOI(x, y, z)),
            ("PUSHGO", ZForm::Reg(z)) => Ok(MMixInstruction::PUSHGO(x, y, z)),
            ("PUSHGO", ZForm::Imm(z)) => Ok(MMixInstruction::PUSHGOI(x, y, z)),
            _ => Err(format!("Unknown GO instruction: {}", mnem)),
        }
    }

    fn parse_inst_pushgo_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        self.parse_rri(pair, MMixInstruction::PUSHGOI)
    }

    fn parse_inst_pop(&self, pair: pest::iterators::Pair<Rule>) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let x = self.parse_number(parts.next().unwrap())? as u8;
        let yz = self.parse_number(parts.next().unwrap())? as u16;
        let y = ((yz >> 8) & 0xFF) as u8;
        let z = (yz & 0xFF) as u8;
        Ok(MMixInstruction::POP(x, y, z))
    }

    fn parse_inst_go_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        self.parse_rri(pair, MMixInstruction::GOI)
    }

    fn parse_inst_get(&self, pair: pest::iterators::Pair<Rule>) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let x = self.parse_register(parts.next().unwrap())?;
        // comma is silent in grammar, not in parts
        let z = self.parse_number(parts.next().unwrap())? as u8;
        Ok(MMixInstruction::GET(x, z))
    }

    fn parse_inst_put_auto(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let x = self.parse_number(parts.next().unwrap())? as u8;
        // comma is silent in grammar, not in parts
        match self.lower_z_operand(parts.next().unwrap(), "PUT")? {
            ZForm::Reg(z) => Ok(MMixInstruction::PUT(x, z)),
            ZForm::Imm(z) => Ok(MMixInstruction::PUTI(x, z)),
        }
    }

    fn parse_inst_puti(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let x = self.parse_number(parts.next().unwrap())? as u8;
        // comma is silent in grammar, not in parts
        let z = self.parse_number(parts.next().unwrap())? as u8;
        Ok(MMixInstruction::PUTI(x, z))
    }

    fn parse_inst_save(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let x_pair = parts.next().ok_or("Missing X register in SAVE")?;
        let x = self.parse_register(x_pair)?;
        let z_pair = parts.next().ok_or("Missing Z value in SAVE")?;
        let z = self.parse_number(z_pair)? as u8;
        Ok(MMixInstruction::SAVE(x, z))
    }

    fn parse_inst_unsave(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let x_pair = parts.next().ok_or("Missing X value in UNSAVE")?;
        let x = self.parse_number(x_pair)? as u8;
        let z_pair = parts.next().ok_or("Missing Z register in UNSAVE")?;
        let z = self.parse_register(z_pair)?;
        Ok(MMixInstruction::UNSAVE(x, z))
    }

    fn parse_inst_ldunc_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        self.parse_rri(pair, MMixInstruction::LDUNCI)
    }

    fn parse_inst_stunc_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        self.parse_rri(pair, MMixInstruction::STUNCI)
    }

    fn parse_inst_ldht_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        self.parse_rri(pair, MMixInstruction::LDHTI)
    }

    fn parse_inst_stht_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        self.parse_rri(pair, MMixInstruction::STHTI)
    }

    fn parse_inst_ldsf_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        self.parse_rri(pair, MMixInstruction::LDSFI)
    }

    fn parse_inst_stsf_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        self.parse_rri(pair, MMixInstruction::STSFI)
    }

    fn parse_inst_ldvts_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        self.parse_rri(pair, MMixInstruction::LDVTSI)
    }

    fn parse_inst_cswap_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        self.parse_rri(pair, MMixInstruction::CSWAPI)
    }

    fn parse_inst_stco_auto(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let x = self.parse_number(parts.next().unwrap())? as u8;
        // comma is silent in grammar, not in parts
        let y = self.parse_register(parts.next().unwrap())?;
        match self.lower_z_operand(parts.next().unwrap(), "STCO")? {
            ZForm::Reg(z) => Ok(MMixInstruction::STCO(x, y, z)),
            ZForm::Imm(z) => Ok(MMixInstruction::STCOI(x, y, z)),
        }
    }

    fn parse_inst_stco_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let x = self.parse_number(parts.next().unwrap())? as u8;
        // comma is silent in grammar, not in parts
        let y = self.parse_register(parts.next().unwrap())?;
        let z = self.parse_number(parts.next().unwrap())? as u8;
        Ok(MMixInstruction::STCOI(x, y, z))
    }

    fn parse_inst_cache_auto(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let mnem = parts.next().unwrap().as_str().to_uppercase();
        let operands = parts.next().unwrap();
        let mut ops = operands.into_inner();
        let x = self.parse_register(ops.next().unwrap())?;
        let y = self.parse_register(ops.next().unwrap())?;
        let z = self.lower_z_operand(ops.next().unwrap(), &mnem)?;

        match (mnem.as_str(), z) {
            ("PRELD", ZForm::Reg(z)) => Ok(MMixInstruction::PRELD(x, y, z)),
            ("PRELD", ZForm::Imm(z)) => Ok(MMixInstruction::PRELDI(x, y, z)),
            ("PREGO", ZForm::Reg(z)) => Ok(MMixInstruction::PREGO(x, y, z)),
            ("PREGO", ZForm::Imm(z)) => Ok(MMixInstruction::PREGOI(x, y, z)),
            ("PREST", ZForm::Reg(z)) => Ok(MMixInstruction::PREST(x, y, z)),
            ("PREST", ZForm::Imm(z)) => Ok(MMixInstruction::PRESTI(x, y, z)),
            ("SYNCD", ZForm::Reg(z)) => Ok(MMixInstruction::SYNCD(x, y, z)),
            ("SYNCD", ZForm::Imm(z)) => Ok(MMixInstruction::SYNCDI(x, y, z)),
            ("SYNCID", ZForm::Reg(z)) => Ok(MMixInstruction::SYNCID(x, y, z)),
            ("SYNCID", ZForm::Imm(z)) => Ok(MMixInstruction::SYNCIDI(x, y, z)),
            _ => Err(format!("Unknown cache control instruction: {}", mnem)),
        }
    }

    fn parse_inst_preld_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        self.parse_rri(pair, MMixInstruction::PRELDI)
    }

    fn parse_inst_prego_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        self.parse_rri(pair, MMixInstruction::PREGOI)
    }

    fn parse_inst_prest_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        self.parse_rri(pair, MMixInstruction::PRESTI)
    }

    fn parse_inst_syncd_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        self.parse_rri(pair, MMixInstruction::SYNCDI)
    }

    fn parse_inst_syncid_rri(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        self.parse_rri(pair, MMixInstruction::SYNCIDI)
    }

    fn parse_inst_resume(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let xyz = self.parse_number(parts.next().unwrap())? as u8;
        Ok(MMixInstruction::RESUME(xyz))
    }

    fn parse_inst_trip(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let x = self.parse_number(parts.next().unwrap())? as u8;
        let y = self.parse_number(parts.next().unwrap())? as u8;
        let z = self.parse_number(parts.next().unwrap())? as u8;
        Ok(MMixInstruction::TRIP(x, y, z))
    }

    /// The operand group is all or nothing; a bare `SWYM` carries 0,0,0.
    fn parse_inst_swym(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let (x, y, z) = match parts.next() {
            Some(first) => (
                self.parse_number(first)? as u8,
                self.parse_number(parts.next().unwrap())? as u8,
                self.parse_number(parts.next().unwrap())? as u8,
            ),
            None => (0, 0, 0),
        };
        Ok(MMixInstruction::SWYM(x, y, z))
    }

    fn parse_inst_sync(
        &self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<MMixInstruction, String> {
        let mut parts = pair.into_inner();
        let _mnem = parts.next();
        let xyz = self.parse_number(parts.next().unwrap())? as u8;
        Ok(MMixInstruction::SYNC(xyz))
    }

    /// Build the data unit a directive assembles from one value, truncating
    /// to the directive's unit width.
    fn data_directive_unit(directive_kind: Rule, value: u64) -> Result<MMixInstruction, String> {
        match directive_kind {
            Rule::directive_byte => Ok(MMixInstruction::BYTE(value as u8)),
            Rule::directive_wyde => Ok(MMixInstruction::WYDE(value as u16)),
            Rule::directive_tetra => Ok(MMixInstruction::TETRA(value as u32)),
            Rule::directive_octa => Ok(MMixInstruction::OCTA(value)),
            _ => Err(format!("Unknown data directive: {:?}", directive_kind)),
        }
    }

    /// Parse a data directive and expand its value list to one instruction
    /// per unit (e.g. `BYTE "Hello"` becomes five `BYTE` instructions).
    fn parse_data_directive(
        &mut self,
        pair: pest::iterators::Pair<Rule>,
    ) -> Result<Vec<MMixInstruction>, String> {
        let mut parts = pair.into_inner();
        let directive_kind = parts.next().unwrap().as_rule();
        let values_pair = parts.next().unwrap();

        let mut result = Vec::new();
        for value in values_pair.into_inner() {
            let actual_value = value.into_inner().next().unwrap(); // string_literal or expr_value

            if actual_value.as_rule() == Rule::string_literal {
                let s = actual_value.as_str();
                let s = &s[1..s.len() - 1]; // Remove quotes
                for b in Self::decode_byte_string(s) {
                    result.push(Self::data_directive_unit(directive_kind, b as u64)?);
                }
            } else {
                let val = self.parse_number(actual_value)?;
                result.push(Self::data_directive_unit(directive_kind, val)?);
            }
        }
        Ok(result)
    }

    fn parse_loc_directive(&mut self, pair: pest::iterators::Pair<Rule>) -> Result<(), String> {
        let mut parts = pair.into_inner();
        let _directive = parts.next(); // Skip "LOC" keyword
        let addr = self.parse_number(parts.next().unwrap())?;
        self.current_addr = addr;
        Ok(())
    }

    fn parse_is_directive(
        &mut self,
        pair: pest::iterators::Pair<Rule>,
        checking: bool,
    ) -> Result<(), String> {
        let mut parts = pair.into_inner();
        let lhs = parts.next().unwrap();
        let (line, _) = lhs.line_col();
        let line = self.original_line(line).unwrap_or(line);
        let raw_name = lhs.as_str().to_string();
        let _is_keyword = parts.next(); // Skip "IS" keyword
        let value_pair = parts.next().unwrap();

        let symbol_type = match value_pair.as_rule() {
            Rule::register => {
                let reg = self.parse_register(value_pair)?;
                SymbolType::Register(reg)
            }
            Rule::expr_value => {
                let value = self.parse_number(value_pair)?;
                SymbolType::Constant(value)
            }
            _ => return Err("IS directive requires register or expr_value".to_string()),
        };

        if checking {
            self.define_symbol(&raw_name, symbol_type, line)?;
        } else {
            let qualified = self.qualify_name(&raw_name);
            self.symbols.insert(qualified, symbol_type);
        }
        Ok(())
    }

    fn parse_prefix_directive(&mut self, pair: pest::iterators::Pair<Rule>) {
        let mut parts = pair.into_inner();
        let _directive = parts.next(); // Skip "PREFIX" keyword
        let arg = parts.next().expect("prefix_arg required by grammar");
        self.current_prefix = arg.as_str().to_string();
    }

    /// Resolve the Z operand of a base mnemonic (auto-immediate path) into
    /// either a register reference or an 8-bit immediate. The grammar allows Z
    /// to be a `register` (which itself may be `$N` or a bare symbol that
    /// could be a register alias *or* a constant) or an `expr_value` (literal
    /// or symbol). Bare symbols are resolved against the symbol and label
    /// tables; numeric values are range-checked against `0..=255`.
    fn lower_z_operand(
        &self,
        pair: pest::iterators::Pair<Rule>,
        mnem: &str,
    ) -> Result<ZForm, String> {
        let (line, col) = pair.line_col();
        let line = self.original_line(line).unwrap_or(line);
        match pair.as_rule() {
            Rule::register => {
                let inner = pair
                    .clone()
                    .into_inner()
                    .next()
                    .expect("register rule has at least one child");
                match inner.as_rule() {
                    Rule::register_num => {
                        let n = self.parse_register(pair)?;
                        Ok(ZForm::Reg(n))
                    }
                    Rule::symbol => {
                        let raw = inner.as_str();
                        let qualified = self.qualify_name(raw);
                        if let Some(&sym) = self.symbols.get(&qualified) {
                            match sym {
                                SymbolType::Register(r) => Ok(ZForm::Reg(r)),
                                SymbolType::Constant(v) => self.imm_in_range(v, mnem, line, col),
                            }
                        } else if let Some(&addr) = self.labels.get(&qualified) {
                            self.imm_in_range(addr, mnem, line, col)
                        } else {
                            Err(format!(
                                "{}:{}:{}: Undefined symbol '{}' in third operand of {}",
                                self.current_filename, line, col, qualified, mnem
                            ))
                        }
                    }
                    other => Err(format!(
                        "{}:{}:{}: Unexpected register inner rule {:?} for {}",
                        self.current_filename, line, col, other, mnem
                    )),
                }
            }
            Rule::expr_value => {
                let v = self.parse_number(pair)?;
                self.imm_in_range(v, mnem, line, col)
            }
            other => Err(format!(
                "{}:{}:{}: Unexpected Z operand rule {:?} for {}",
                self.current_filename, line, col, other, mnem
            )),
        }
    }

    /// Range-check a resolved value as an 8-bit immediate operand (0..=255).
    fn imm_byte(&self, v: u64, mnem: &str, line: usize, col: usize) -> Result<u8, String> {
        if v <= 0xFF {
            Ok(v as u8)
        } else {
            Err(format!(
                "{}:{}:{}: immediate operand {} out of range 0..255 for {}",
                self.current_filename, line, col, v, mnem
            ))
        }
    }

    /// Range-check a resolved Z value as an 8-bit immediate (0..=255).
    fn imm_in_range(&self, v: u64, mnem: &str, line: usize, col: usize) -> Result<ZForm, String> {
        self.imm_byte(v, mnem, line, col).map(ZForm::Imm)
    }

    fn parse_register(&self, pair: pest::iterators::Pair<Rule>) -> Result<u8, String> {
        let (line, col) = pair.line_col();
        let line = self.original_line(line).unwrap_or(line);

        // If the pair is a `register` rule, it might have an inner rule (register_num or symbol)
        let text = if pair.as_rule() == Rule::register {
            // Check if it has children (symbol case)
            if let Some(inner) = pair.clone().into_inner().next() {
                inner.as_str()
            } else {
                pair.as_str()
            }
        } else {
            pair.as_str()
        };

        // Check if it's a symbolic name from IS directive
        if !text.starts_with('$') {
            let qualified = self.qualify_name(text);
            if let Some(&symbol_type) = self.symbols.get(&qualified) {
                match symbol_type {
                    SymbolType::Register(reg) => return Ok(reg),
                    SymbolType::Constant(value) => {
                        return Err(format!(
                            "{}:{}:{}: Symbol '{}' is a numeric constant ({}), cannot use as register",
                            self.current_filename, line, col, qualified, value
                        ));
                    }
                }
            }
            return Err(format!(
                "{}:{}:{}: Undefined symbol '{}' (expected register like $0 or register alias)",
                self.current_filename, line, col, qualified
            ));
        }

        text[1..]
            .parse::<u8>()
            .map_err(|e| format!("Line {}:{}: Invalid register number: {}", line, col, e))
    }

    fn parse_number(&self, pair: pest::iterators::Pair<Rule>) -> Result<u64, String> {
        let rule = pair.as_rule();
        let (line, col) = pair.line_col();
        let line = self.original_line(line).unwrap_or(line);

        // Handle container rules that have children
        if rule == Rule::expr_value || rule == Rule::number_literal || rule == Rule::operand_imm {
            let inner = pair.into_inner().next().unwrap();
            return self.parse_number(inner);
        }

        // For atomic rules, use the text directly
        let text = pair.as_str();

        match rule {
            Rule::at_symbol => {
                // @ represents the current location
                Ok(self.current_addr)
            }
            Rule::signed_number_literal => {
                // Unary minus applied to a numeric literal
                let mut inner = pair.into_inner();
                let unsigned = self.parse_number(inner.next().unwrap())?;
                let signed = -(unsigned as i128);
                Ok(signed as u64)
            }
            Rule::char_literal => {
                // Single-byte character literal with minimal escapes
                let inner = &text[1..text.len() - 1];
                let ch = if let Some(rest) = inner.strip_prefix('\\') {
                    match rest {
                        "n" => '\n',
                        "r" => '\r',
                        "t" => '\t',
                        "0" => '\0',
                        "\\" => '\\',
                        "'" => '\'',
                        _ => {
                            return Err(format!(
                                "Line {}:{}: Unsupported escape in char literal: \\{}",
                                line, col, rest
                            ));
                        }
                    }
                } else {
                    if inner.chars().count() != 1 {
                        return Err(format!(
                            "Line {}:{}: Invalid char literal (must be one byte): '{}'",
                            line, col, inner
                        ));
                    }
                    inner.chars().next().unwrap()
                };

                if !ch.is_ascii() {
                    return Err(format!(
                        "Line {}:{}: Char literal must be ASCII byte, got {:?}",
                        line, col, ch
                    ));
                }
                Ok(ch as u8 as u64)
            }
            Rule::hex_literal => {
                // Support both # and 0x/0X prefixes
                let hex_str = if let Some(stripped) = text.strip_prefix('#') {
                    stripped
                } else if let Some(stripped) =
                    text.strip_prefix("0x").or_else(|| text.strip_prefix("0X"))
                {
                    stripped
                } else {
                    text
                };
                u64::from_str_radix(hex_str, 16)
                    .map_err(|e| format!("Line {}:{}: Invalid hex number: {}", line, col, e))
            }
            Rule::oct_literal => u64::from_str_radix(&text[1..], 8)
                .map_err(|e| format!("Line {}:{}: Invalid octal number: {}", line, col, e)),
            Rule::dec_literal => text
                .parse::<u64>()
                .map_err(|e| format!("Line {}:{}: Invalid decimal number: {}", line, col, e)),
            Rule::symbol | Rule::identifier | Rule::global_id => {
                let qualified = self.qualify_name(text);
                if let Some(&symbol_type) = self.symbols.get(&qualified) {
                    match symbol_type {
                        SymbolType::Constant(value) => Ok(value),
                        SymbolType::Register(reg) => Err(format!(
                            "{}:{}:{}: Symbol '{}' is a register alias (${}), cannot use as immediate value",
                            self.current_filename, line, col, qualified, reg
                        )),
                    }
                } else if let Some(&label_addr) = self.labels.get(&qualified) {
                    Ok(label_addr)
                } else {
                    Err(format!(
                        "{}:{}:{}: Undefined symbol: {}",
                        self.current_filename, line, col, qualified
                    ))
                }
            }
            _ => Err(format!(
                "Line {}:{}: Expected number, got: {:?}",
                line, col, rule
            )),
        }
    }

    /// Every instruction occupies a tetra-aligned slot, including the
    /// pseudo-instructions `instruction_size` reports as wider than one tetra.
    /// Alignment is not the emitted size.
    const INSTRUCTION_ALIGNMENT: u64 = 4;

    fn instruction_size(inst: &MMixInstruction) -> u64 {
        match inst {
            MMixInstruction::SET(_, _) => 16,
            MMixInstruction::SETRR(_, _) => 4, // ORI $X, $Y, 0
            MMixInstruction::BYTE(_) => 1,
            MMixInstruction::WYDE(_) => 2,
            MMixInstruction::TETRA(_) => 4,
            MMixInstruction::OCTA(_) => 8,
            _ => 4,
        }
    }

    /// Encode a single instruction into bytes using the shared encode module
    pub fn encode_instruction_bytes(&self, instruction: &MMixInstruction) -> Vec<u8> {
        crate::encode::encode_instruction_bytes(instruction)
    }

    /// Generate object code in MMO format
    pub fn generate_object_code(&self) -> Vec<u8> {
        crate::mmo::MmoGenerator::new(self.instructions.clone(), self.labels.clone()).generate()
    }

    /// The original source location of the code at `addr`, or `None` for
    /// compiler-generated code (e.g. the appended debug-subroutine block) or
    /// an address no statement emitted.
    ///
    /// `addr` need not be an entry address: an address inside a multi-tetra
    /// expansion resolves to the statement that emitted it. Each entry
    /// covers exactly the bytes its own item emitted, so an address past the
    /// end of a run maps to nothing -- the gap between the text and data
    /// segments, and the generated block after the last user statement, both
    /// stay unmapped.
    pub fn source_loc(&self, addr: u64) -> Option<&SourceLoc> {
        let (&start, loc) = self.debug_info.range(..=addr).next_back()?;
        (addr - start < self.emitted_size(start)?).then_some(loc)
    }

    /// The byte extent of the item emitted at `addr`, or `None` if no item
    /// starts there.
    fn emitted_size(&self, addr: u64) -> Option<u64> {
        self.instructions
            .iter()
            .find(|(at, _)| *at == addr)
            .map(|(_, inst)| Self::instruction_size(inst))
    }

    /// The lowest instruction address whose source location is `(file,
    /// line)`, or `None` if that line produced no code. Exact-line only.
    ///
    /// If `file` was passed as more than one translation unit (a duplicate
    /// input filename), this still matches by string equality against
    /// whichever unit(s) produced code at that line -- a documented,
    /// deterministic limitation for the pathological duplicate-filename
    /// case; the address returned is always the lowest that matches.
    pub fn addr_for_line(&self, file: &str, line: usize) -> Option<u64> {
        self.debug_info
            .iter()
            .find(|(_, loc)| loc.file == file && loc.line == line)
            .map(|(&addr, _)| addr)
    }

    /// The original (un-preprocessed) text of `file`'s 1-based `line`,
    /// without the trailing newline, or `None` past end-of-file or for an
    /// unknown file. If `file` was passed more than once, resolves to the
    /// FIRST translation unit with that name in command-line order.
    pub fn source_text(&self, file: &str, line: usize) -> Option<&str> {
        let unit = self.sources.iter().find(|u| u.filename == file)?;
        let index = line.checked_sub(1)?;
        unit.original.lines().nth(index)
    }

    /// Expand `INCLUDE <file>` directives into an ordered list of translation
    /// units, ready to feed to `new`/`add_source`. Host files are split at
    /// each `INCLUDE` into segments (each tagged with the host's filename and
    /// blank-padded to keep absolute line numbers); each included file is
    /// resolved recursively and its units inserted at that position. Paths
    /// resolve relative to the including file's directory. `read` supplies
    /// file contents -- injected so this logic is testable without real
    /// filesystem access and reusable by any frontend. A cycle (re-entry on
    /// the current include chain) or an unreadable file is an `Err`.
    pub fn resolve_includes<R>(
        root_source: &str,
        root_filename: &str,
        base_dir: &Path,
        read: &R,
    ) -> Result<Vec<(String, String)>, String>
    where
        R: Fn(&Path) -> std::io::Result<String>,
    {
        let mut chain = Vec::new();
        Self::resolve_includes_chain(root_source, root_filename, base_dir, read, &mut chain)
    }

    /// Recursive worker behind `resolve_includes`. `chain` holds the
    /// lexically-normalized identity of every file currently being expanded
    /// (the ancestors on the path from the top-level call to here), used to
    /// detect a file re-entering itself before it finishes expanding.
    fn resolve_includes_chain<R>(
        root_source: &str,
        root_filename: &str,
        base_dir: &Path,
        read: &R,
        chain: &mut Vec<PathBuf>,
    ) -> Result<Vec<(String, String)>, String>
    where
        R: Fn(&Path) -> std::io::Result<String>,
    {
        let mut units = Vec::new();
        let mut segment = String::new();
        let mut segment_start_line: usize = 1;
        let mut current_line: usize = 0;

        for raw_line in root_source.split_inclusive('\n') {
            current_line += 1;
            let content = raw_line.strip_suffix('\n').unwrap_or(raw_line);
            let Some(operand) = Self::parse_include_operand(content) else {
                segment.push_str(raw_line);
                continue;
            };

            if !segment.trim().is_empty() {
                units.push((
                    root_filename.to_string(),
                    Self::pad_source(&segment, segment_start_line),
                ));
            }
            segment.clear();

            let target = Self::normalize_lexically(&base_dir.join(&operand));
            if chain.contains(&target) {
                let mut names: Vec<String> =
                    chain.iter().map(|p| p.display().to_string()).collect();
                names.push(target.display().to_string());
                return Err(format!("include cycle detected: {}", names.join(" -> ")));
            }

            let included_source = read(&target).map_err(|err| {
                format!("cannot read included file '{}': {}", target.display(), err)
            })?;
            let included_filename = target.display().to_string();
            let included_base_dir = target
                .parent()
                .map(Path::to_path_buf)
                .unwrap_or_else(|| PathBuf::from(""));

            chain.push(target);
            let included_units = Self::resolve_includes_chain(
                &included_source,
                &included_filename,
                &included_base_dir,
                read,
                chain,
            )?;
            chain.pop();
            units.extend(included_units);

            segment_start_line = current_line + 1;
        }

        if !segment.trim().is_empty() {
            units.push((
                root_filename.to_string(),
                Self::pad_source(&segment, segment_start_line),
            ));
        }

        Ok(units)
    }

    /// If `line`, after stripping a trailing `;`/`%` comment and trimming
    /// whitespace, is an `INCLUDE`/`.INCLUDE` directive (case-insensitive),
    /// returns its operand (unquoted if wrapped in matching double quotes).
    fn parse_include_operand(line: &str) -> Option<String> {
        let without_comment = match line.find([';', '%']) {
            Some(idx) => &line[..idx],
            None => line,
        };
        let trimmed = without_comment.trim();
        let mut parts = trimmed.splitn(2, |c: char| c.is_whitespace());
        let keyword = parts.next()?;
        if !keyword
            .trim_start_matches('.')
            .eq_ignore_ascii_case("include")
        {
            return None;
        }
        let operand = parts.next().unwrap_or("").trim();
        if operand.is_empty() {
            return None;
        }
        let unquoted = if operand.len() >= 2 && operand.starts_with('"') && operand.ends_with('"') {
            &operand[1..operand.len() - 1]
        } else {
            operand
        };
        Some(unquoted.to_string())
    }

    /// Prepend `start_line - 1` newlines to `text` so absolute line numbers
    /// survive being embedded at `start_line` of some larger file (the
    /// grammar ignores leading blank lines).
    fn pad_source(text: &str, start_line: usize) -> String {
        let padding = start_line.saturating_sub(1);
        let mut padded = String::with_capacity(text.len() + padding);
        for _ in 0..padding {
            padded.push('\n');
        }
        padded.push_str(text);
        padded
    }

    /// Lexically collapse `.`/`..` components without touching the
    /// filesystem (unlike `fs::canonicalize`, which would defeat the
    /// injected reader in unit tests and can fail on a nonexistent path).
    fn normalize_lexically(path: &Path) -> PathBuf {
        use std::path::Component;

        let mut result = PathBuf::new();
        for component in path.components() {
            match component {
                Component::CurDir => {}
                Component::ParentDir => {
                    if !result.pop() {
                        result.push("..");
                    }
                }
                other => result.push(other.as_os_str()),
            }
        }
        result
    }
}

// Keep all the existing tests - they should work unchanged
#[cfg(test)]
mod tests {
    use super::*;

    // ---- Mnemonic word-boundary guard (adversarial) ------------------
    // Every `mnemonic_*` and `directive_*` rule closes with the shared
    // `word_end` rule: a keyword ends where a symbol could not continue, so a
    // short mnemonic's literal cannot match as a bare prefix of a longer one.
    // `Rule::parse` doesn't require consuming the whole input, so without the
    // guard each of these three calls returns `Ok` (the rule matches only its
    // own shorter literal and stops); with it each must return `Err`.

    #[test]
    fn test_mnemonic_boundary_guard_rejects_prefix_match() {
        use pest::Parser;

        // GET is a literal prefix of GETA/GETAB (the flagged pair).
        assert!(
            MMixalParser::parse(Rule::mnemonic_get, "GETA").is_err(),
            "mnemonic_get must not match a bare prefix of GETA"
        );
        // SET is a literal prefix of SETL/SETH/SETMH/SETML.
        assert!(
            MMixalParser::parse(Rule::mnemonic_set, "SETL").is_err(),
            "mnemonic_set must not match a bare prefix of SETL"
        );
        // SYNC is a literal prefix of SYNCD/SYNCID/SYNCDI/SYNCIDI.
        assert!(
            MMixalParser::parse(Rule::mnemonic_sync, "SYNCD").is_err(),
            "mnemonic_sync must not match a bare prefix of SYNCD"
        );
    }

    // ---- Mnemonic word-boundary guard: whitespace-adjacency behavior -
    // The guard has two known, intentional side effects on whitespace-
    // adjacent constructs. Both are real behavior changes, tested in
    // both directions here rather than left to surface only as an
    // unexplained corpus diff.

    #[test]
    fn test_boundary_guard_rejects_zero_whitespace_before_operand() {
        // `ADDa,b,c` (no space between the mnemonic and its first operand)
        // parsed as ADD with the three IS-aliased register operands before
        // this guard -- an accident of the grammar's implicit whitespace,
        // never legitimate MMIXAL syntax. `ADDa` fails `word_end` ('a' could
        // continue a symbol) and the line is a syntax error. A two-operand
        // ADD is invalid on both sides of this change for unrelated reasons,
        // so the repro must keep all three real, IS-aliased operands.
        let source = "a IS $1\nb IS $2\nc IS $3\nMain ADDa,b,c";
        let mut asm = MMixAssembler::new(source, "<test>");
        assert!(
            asm.parse().is_err(),
            "ADDa,b,c must be rejected now that the mnemonic requires a \
             word boundary before its operand"
        );
    }

    #[test]
    fn test_boundary_guard_accepts_mnemonic_prefixed_label() {
        // `HaltLoop` immediately followed by more source used to fail to
        // parse as a label: unguarded `mnemonic_halt` greedily matched the
        // "Halt" prefix of "HaltLoop" as a complete zero-operand HALT
        // instruction before the grammar ever tried `label_def`, leaving an
        // unparseable "Loop  ADD $1,$2,$3" remainder. After the guard,
        // "Halt" immediately followed by 'L' (alphanumeric) fails the
        // boundary check, `instruction` no longer matches at that position,
        // and `label_def` correctly claims `HaltLoop` as a label.
        let source = "HaltLoop  ADD $1,$2,$3\n  HALT";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse()
            .unwrap_or_else(|e| panic!("failed to parse {source:?}: {e}"));
        assert_eq!(
            asm.labels.get("HaltLoop"),
            Some(&0),
            "HaltLoop must resolve to address 0"
        );
    }

    #[test]
    fn test_keyword_boundary_admits_underscore_in_label() {
        // A symbol continues on '_', so a keyword must not end before one:
        // `Halt_Loop` is a label, not HALT trailing garbage. These cover the
        // three shapes that misparsed -- an operand-less mnemonic, a mnemonic
        // whose operand would absorb the tail, and a directive.
        let source = "Halt_Loop SETL $1,1\n\
                      Swym_x SETL $2,2\n\
                      Resume_x SETL $3,3\n\
                      Loc_Start SETL $4,4\n\
                      Greg_Base SETL $5,5\n";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse()
            .unwrap_or_else(|e| panic!("failed to parse {source:?}: {e}"));
        for (name, address) in [
            ("Halt_Loop", 0u64),
            ("Swym_x", 4),
            ("Resume_x", 8),
            ("Loc_Start", 12),
            ("Greg_Base", 16),
        ] {
            assert_eq!(
                asm.labels.get(name),
                Some(&address),
                "{name} must be claimed as a label at {address}"
            );
        }
    }

    #[test]
    fn test_swym_carries_its_operands() {
        let source = "SWYM 1,2,3\nSWYM";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse()
            .unwrap_or_else(|e| panic!("failed to parse {source:?}: {e}"));
        assert_eq!(asm.instructions.len(), 2, "both SWYM forms must assemble");
        assert_eq!(asm.instructions[0].1, MMixInstruction::SWYM(1, 2, 3));
        assert_eq!(asm.instructions[1].1, MMixInstruction::SWYM(0, 0, 0));
    }

    #[test]
    fn test_swym_rejects_a_partial_operand_list() {
        let mut asm = MMixAssembler::new("SWYM 1,2", "<test>");
        assert!(
            asm.parse().is_err(),
            "SWYM takes zero or three operands, never two"
        );
    }

    #[test]
    fn test_parse_simple_label() {
        let mut asm = MMixAssembler::new("LOOP: HALT", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.labels.get("LOOP"), Some(&0));
        assert_eq!(asm.instructions.len(), 1);
    }

    #[test]
    fn test_parse_octa_directive() {
        let mut asm = MMixAssembler::new("OCTA #123456789ABCDEF0", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions.len(), 1);
        assert_eq!(
            asm.instructions[0].1,
            MMixInstruction::OCTA(0x123456789ABCDEF0)
        );
    }

    #[test]
    fn test_parse_node_structure() {
        let mut asm = MMixAssembler::new("NODE: OCTA 42\n      OCTA 0", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.labels.get("NODE"), Some(&0));
        assert_eq!(asm.instructions.len(), 2);
    }

    #[test]
    fn test_parse_seti() {
        let mut asm = MMixAssembler::new("SETI $2, 10", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SET(2, 10));
    }

    #[test]
    fn test_parse_set_register() {
        let mut asm = MMixAssembler::new("SET $1, $7", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SETRR(1, 7));
    }

    #[test]
    fn test_parse_negative_literal_seti() {
        let mut asm = MMixAssembler::new("SETI $1, -1", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SET(1, u64::MAX));
    }

    #[test]
    fn test_parse_negative_literal_8bit_wrap() {
        let mut asm = MMixAssembler::new("ADDI $1, $2, -1", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::ADDI(1, 2, 0xFF));
    }

    #[test]
    fn test_decode_byte_string_decodes_escapes() {
        assert_eq!(
            MMixAssembler::decode_byte_string("a\\nb"),
            vec![b'a', b'\n', b'b']
        );
    }

    #[test]
    fn test_byte_escape_pass1_pass2_agree() {
        // count_string_bytes sizes the escape in pass 1 and decode_byte_string
        // expands it in pass 2; the two must agree. The forward OCTA reads
        // pass 1's counter, because pass 2 resolves it before reaching the
        // label and overwriting the entry; the emitted bytes read pass 2's.
        // The label sits on a BYTE so that no rounding can absorb a
        // disagreement between them.
        let mut asm = MMixAssembler::new("OCTA LABEL\nBYTE \"a\\nb\",0\nLABEL BYTE 7", "<test>");
        asm.parse().unwrap();
        let bytes: Vec<_> = asm.instructions[1..5]
            .iter()
            .map(|(addr, inst)| (*addr, inst.clone()))
            .collect();
        assert_eq!(
            bytes,
            vec![
                (8, MMixInstruction::BYTE(b'a')),
                (9, MMixInstruction::BYTE(b'\n')),
                (10, MMixInstruction::BYTE(b'b')),
                (11, MMixInstruction::BYTE(0)),
            ]
        );
        assert_eq!(asm.instructions[0].1, MMixInstruction::OCTA(12));
    }

    #[test]
    fn test_wyde_list_mixes_numbers_and_string_pass1_pass2_agree() {
        // A leading BYTE leaves the counter unaligned so List's WYDE must
        // round up. The forward OCTA reads pass 1's size for the list;
        // pass 2 must compute the same size or Next's address disagrees.
        let mut asm = MMixAssembler::new(
            "OCTA Next\nBYTE 1\nList WYDE 10,\"ab\",20\nNext BYTE 99",
            "<test>",
        );
        asm.parse().unwrap();
        assert_eq!(asm.labels.get("List"), Some(&10));
        let list: Vec<_> = asm.instructions[2..6]
            .iter()
            .map(|(addr, inst)| (*addr, inst.clone()))
            .collect();
        assert_eq!(
            list,
            vec![
                (10, MMixInstruction::WYDE(10)),
                (12, MMixInstruction::WYDE(b'a' as u16)),
                (14, MMixInstruction::WYDE(b'b' as u16)),
                (16, MMixInstruction::WYDE(20)),
            ]
        );
        assert_eq!(asm.labels.get("Next"), Some(&18));
        assert_eq!(asm.instructions[0].1, MMixInstruction::OCTA(18));
    }

    #[test]
    fn test_tetra_list_mixes_numbers_and_string_pass1_pass2_agree() {
        let mut asm = MMixAssembler::new(
            "OCTA Next\nBYTE 1\nList TETRA 10,\"ab\",20\nNext BYTE 99",
            "<test>",
        );
        asm.parse().unwrap();
        assert_eq!(asm.labels.get("List"), Some(&12));
        let list: Vec<_> = asm.instructions[2..6]
            .iter()
            .map(|(addr, inst)| (*addr, inst.clone()))
            .collect();
        assert_eq!(
            list,
            vec![
                (12, MMixInstruction::TETRA(10)),
                (16, MMixInstruction::TETRA(b'a' as u32)),
                (20, MMixInstruction::TETRA(b'b' as u32)),
                (24, MMixInstruction::TETRA(20)),
            ]
        );
        assert_eq!(asm.labels.get("Next"), Some(&28));
        assert_eq!(asm.instructions[0].1, MMixInstruction::OCTA(28));
    }

    #[test]
    fn test_octa_list_mixes_numbers_and_string_pass1_pass2_agree() {
        let mut asm = MMixAssembler::new(
            "OCTA Next\nBYTE 1\nList OCTA 10,\"ab\",20\nNext BYTE 99",
            "<test>",
        );
        asm.parse().unwrap();
        assert_eq!(asm.labels.get("List"), Some(&16));
        let list: Vec<_> = asm.instructions[2..6]
            .iter()
            .map(|(addr, inst)| (*addr, inst.clone()))
            .collect();
        assert_eq!(
            list,
            vec![
                (16, MMixInstruction::OCTA(10)),
                (24, MMixInstruction::OCTA(b'a' as u64)),
                (32, MMixInstruction::OCTA(b'b' as u64)),
                (40, MMixInstruction::OCTA(20)),
            ]
        );
        assert_eq!(asm.labels.get("Next"), Some(&48));
        assert_eq!(asm.instructions[0].1, MMixInstruction::OCTA(48));
    }

    #[test]
    fn test_byte_string_no_auto_terminator() {
        // MMIXAL appends no terminator to a BYTE string: "Hi" is two bytes and
        // nothing more.
        let mut asm = MMixAssembler::new("BYTE \"Hi\"", "<test>");
        asm.parse().unwrap();
        let bytes: Vec<_> = asm
            .instructions
            .iter()
            .map(|(addr, inst)| (*addr, inst.clone()))
            .collect();
        assert_eq!(
            bytes,
            vec![
                (0, MMixInstruction::BYTE(b'H')),
                (1, MMixInstruction::BYTE(b'i')),
            ]
        );
    }

    #[test]
    fn test_octa_label_rounds_up_after_byte() {
        // MMIXAL rounds the counter to the item's width before assembling it,
        // so the octabyte -- and the label on it -- lands at 8, not 1.
        let mut asm = MMixAssembler::new("BYTE 1\nDATA: OCTA 0", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.labels.get("DATA"), Some(&8));
    }

    #[test]
    fn test_wyde_and_tetra_labels_round_to_their_widths() {
        let mut asm = MMixAssembler::new("BYTE 1\nDATA: WYDE 0", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.labels.get("DATA"), Some(&2));

        let mut asm = MMixAssembler::new("BYTE 1\nDATA: TETRA 0", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.labels.get("DATA"), Some(&4));
    }

    #[test]
    fn test_instruction_label_rounds_up_after_byte() {
        // Instructions align to 4 like any tetra-wide item.
        let mut asm = MMixAssembler::new("BYTE 1\nCODE: HALT", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.labels.get("CODE"), Some(&4));
    }

    #[test]
    fn test_forward_reference_resolves_to_aligned_address() {
        // Pass 2 overwrites asm.labels with its own addresses, so a pass-1 and
        // pass-2 disagreement survives only in the operand pass 2 encoded from
        // the stale pass-1 entry. DATA rounds to 8, four tetras past the JMP's
        // two.
        let mut asm = MMixAssembler::new("JMP DATA\nBYTE 1\nDATA: OCTA 0", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::JMP(2));
    }

    #[test]
    fn test_two_debug_directives_assemble() {
        // preprocess_debug appends one subroutine per directive, each ending in
        // a BYTE string; the next subroutine's SAVE follows it directly. Without
        // instruction alignment the source assembles only when the first
        // string's length is 0 mod 4.
        let source = "        LOC     #100\nMain    debug \"one\"\n        debug \"two\"\n        TRAP    0,Halt,0\n";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse().unwrap();
    }

    #[test]
    fn test_multibyte_byte_string_is_not_aligned() {
        // Alignment comes from the item's kind, not its size: a four-byte BYTE
        // list is still placed wherever the counter stands. Deriving alignment
        // from data_directive_size would put TEXT at 4.
        let mut asm = MMixAssembler::new("BYTE 1\nTEXT: BYTE \"abcd\"", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.labels.get("TEXT"), Some(&1));
    }

    #[test]
    fn test_loc_sets_the_counter_exactly() {
        // LOC assigns the counter; it does not align. The next aligned item
        // rounds from wherever LOC left it.
        let mut asm = MMixAssembler::new("LOC #101\nHERE: BYTE 0", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.labels.get("HERE"), Some(&0x101));
    }

    #[test]
    fn test_standalone_label_line_is_not_rounded() {
        // Rounding happens when an item is assembled, not when a label is
        // defined alone, so a bare label line names an address up to 7 bytes
        // below the octabyte that follows it.
        let mut asm = MMixAssembler::new("BYTE 1\nDATA\nOCTA #FF", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.labels.get("DATA"), Some(&1));
        assert_eq!(
            asm.instructions
                .last()
                .map(|(addr, inst)| (*addr, inst.clone())),
            Some((8, MMixInstruction::OCTA(0xFF)))
        );
    }

    #[test]
    fn test_lda_rri_pass1_size_matches_pass2() {
        let mut asm = MMixAssembler::new("JMP LABEL\nLDA $1,$2,4\nLABEL: HALT", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::JMP(2));
    }

    #[test]
    fn test_branch_offset_beyond_i16_bytes_not_truncated() {
        // Byte delta between BZ (at addr 0) and LABEL (at addr 0x10000, i.e.
        // 65536 bytes forward) exceeds i16::MAX (32767), so casting the raw
        // byte delta to i16 before dividing by 4 would silently wrap.
        let source = "BZ $0,LABEL\nLOC #10000\nLABEL: HALT";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse().unwrap();
        let expected_offset = 0x10000i64 / 4;
        assert_eq!(
            asm.instructions[0].1,
            MMixInstruction::BZ(0, expected_offset as u16)
        );
    }

    #[test]
    fn test_jmp_backward_emits_jmpb() {
        // A JMP whose target is BEHIND the current instruction must assemble
        // to JMPB, whose 24-bit field is 2^24 - magnitude.
        let source = "LOC #100\nBACK: HALT\nJMP BACK";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse().unwrap();
        // JMP is at addr 0x104 (BACK's HALT is 4 bytes), target 0x100:
        // magnitude = (0x104 - 0x100) / 4 = 1, field = 0x1000000 - 1.
        assert_eq!(asm.instructions[1].1, MMixInstruction::JMPB(0xFFFFFF));
    }

    #[test]
    fn test_geta_offset_beyond_range_errors() {
        // Target is 65536 tetras forward, one past GETA's 0..=65535 reach.
        // Without the range check this source assembles to a wrapped field.
        let source = "GETA $0,LABEL\nLOC #40000\nLABEL: HALT";
        let mut asm = MMixAssembler::new(source, "<test>");
        let err = asm.parse().unwrap_err();
        assert!(err.contains("GETA"));
        assert!(err.contains("out of range"));
    }

    #[test]
    fn test_geta_misaligned_target_errors() {
        // A bare label line takes the counter unrounded, so LABEL names the
        // byte after the BYTE -- address 5, and 5 bytes forward of the GETA.
        let source = "GETA $0,LABEL\nBYTE 1\nLABEL\nOCTA 0";
        let mut asm = MMixAssembler::new(source, "<test>");
        let err = asm.parse().unwrap_err();
        assert!(err.contains("not 4-byte aligned"), "{err}");
    }

    #[test]
    fn test_geta_offset_within_range_succeeds() {
        // 65535 tetras forward is the last target GETA reaches.
        let source = "GETA $0,LABEL\nLOC #3FFFC\nLABEL: HALT";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse().unwrap();
        let MMixInstruction::GETA(_, y, z) = asm.instructions[0].1 else {
            panic!("expected GETA instruction");
        };
        let field = ((y as u16) << 8) | z as u16;
        assert_eq!(field, 65535);
    }

    #[test]
    fn test_getab_forward_target_errors() {
        // Target is FORWARD of the GETAB, which cannot be encoded at all
        // (GETAB is a backward-only unsigned magnitude). Under the unfixed
        // code this assembles successfully with a semantically inverted
        // encoding.
        let source = "GETAB $0,LABEL\nLOC #100\nLABEL: HALT";
        let mut asm = MMixAssembler::new(source, "<test>");
        assert!(asm.parse().is_err());
    }

    #[test]
    fn test_getab_backward_target_encodes_knuth_field() {
        // GETAB sits at addr 0x104 (BACK's HALT is 4 bytes), target 0x100:
        // magnitude = (0x104 - 0x100) / 4 = 1, field = 65536 - 1 = 0xFFFF.
        let source = "LOC #100\nBACK: HALT\nGETAB $0,BACK";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[1].1, MMixInstruction::GETAB(0, 0xFF, 0xFF));
    }

    #[test]
    fn test_geta_forward_reach_extends_past_i16() {
        // 32769 tetras forward is inside GETA's 0..=65535 reach and outside
        // the i16 range the old check enforced.
        let source = "GETA $0,LABEL\nLOC #20004\nLABEL: HALT";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::GETA(0, 0x80, 0x01));
    }

    #[test]
    fn test_forward_mnemonic_at_backward_target_emits_backward_sibling() {
        // MMIXAL picks the opcode from the sign of the displacement, so a BNP
        // one tetra behind itself becomes BNPB with field 65536 - 1.
        let source = "LOC #100\nBACK: HALT\nBNP $1,BACK";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[1].1, MMixInstruction::BNPB(1, 0xFFFF));
    }

    #[test]
    fn test_pushj_at_backward_target_emits_pushjb() {
        let source = "LOC #100\nBACK: HALT\nPUSHJ $1,BACK";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse().unwrap();
        assert_eq!(
            asm.instructions[1].1,
            MMixInstruction::PUSHJB(1, 0xFF, 0xFF)
        );
    }

    #[test]
    fn test_pbranch_at_backward_target_emits_knuth_field() {
        // parse_inst_pbranch is a separate function from parse_inst_branch and
        // needs its own coverage of both the auto-selection and the field.
        let source = "LOC #100\nBACK: HALT\nPBZ $1,BACK";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[1].1, MMixInstruction::PBZB(1, 0xFF, 0xFF));

        let explicit = "LOC #100\nBACK: HALT\nPBZB $1,BACK";
        let mut asm = MMixAssembler::new(explicit, "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[1].1, MMixInstruction::PBZB(1, 0xFF, 0xFF));
    }

    #[test]
    fn test_backward_mnemonic_at_forward_target_names_forward_sibling() {
        let source = "BZB $1,LABEL\nLABEL: HALT";
        let mut asm = MMixAssembler::new(source, "<test>");
        let err = asm.parse().unwrap_err();
        assert!(err.contains("BZB"), "{err}");
        assert!(err.contains("use BZ instead"), "{err}");
    }

    #[test]
    fn test_zero_displacement_takes_the_forward_opcode() {
        // Forward reaches 0..=65535 tetras and backward 1..=65536, so a
        // branch to itself is forward with an empty field.
        let source = "HERE: BZ $1,HERE";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::BZ(1, 0));
    }

    #[test]
    fn test_branch_backward_reaches_65536_tetras() {
        // A backward field of 0 means -65536 tetras, the far end of the reach.
        let source = "LOC #0\nBACK: HALT\nLOC #40000\nBZ $1,BACK";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[1].1, MMixInstruction::BZB(1, 0));
    }

    #[test]
    fn test_branch_beyond_reach_errors() {
        let forward = "BZ $1,LABEL\nLOC #40000\nLABEL: HALT";
        let mut asm = MMixAssembler::new(forward, "<test>");
        let err = asm.parse().unwrap_err();
        assert!(err.contains("out of range"), "{err}");

        let backward = "LOC #0\nBACK: HALT\nLOC #40004\nBZ $1,BACK";
        let mut asm = MMixAssembler::new(backward, "<test>");
        let err = asm.parse().unwrap_err();
        assert!(err.contains("out of range"), "{err}");
    }

    #[test]
    fn test_branch_misaligned_target_errors() {
        // LABEL is a bare label line on data: address 5, not a multiple of 4.
        let source = "BZ $1,LABEL\nBYTE 1\nLABEL\nOCTA 0";
        let mut asm = MMixAssembler::new(source, "<test>");
        let err = asm.parse().unwrap_err();
        assert!(err.contains("not 4-byte aligned"), "{err}");
    }

    #[test]
    fn test_jmp_misaligned_target_errors() {
        // LABEL is a bare label line on data: address 5, not a multiple of 4.
        let source = "JMP LABEL\nBYTE 1\nLABEL\nOCTA 0";
        let mut asm = MMixAssembler::new(source, "<test>");
        let err = asm.parse().unwrap_err();
        assert!(err.contains("not 4-byte aligned"), "{err}");
    }

    #[test]
    fn test_jmp_beyond_reach_errors() {
        // JMP's field is 24 bits: 0..=16777215 tetras forward, 1..=16777216
        // backward. Without the check the extra bits were masked away.
        let forward = "JMP LABEL\nLOC #4000000\nLABEL: HALT";
        let mut asm = MMixAssembler::new(forward, "<test>");
        let err = asm.parse().unwrap_err();
        assert!(err.contains("out of range"), "{err}");

        let backward = "LOC #0\nBACK: HALT\nLOC #4000004\nJMP BACK";
        let mut asm = MMixAssembler::new(backward, "<test>");
        let err = asm.parse().unwrap_err();
        assert!(err.contains("out of range"), "{err}");
    }

    #[test]
    fn test_incl_takes_a_16_bit_immediate() {
        // INCL adds YZ to $X, like its INCH/INCMH/INCML siblings.
        let mut asm = MMixAssembler::new("INCL $1,#203", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::INCL(1, 0x203));
    }

    #[test]
    fn test_parse_char_literal_immediate() {
        let mut asm = MMixAssembler::new("ANDI $1, $2, 'A'", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::ANDI(1, 2, 65));
    }

    #[test]
    fn test_parse_char_literal_escape_newline() {
        let mut asm = MMixAssembler::new("ANDI $1, $2, '\\n'", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::ANDI(1, 2, 10));
    }

    #[test]
    fn test_parse_char_literal_non_ascii_error() {
        let mut asm = MMixAssembler::new("ANDI $1, $2, 'Ā'", "<test>");
        assert!(asm.parse().is_err());
    }

    #[test]
    fn test_parse_char_literal_multi_char_error() {
        let mut asm = MMixAssembler::new("ANDI $1, $2, 'AB'", "<test>");
        assert!(asm.parse().is_err());
    }

    // Bitwise operation tests
    #[test]
    fn test_parse_and() {
        let mut asm = MMixAssembler::new("AND $1, $2, $3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::AND(1, 2, 3));
    }

    #[test]
    fn test_parse_andi() {
        let mut asm = MMixAssembler::new("ANDI $1, $2, #FF", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::ANDI(1, 2, 0xFF));
    }

    #[test]
    fn test_parse_or() {
        let mut asm = MMixAssembler::new("OR $10, $20, $30", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::OR(10, 20, 30));
    }

    #[test]
    fn test_parse_xor() {
        let mut asm = MMixAssembler::new("XOR $5, $6, $7", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::XOR(5, 6, 7));
    }

    #[test]
    fn test_parse_andn() {
        let mut asm = MMixAssembler::new("ANDN $1, $2, $3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::ANDN(1, 2, 3));
    }

    #[test]
    fn test_parse_nand() {
        let mut asm = MMixAssembler::new("NAND $1, $2, $3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::NAND(1, 2, 3));
    }

    #[test]
    fn test_parse_nor() {
        let mut asm = MMixAssembler::new("NOR $1, $2, $3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::NOR(1, 2, 3));
    }

    #[test]
    fn test_parse_nxor() {
        let mut asm = MMixAssembler::new("NXOR $1, $2, $3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::NXOR(1, 2, 3));
    }

    #[test]
    fn test_parse_mux() {
        let mut asm = MMixAssembler::new("MUX $1, $2, $3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::MUX(1, 2, 3));
    }

    // Bit fiddling operations tests
    #[test]
    fn test_parse_bdif() {
        let mut asm = MMixAssembler::new("BDIF $1, $2, $3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::BDIF(1, 2, 3));
    }

    #[test]
    fn test_parse_bdifi() {
        let mut asm = MMixAssembler::new("BDIFI $1, $2, #10", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::BDIFI(1, 2, 0x10));
    }

    #[test]
    fn test_parse_wdif() {
        let mut asm = MMixAssembler::new("WDIF $1, $2, $3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::WDIF(1, 2, 3));
    }

    #[test]
    fn test_parse_wdifi() {
        let mut asm = MMixAssembler::new("WDIFI $1, $2, 100", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::WDIFI(1, 2, 100));
    }

    #[test]
    fn test_parse_tdif() {
        let mut asm = MMixAssembler::new("TDIF $1, $2, $3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::TDIF(1, 2, 3));
    }

    #[test]
    fn test_parse_tdifi() {
        let mut asm = MMixAssembler::new("TDIFI $1, $2, 50", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::TDIFI(1, 2, 50));
    }

    #[test]
    fn test_parse_odif() {
        let mut asm = MMixAssembler::new("ODIF $1, $2, $3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::ODIF(1, 2, 3));
    }

    #[test]
    fn test_parse_odifi() {
        let mut asm = MMixAssembler::new("ODIFI $1, $2, 255", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::ODIFI(1, 2, 255));
    }

    #[test]
    fn test_parse_sadd() {
        let mut asm = MMixAssembler::new("SADD $1, $2, $3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SADD(1, 2, 3));
    }

    #[test]
    fn test_parse_saddi() {
        let mut asm = MMixAssembler::new("SADDI $1, $2, 0", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SADDI(1, 2, 0));
    }

    #[test]
    fn test_parse_mor() {
        let mut asm = MMixAssembler::new("MOR $1, $2, $3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::MOR(1, 2, 3));
    }

    #[test]
    fn test_parse_mori() {
        let mut asm = MMixAssembler::new("MORI $1, $2, 128", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::MORI(1, 2, 128));
    }

    #[test]
    fn test_parse_mxor() {
        let mut asm = MMixAssembler::new("MXOR $1, $2, $3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::MXOR(1, 2, 3));
    }

    #[test]
    fn test_parse_mxori() {
        let mut asm = MMixAssembler::new("MXORI $1, $2, 64", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::MXORI(1, 2, 64));
    }

    // Shift instruction parsing tests
    #[test]
    fn test_parse_sl() {
        let mut asm = MMixAssembler::new("SL $3, $1, $2", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SL(3, 1, 2));
    }

    #[test]
    fn test_parse_sli() {
        let mut asm = MMixAssembler::new("SLI $3, $1, 8", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SLI(3, 1, 8));
    }

    #[test]
    fn test_parse_slu() {
        let mut asm = MMixAssembler::new("SLU $10, $20, $30", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SLU(10, 20, 30));
    }

    #[test]
    fn test_parse_slui() {
        let mut asm = MMixAssembler::new("SLUI $1, $2, 16", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SLUI(1, 2, 16));
    }

    #[test]
    fn test_parse_sr() {
        let mut asm = MMixAssembler::new("SR $5, $6, $7", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SR(5, 6, 7));
    }

    #[test]
    fn test_parse_sri() {
        let mut asm = MMixAssembler::new("SRI $3, $1, 4", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SRI(3, 1, 4));
    }

    #[test]
    fn test_parse_sru() {
        let mut asm = MMixAssembler::new("SRU $8, $9, $10", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SRU(8, 9, 10));
    }

    #[test]
    fn test_parse_srui() {
        let mut asm = MMixAssembler::new("SRUI $3, $1, 1", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SRUI(3, 1, 1));
    }

    #[test]
    fn test_parse_fcmpe() {
        let mut asm = MMixAssembler::new("FCMPE $1, $2, $3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::FCMPE(1, 2, 3));
    }

    #[test]
    fn test_parse_fune() {
        let mut asm = MMixAssembler::new("FUNE $4, $5, $6", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::FUNE(4, 5, 6));
    }

    #[test]
    fn test_parse_feqle() {
        let mut asm = MMixAssembler::new("FEQLE $7, $8, $9", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::FEQLE(7, 8, 9));
    }

    /// Verify the longest-first grammar still matches the shorter mnemonics.
    #[test]
    fn test_parse_fcmp_after_fcmpe_added() {
        let mut asm = MMixAssembler::new("FCMP $1, $2, $3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::FCMP(1, 2, 3));
    }

    #[test]
    fn test_parse_feql_after_feqle_added() {
        let mut asm = MMixAssembler::new("FEQL $1, $2, $3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::FEQL(1, 2, 3));
    }

    #[test]
    fn test_parse_fun_after_fune_added() {
        let mut asm = MMixAssembler::new("FUN $1, $2, $3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::FUN(1, 2, 3));
    }

    // ---- Multi-source assembly + global-':' symbol tests ----

    #[test]
    fn test_global_symbol_label_and_operand() {
        // `:Foo` parses both as a label definition and as an operand reference.
        let src = "\
            LOC #100\n\
            Main BNZ $1,:Foo\n\
            :Foo HALT\n";
        let mut asm = MMixAssembler::new(src, "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.labels.get(":Foo").copied(), Some(0x104));
        assert_eq!(asm.labels.get("Main").copied(), Some(0x100));
        // ':Foo' and 'Foo' are distinct names; only the colon-form was defined.
        assert!(!asm.labels.contains_key("Foo"));
    }

    #[test]
    fn test_multi_source_main_calls_lib() {
        let main_src = "\
            LOC #100\n\
            Main PUSHJ $0,:Lib\n\
                 HALT\n";
        let lib_src = "\
            LOC #200\n\
            :Lib POP 0,0\n";
        let mut asm = MMixAssembler::new(main_src, "main.mms");
        asm.add_source(lib_src, "lib.mms");
        asm.parse().unwrap();
        assert_eq!(asm.labels.get("Main").copied(), Some(0x100));
        assert_eq!(asm.labels.get(":Lib").copied(), Some(0x200));

        // Two LOC regions both produced instructions.
        let addrs: Vec<u64> = asm.instructions.iter().map(|(a, _)| *a).collect();
        assert!(addrs.contains(&0x100));
        assert!(addrs.contains(&0x200));
    }

    #[test]
    fn test_multi_source_main_redefined() {
        let a = "\
            LOC #100\n\
            Main HALT\n";
        let b = "\
            LOC #200\n\
            Main HALT\n";
        let mut asm = MMixAssembler::new(a, "a.mms");
        asm.add_source(b, "b.mms");
        let err = asm.parse().expect_err("expected redefinition error");
        assert!(err.contains("'Main'"), "err: {}", err);
        assert!(err.contains("a.mms"), "err: {}", err);
        assert!(err.contains("b.mms"), "err: {}", err);
        assert!(err.contains("redefined"), "err: {}", err);
    }

    #[test]
    fn test_multi_source_global_symbol_redefined() {
        let a = "\
            LOC #100\n\
            :Foo HALT\n";
        let b = "\
            LOC #200\n\
            :Foo HALT\n";
        let mut asm = MMixAssembler::new(a, "a.mms");
        asm.add_source(b, "b.mms");
        let err = asm.parse().expect_err("expected redefinition error");
        assert!(err.contains("':Foo'"), "err: {}", err);
        assert!(err.contains("a.mms"), "err: {}", err);
        assert!(err.contains("b.mms"), "err: {}", err);
    }

    #[test]
    fn test_redefinition_across_label_and_is() {
        // A label and an IS-bound symbol with the same qualified name collide.
        let src = "\
            LOC #100\n\
            Foo HALT\n\
            Foo IS 5\n";
        let mut asm = MMixAssembler::new(src, "<test>");
        let err = asm.parse().expect_err("expected redefinition error");
        assert!(err.contains("'Foo'"), "err: {}", err);
        assert!(err.contains("redefined"), "err: {}", err);
    }

    // ---- PREFIX directive tests ----

    #[test]
    fn test_prefix_qualifies_unqualified_symbol() {
        let src = "\
            PREFIX Sub_\n\
            Bar IS 5\n";
        let mut asm = MMixAssembler::new(src, "<test>");
        asm.parse().unwrap();
        assert_eq!(
            asm.symbols.get("Sub_Bar").copied(),
            Some(SymbolType::Constant(5))
        );
        assert!(!asm.symbols.contains_key("Bar"));
    }

    #[test]
    fn test_prefix_colon_opts_out() {
        let src = "\
            PREFIX Sub_\n\
            :Foo IS 9\n";
        let mut asm = MMixAssembler::new(src, "<test>");
        asm.parse().unwrap();
        assert_eq!(
            asm.symbols.get(":Foo").copied(),
            Some(SymbolType::Constant(9))
        );
        assert!(!asm.symbols.contains_key("Sub_:Foo"));
    }

    #[test]
    fn test_prefix_persists_across_files() {
        // PREFIX set in file A applies to definitions in file B.
        let a = "PREFIX P_\n";
        let b = "\
            LOC #100\n\
            Bar HALT\n";
        let mut asm = MMixAssembler::new(a, "a.mms");
        asm.add_source(b, "b.mms");
        asm.parse().unwrap();
        assert_eq!(asm.labels.get("P_Bar").copied(), Some(0x100));
        assert!(!asm.labels.contains_key("Bar"));
    }

    #[test]
    fn test_prefix_reset_to_global() {
        // `PREFIX :` makes unqualified names resolve under the global root.
        let src = "\
            PREFIX P_\n\
            Bar IS 1\n\
            PREFIX :\n\
            Baz IS 2\n";
        let mut asm = MMixAssembler::new(src, "<test>");
        asm.parse().unwrap();
        assert_eq!(
            asm.symbols.get("P_Bar").copied(),
            Some(SymbolType::Constant(1))
        );
        assert_eq!(
            asm.symbols.get(":Baz").copied(),
            Some(SymbolType::Constant(2))
        );
    }

    // -----------------------------------------------------------------
    // Auto-immediate selection for base mnemonics (ADD, AND, SR, ...).
    // -----------------------------------------------------------------
    // The base mnemonic now accepts either a register or an in-range
    // immediate as its third operand and emits the corresponding RRR or
    // RRI MMixInstruction variant. The explicit *I mnemonics still work
    // as before through their original code path.

    #[test]
    fn test_auto_arith_register_form_unchanged() {
        // Regression: ADD with register Z still emits ADD, not ADDI.
        let mut asm = MMixAssembler::new("ADD $1,$2,$3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::ADD(1, 2, 3));
    }

    #[test]
    fn test_auto_arith_immediate_swap() {
        // ADD with a literal Z now selects the ADDI variant automatically.
        let mut asm = MMixAssembler::new("ADD $1,$2,5", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::ADDI(1, 2, 5));
    }

    // -----------------------------------------------------------------
    // SET selects its variant from the operand's kind, and the base
    // load/store mnemonics select RRR/RRI the same way.
    // -----------------------------------------------------------------

    #[test]
    fn test_set_immediate_selects_setl() {
        let mut asm = MMixAssembler::new("SET $1,5", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SETL(1, 5));
    }

    #[test]
    fn test_set_accepts_a_wyde_wide_immediate() {
        // Above the 8-bit arithmetic Z field, still inside SET's own wyde.
        let mut asm = MMixAssembler::new("SET $1,20000", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SETL(1, 20000));
    }

    #[test]
    fn test_set_rejects_an_immediate_above_a_wyde() {
        let mut asm = MMixAssembler::new("SET $1,#10000", "<test>");
        let err = asm.parse().expect_err("expected out-of-range error");
        assert!(
            err.contains("SETI"),
            "error should name SETI as the wide form, got: {err}"
        );
    }

    #[test]
    fn test_set_rejects_a_wide_symbol_operand() {
        let mut asm = MMixAssembler::new("C IS #12345\nSET $1,C", "<test>");
        let err = asm.parse().expect_err("expected out-of-range error");
        assert!(
            err.contains("SETI"),
            "error should name SETI as the wide form, got: {err}"
        );
    }

    #[test]
    fn test_seti_accepts_an_immediate_above_a_wyde() {
        let mut asm = MMixAssembler::new("SETI $1,#10000", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SET(1, 0x10000));
    }

    #[test]
    fn test_set_negative_literal_wraps_to_its_wyde() {
        let mut asm = MMixAssembler::new("SET $1,-1", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SETL(1, 0xFFFF));
    }

    #[test]
    fn test_set_symbol_register_alias_still_copies() {
        let mut asm = MMixAssembler::new("N IS $7\nSET $1,N", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SETRR(1, 7));
    }

    #[test]
    fn test_set_is_one_tetra_and_seti_is_four() {
        let mut set = MMixAssembler::new("SET $1,5", "<test>");
        set.parse().unwrap();
        let mut seti = MMixAssembler::new("SETI $1,5", "<test>");
        seti.parse().unwrap();

        assert_eq!(
            set.encode_instruction_bytes(&set.instructions[0].1).len(),
            4
        );
        assert_eq!(
            seti.encode_instruction_bytes(&seti.instructions[0].1).len(),
            16
        );
    }

    #[test]
    fn test_auto_load_store_immediate_swap() {
        let mut base = MMixAssembler::new("LDO $1,$2,0\nSTO $1,$2,0", "<test>");
        base.parse().unwrap();
        let mut explicit = MMixAssembler::new("LDOI $1,$2,0\nSTOI $1,$2,0", "<test>");
        explicit.parse().unwrap();

        assert_eq!(base.instructions[0].1, explicit.instructions[0].1);
        assert_eq!(base.instructions[1].1, explicit.instructions[1].1);
        assert_eq!(base.instructions[0].1, MMixInstruction::LDOI(1, 2, 0));
        assert_eq!(base.instructions[1].1, MMixInstruction::STOI(1, 2, 0));
    }

    #[test]
    fn test_auto_load_store_register_form_unchanged() {
        let mut asm = MMixAssembler::new("LDO $1,$2,$3\nSTBU $1,$2,$3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::LDO(1, 2, 3));
        assert_eq!(asm.instructions[1].1, MMixInstruction::STBU(1, 2, 3));
    }

    #[test]
    fn test_auto_load_store_immediate_out_of_range() {
        // Z is an 8-bit field for loads and stores.
        let mut asm = MMixAssembler::new("LDO $1,$2,300", "<test>");
        let err = asm.parse().expect_err("expected out-of-range error");
        assert!(
            err.contains("out of range 0..255"),
            "error should mention range, got: {err}"
        );
    }

    #[test]
    fn test_auto_arith_explicit_addi_still_works() {
        // The *I alias path is unchanged.
        let mut asm = MMixAssembler::new("ADDI $1,$2,5", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::ADDI(1, 2, 5));
    }

    #[test]
    fn test_auto_arith_addi_rejects_register_z() {
        // *I mnemonics must continue to reject a register third operand.
        let mut asm = MMixAssembler::new("ADDI $1,$2,$3", "<test>");
        assert!(asm.parse().is_err(), "ADDI with $Z should not parse");
    }

    #[test]
    fn test_auto_arith_immediate_out_of_range() {
        // A literal Z above 255 produces an out-of-range error.
        let mut asm = MMixAssembler::new("ADD $1,$2,300", "<test>");
        let err = asm.parse().expect_err("expected out-of-range error");
        assert!(
            err.contains("out of range 0..255"),
            "error should mention range, got: {err}"
        );
    }

    #[test]
    fn test_auto_arith_symbol_resolves_to_immediate() {
        // A symbol bound to a small constant should auto-select the RRI form.
        let src = "K IS 7\nADD $1,$2,K";
        let mut asm = MMixAssembler::new(src, "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::ADDI(1, 2, 7));
    }

    #[test]
    fn test_auto_arith_symbol_resolves_to_register_alias() {
        // A symbol bound to a register alias should keep the RRR form.
        let src = "R IS $4\nADD $1,$2,R";
        let mut asm = MMixAssembler::new(src, "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::ADD(1, 2, 4));
    }

    // Family coverage: one representative test per other family.

    #[test]
    fn test_auto_bitwise_and_with_hex_immediate() {
        let mut asm = MMixAssembler::new("AND $1,$2,#FF", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::ANDI(1, 2, 0xFF));
    }

    #[test]
    fn test_auto_shift_sr_with_decimal_immediate() {
        let mut asm = MMixAssembler::new("SR $1,$2,3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::SRI(1, 2, 3));
    }

    #[test]
    fn test_auto_bitfiddle_bdif_register_form() {
        // Bit-fiddle family still chooses RRR when Z is a register.
        let mut asm = MMixAssembler::new("BDIF $1,$2,$3", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::BDIF(1, 2, 3));
    }

    #[test]
    fn test_auto_conditional_set_csz_with_immediate() {
        let mut asm = MMixAssembler::new("CSZ $1,$2,7", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::CSZI(1, 2, 7));
    }

    #[test]
    fn test_auto_zero_or_set_zsp_with_immediate() {
        let mut asm = MMixAssembler::new("ZSP $1,$2,1", "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[0].1, MMixInstruction::ZSPI(1, 2, 1));
    }

    // Regression: a program written with base mnemonics must assemble to
    // the exact same bytes as the same program written with explicit *I
    // mnemonics. Touches all six in-scope families.
    #[test]
    fn test_auto_immediate_byte_identical_to_explicit_i() {
        let auto_src = "\
ADD  $1,$2,5
SUBU $3,$4,#10
AND  $5,$6,#FF
OR   $7,$8,1
SR   $1,$2,3
SLU  $3,$4,16
BDIF $5,$6,7
SADD $7,$8,255
CSZ  $1,$2,42
CSNN $3,$4,1
ZSP  $5,$6,8
ZSEV $7,$8,128
";
        let explicit_src = "\
ADDI  $1,$2,5
SUBUI $3,$4,#10
ANDI  $5,$6,#FF
ORI   $7,$8,1
SRI   $1,$2,3
SLUI  $3,$4,16
BDIFI $5,$6,7
SADDI $7,$8,255
CSZI  $1,$2,42
CSNNI $3,$4,1
ZSPI  $5,$6,8
ZSEVI $7,$8,128
";

        let mut auto_asm = MMixAssembler::new(auto_src, "<auto>");
        auto_asm.parse().unwrap();
        let mut explicit_asm = MMixAssembler::new(explicit_src, "<explicit>");
        explicit_asm.parse().unwrap();

        assert_eq!(
            auto_asm.instructions.len(),
            explicit_asm.instructions.len(),
            "auto and explicit forms produced different instruction counts"
        );

        for (i, (auto, explicit)) in auto_asm
            .instructions
            .iter()
            .zip(explicit_asm.instructions.iter())
            .enumerate()
        {
            let auto_bytes = auto_asm.encode_instruction_bytes(&auto.1);
            let explicit_bytes = explicit_asm.encode_instruction_bytes(&explicit.1);
            assert_eq!(
                auto_bytes, explicit_bytes,
                "instruction {i}: auto form {:?} encoded to {:?}, explicit form {:?} encoded to {:?}",
                auto.1, auto_bytes, explicit.1, explicit_bytes
            );
        }
    }

    // -----------------------------------------------------------------
    // Extensive validation for the auto-immediate path.
    // -----------------------------------------------------------------
    // The auto rules introduce backtracking through prefix collisions
    // (e.g. AND vs ANDI, ADD vs ADDU, CSN vs CSNN). The tests below
    // pin down the routing for every base mnemonic in scope, exercise
    // boundary Z values, exercise symbol-Z resolution paths, and
    // confirm cross-family non-interference.

    /// Assemble a snippet whose first instruction is the one under test
    /// and assert it produced the expected enum variant. Snippets are
    /// kept to one logical instruction so failures point at the case.
    fn assert_first_instruction(src: &str, expected: MMixInstruction) {
        let mut asm = MMixAssembler::new(src, "<test>");
        asm.parse()
            .unwrap_or_else(|e| panic!("failed to parse {src:?}: {e}"));
        assert!(
            !asm.instructions.is_empty(),
            "no instructions produced for {src:?}"
        );
        assert_eq!(
            asm.instructions[0].1, expected,
            "wrong instruction for {src:?}"
        );
    }

    /// Like `assert_first_instruction`, but for offset-bearing families
    /// (branch/PB-branch offsets, GETA/GETAB and PUSHJ/PUSHJB PC-relative
    /// addresses) where the exact computed value isn't what a prefix-
    /// collision test is proving. Checks only the variant discriminant
    /// (and any un-computed fields the predicate cares to check).
    /// Assert the LAST instruction of `src`, letting a case prefix its source
    /// with a label the instruction under test can reach backward.
    fn assert_last_instruction_matches(src: &str, predicate: impl Fn(&MMixInstruction) -> bool) {
        let mut asm = MMixAssembler::new(src, "<test>");
        asm.parse()
            .unwrap_or_else(|e| panic!("failed to parse {src:?}: {e}"));
        let last = asm
            .instructions
            .last()
            .unwrap_or_else(|| panic!("no instructions produced for {src:?}"));
        assert!(
            predicate(&last.1),
            "wrong instruction variant for {src:?}: got {:?}",
            last.1
        );
    }

    fn assert_first_instruction_matches(src: &str, predicate: impl Fn(&MMixInstruction) -> bool) {
        let mut asm = MMixAssembler::new(src, "<test>");
        asm.parse()
            .unwrap_or_else(|e| panic!("failed to parse {src:?}: {e}"));
        assert!(
            !asm.instructions.is_empty(),
            "no instructions produced for {src:?}"
        );
        assert!(
            predicate(&asm.instructions[0].1),
            "wrong instruction variant for {src:?}: got {:?}",
            asm.instructions[0].1
        );
    }

    fn assert_parse_error_contains(src: &str, needle: &str) {
        let mut asm = MMixAssembler::new(src, "<test>");
        let err = asm
            .parse()
            .err()
            .unwrap_or_else(|| panic!("expected error for {src:?}, but parse succeeded"));
        assert!(
            err.contains(needle),
            "error for {src:?} missing {needle:?}: got {err}"
        );
    }

    // ---- Family-wide auto-immediate coverage ------------------------

    #[test]
    fn test_auto_arith_full_coverage() {
        // Every arithmetic base mnemonic + register form (RRR) and
        // immediate form (RRI). Z=5 for stability; mnemonic prefixes
        // (ADD/ADDU/2ADDU/...) must each route to their own variant.
        let cases: &[(&str, MMixInstruction)] = &[
            ("ADD $1,$2,$3", MMixInstruction::ADD(1, 2, 3)),
            ("ADD $1,$2,5", MMixInstruction::ADDI(1, 2, 5)),
            ("ADDU $1,$2,$3", MMixInstruction::ADDU(1, 2, 3)),
            ("ADDU $1,$2,5", MMixInstruction::ADDUI(1, 2, 5)),
            ("2ADDU $1,$2,$3", MMixInstruction::ADDU2(1, 2, 3)),
            ("2ADDU $1,$2,5", MMixInstruction::ADDU2I(1, 2, 5)),
            ("4ADDU $1,$2,$3", MMixInstruction::ADDU4(1, 2, 3)),
            ("4ADDU $1,$2,5", MMixInstruction::ADDU4I(1, 2, 5)),
            ("8ADDU $1,$2,$3", MMixInstruction::ADDU8(1, 2, 3)),
            ("8ADDU $1,$2,5", MMixInstruction::ADDU8I(1, 2, 5)),
            ("16ADDU $1,$2,$3", MMixInstruction::ADDU16(1, 2, 3)),
            ("16ADDU $1,$2,5", MMixInstruction::ADDU16I(1, 2, 5)),
            ("SUB $1,$2,$3", MMixInstruction::SUB(1, 2, 3)),
            ("SUB $1,$2,5", MMixInstruction::SUBI(1, 2, 5)),
            ("SUBU $1,$2,$3", MMixInstruction::SUBU(1, 2, 3)),
            ("SUBU $1,$2,5", MMixInstruction::SUBUI(1, 2, 5)),
            ("MUL $1,$2,$3", MMixInstruction::MUL(1, 2, 3)),
            ("MUL $1,$2,5", MMixInstruction::MULI(1, 2, 5)),
            ("MULU $1,$2,$3", MMixInstruction::MULU(1, 2, 3)),
            ("MULU $1,$2,5", MMixInstruction::MULUI(1, 2, 5)),
            ("DIV $1,$2,$3", MMixInstruction::DIV(1, 2, 3)),
            ("DIV $1,$2,5", MMixInstruction::DIVI(1, 2, 5)),
            ("DIVU $1,$2,$3", MMixInstruction::DIVU(1, 2, 3)),
            ("DIVU $1,$2,5", MMixInstruction::DIVUI(1, 2, 5)),
            ("CMP $1,$2,$3", MMixInstruction::CMP(1, 2, 3)),
            ("CMP $1,$2,5", MMixInstruction::CMPI(1, 2, 5)),
            ("CMPU $1,$2,$3", MMixInstruction::CMPU(1, 2, 3)),
            ("CMPU $1,$2,5", MMixInstruction::CMPUI(1, 2, 5)),
        ];
        for (src, expected) in cases {
            assert_first_instruction(src, expected.clone());
        }
    }

    #[test]
    fn test_auto_bitwise_full_coverage() {
        let cases: &[(&str, MMixInstruction)] = &[
            ("AND $1,$2,$3", MMixInstruction::AND(1, 2, 3)),
            ("AND $1,$2,5", MMixInstruction::ANDI(1, 2, 5)),
            ("OR $1,$2,$3", MMixInstruction::OR(1, 2, 3)),
            ("OR $1,$2,5", MMixInstruction::ORI(1, 2, 5)),
            ("XOR $1,$2,$3", MMixInstruction::XOR(1, 2, 3)),
            ("XOR $1,$2,5", MMixInstruction::XORI(1, 2, 5)),
            ("ANDN $1,$2,$3", MMixInstruction::ANDN(1, 2, 3)),
            ("ANDN $1,$2,5", MMixInstruction::ANDNI(1, 2, 5)),
            ("ORN $1,$2,$3", MMixInstruction::ORN(1, 2, 3)),
            ("ORN $1,$2,5", MMixInstruction::ORNI(1, 2, 5)),
            ("NAND $1,$2,$3", MMixInstruction::NAND(1, 2, 3)),
            ("NAND $1,$2,5", MMixInstruction::NANDI(1, 2, 5)),
            ("NOR $1,$2,$3", MMixInstruction::NOR(1, 2, 3)),
            ("NOR $1,$2,5", MMixInstruction::NORI(1, 2, 5)),
            ("NXOR $1,$2,$3", MMixInstruction::NXOR(1, 2, 3)),
            ("NXOR $1,$2,5", MMixInstruction::NXORI(1, 2, 5)),
            ("MUX $1,$2,$3", MMixInstruction::MUX(1, 2, 3)),
            ("MUX $1,$2,5", MMixInstruction::MUXI(1, 2, 5)),
        ];
        for (src, expected) in cases {
            assert_first_instruction(src, expected.clone());
        }
    }

    #[test]
    fn test_auto_bitfiddle_full_coverage() {
        let cases: &[(&str, MMixInstruction)] = &[
            ("BDIF $1,$2,$3", MMixInstruction::BDIF(1, 2, 3)),
            ("BDIF $1,$2,5", MMixInstruction::BDIFI(1, 2, 5)),
            ("WDIF $1,$2,$3", MMixInstruction::WDIF(1, 2, 3)),
            ("WDIF $1,$2,5", MMixInstruction::WDIFI(1, 2, 5)),
            ("TDIF $1,$2,$3", MMixInstruction::TDIF(1, 2, 3)),
            ("TDIF $1,$2,5", MMixInstruction::TDIFI(1, 2, 5)),
            ("ODIF $1,$2,$3", MMixInstruction::ODIF(1, 2, 3)),
            ("ODIF $1,$2,5", MMixInstruction::ODIFI(1, 2, 5)),
            ("SADD $1,$2,$3", MMixInstruction::SADD(1, 2, 3)),
            ("SADD $1,$2,5", MMixInstruction::SADDI(1, 2, 5)),
            ("MOR $1,$2,$3", MMixInstruction::MOR(1, 2, 3)),
            ("MOR $1,$2,5", MMixInstruction::MORI(1, 2, 5)),
            ("MXOR $1,$2,$3", MMixInstruction::MXOR(1, 2, 3)),
            ("MXOR $1,$2,5", MMixInstruction::MXORI(1, 2, 5)),
        ];
        for (src, expected) in cases {
            assert_first_instruction(src, expected.clone());
        }
    }

    #[test]
    fn test_auto_shift_full_coverage() {
        let cases: &[(&str, MMixInstruction)] = &[
            ("SL $1,$2,$3", MMixInstruction::SL(1, 2, 3)),
            ("SL $1,$2,5", MMixInstruction::SLI(1, 2, 5)),
            ("SLU $1,$2,$3", MMixInstruction::SLU(1, 2, 3)),
            ("SLU $1,$2,5", MMixInstruction::SLUI(1, 2, 5)),
            ("SR $1,$2,$3", MMixInstruction::SR(1, 2, 3)),
            ("SR $1,$2,5", MMixInstruction::SRI(1, 2, 5)),
            ("SRU $1,$2,$3", MMixInstruction::SRU(1, 2, 3)),
            ("SRU $1,$2,5", MMixInstruction::SRUI(1, 2, 5)),
        ];
        for (src, expected) in cases {
            assert_first_instruction(src, expected.clone());
        }
    }

    #[test]
    fn test_auto_conditional_set_full_coverage() {
        let cases: &[(&str, MMixInstruction)] = &[
            ("CSN $1,$2,$3", MMixInstruction::CSN(1, 2, 3)),
            ("CSN $1,$2,5", MMixInstruction::CSNI(1, 2, 5)),
            ("CSZ $1,$2,$3", MMixInstruction::CSZ(1, 2, 3)),
            ("CSZ $1,$2,5", MMixInstruction::CSZI(1, 2, 5)),
            ("CSP $1,$2,$3", MMixInstruction::CSP(1, 2, 3)),
            ("CSP $1,$2,5", MMixInstruction::CSPI(1, 2, 5)),
            ("CSOD $1,$2,$3", MMixInstruction::CSOD(1, 2, 3)),
            ("CSOD $1,$2,5", MMixInstruction::CSODI(1, 2, 5)),
            ("CSNN $1,$2,$3", MMixInstruction::CSNN(1, 2, 3)),
            ("CSNN $1,$2,5", MMixInstruction::CSNNI(1, 2, 5)),
            ("CSNZ $1,$2,$3", MMixInstruction::CSNZ(1, 2, 3)),
            ("CSNZ $1,$2,5", MMixInstruction::CSNZI(1, 2, 5)),
            ("CSNP $1,$2,$3", MMixInstruction::CSNP(1, 2, 3)),
            ("CSNP $1,$2,5", MMixInstruction::CSNPI(1, 2, 5)),
            ("CSEV $1,$2,$3", MMixInstruction::CSEV(1, 2, 3)),
            ("CSEV $1,$2,5", MMixInstruction::CSEVI(1, 2, 5)),
        ];
        for (src, expected) in cases {
            assert_first_instruction(src, expected.clone());
        }
    }

    #[test]
    fn test_auto_zero_or_set_full_coverage() {
        let cases: &[(&str, MMixInstruction)] = &[
            ("ZSN $1,$2,$3", MMixInstruction::ZSN(1, 2, 3)),
            ("ZSN $1,$2,5", MMixInstruction::ZSNI(1, 2, 5)),
            ("ZSZ $1,$2,$3", MMixInstruction::ZSZ(1, 2, 3)),
            ("ZSZ $1,$2,5", MMixInstruction::ZSZI(1, 2, 5)),
            ("ZSP $1,$2,$3", MMixInstruction::ZSP(1, 2, 3)),
            ("ZSP $1,$2,5", MMixInstruction::ZSPI(1, 2, 5)),
            ("ZSOD $1,$2,$3", MMixInstruction::ZSOD(1, 2, 3)),
            ("ZSOD $1,$2,5", MMixInstruction::ZSODI(1, 2, 5)),
            ("ZSNN $1,$2,$3", MMixInstruction::ZSNN(1, 2, 3)),
            ("ZSNN $1,$2,5", MMixInstruction::ZSNNI(1, 2, 5)),
            ("ZSNZ $1,$2,$3", MMixInstruction::ZSNZ(1, 2, 3)),
            ("ZSNZ $1,$2,5", MMixInstruction::ZSNZI(1, 2, 5)),
            ("ZSNP $1,$2,$3", MMixInstruction::ZSNP(1, 2, 3)),
            ("ZSNP $1,$2,5", MMixInstruction::ZSNPI(1, 2, 5)),
            ("ZSEV $1,$2,$3", MMixInstruction::ZSEV(1, 2, 3)),
            ("ZSEV $1,$2,5", MMixInstruction::ZSEVI(1, 2, 5)),
        ];
        for (src, expected) in cases {
            assert_first_instruction(src, expected.clone());
        }
    }

    // ---- Canonical spellings for the remaining families -------------
    // MMIXAL picks the immediate opcode from the operand, so a base
    // mnemonic with an immediate Z emits what its *I spelling emits. The
    // *I spellings stay accepted as a legacy surface.

    fn first_instruction(src: &str) -> MMixInstruction {
        let mut asm = MMixAssembler::new(src, "<test>");
        asm.parse()
            .unwrap_or_else(|e| panic!("failed to parse {src:?}: {e}"));
        asm.instructions
            .first()
            .unwrap_or_else(|| panic!("no instructions produced for {src:?}"))
            .1
            .clone()
    }

    #[test]
    fn test_auto_extended_load_store_full_coverage() {
        let cases: &[(&str, MMixInstruction)] = &[
            ("LDUNC $1,$2,$3", MMixInstruction::LDUNC(1, 2, 3)),
            ("LDUNC $1,$2,5", MMixInstruction::LDUNCI(1, 2, 5)),
            ("STUNC $1,$2,$3", MMixInstruction::STUNC(1, 2, 3)),
            ("STUNC $1,$2,5", MMixInstruction::STUNCI(1, 2, 5)),
            ("LDHT $1,$2,$3", MMixInstruction::LDHT(1, 2, 3)),
            ("LDHT $1,$2,5", MMixInstruction::LDHTI(1, 2, 5)),
            ("STHT $1,$2,$3", MMixInstruction::STHT(1, 2, 3)),
            ("STHT $1,$2,5", MMixInstruction::STHTI(1, 2, 5)),
            ("LDSF $1,$2,$3", MMixInstruction::LDSF(1, 2, 3)),
            ("LDSF $1,$2,5", MMixInstruction::LDSFI(1, 2, 5)),
            ("STSF $1,$2,$3", MMixInstruction::STSF(1, 2, 3)),
            ("STSF $1,$2,5", MMixInstruction::STSFI(1, 2, 5)),
            ("LDVTS $1,$2,$3", MMixInstruction::LDVTS(1, 2, 3)),
            ("LDVTS $1,$2,5", MMixInstruction::LDVTSI(1, 2, 5)),
            ("CSWAP $1,$2,$3", MMixInstruction::CSWAP(1, 2, 3)),
            ("CSWAP $1,$2,5", MMixInstruction::CSWAPI(1, 2, 5)),
        ];
        for (src, expected) in cases {
            assert_first_instruction(src, expected.clone());
        }
    }

    #[test]
    fn test_auto_cache_and_go_full_coverage() {
        let cases: &[(&str, MMixInstruction)] = &[
            ("PRELD $1,$2,$3", MMixInstruction::PRELD(1, 2, 3)),
            ("PRELD $1,$2,5", MMixInstruction::PRELDI(1, 2, 5)),
            ("PREGO $1,$2,$3", MMixInstruction::PREGO(1, 2, 3)),
            ("PREGO $1,$2,5", MMixInstruction::PREGOI(1, 2, 5)),
            ("PREST $1,$2,$3", MMixInstruction::PREST(1, 2, 3)),
            ("PREST $1,$2,5", MMixInstruction::PRESTI(1, 2, 5)),
            ("SYNCD $1,$2,$3", MMixInstruction::SYNCD(1, 2, 3)),
            ("SYNCD $1,$2,5", MMixInstruction::SYNCDI(1, 2, 5)),
            ("SYNCID $1,$2,$3", MMixInstruction::SYNCID(1, 2, 3)),
            ("SYNCID $1,$2,5", MMixInstruction::SYNCIDI(1, 2, 5)),
            ("GO $1,$2,$3", MMixInstruction::GO(1, 2, 3)),
            ("GO $1,$2,5", MMixInstruction::GOI(1, 2, 5)),
            ("PUSHGO $1,$2,$3", MMixInstruction::PUSHGO(1, 2, 3)),
            ("PUSHGO $1,$2,5", MMixInstruction::PUSHGOI(1, 2, 5)),
        ];
        for (src, expected) in cases {
            assert_first_instruction(src, expected.clone());
        }
    }

    #[test]
    fn test_auto_float_conversion_full_coverage() {
        // Y is a rounding-mode value, not a register; 0 here exercises
        // Z's register/immediate auto-select, this test's point.
        let cases: &[(&str, MMixInstruction)] = &[
            ("FLOT $1,0,$3", MMixInstruction::FLOT(1, 0, 3)),
            ("FLOT $1,0,5", MMixInstruction::FLOTI(1, 0, 5)),
            ("FLOTU $1,0,$3", MMixInstruction::FLOTU(1, 0, 3)),
            ("FLOTU $1,0,5", MMixInstruction::FLOTUI(1, 0, 5)),
            ("SFLOT $1,0,$3", MMixInstruction::SFLOT(1, 0, 3)),
            ("SFLOT $1,0,5", MMixInstruction::SFLOTI(1, 0, 5)),
            ("SFLOTU $1,0,$3", MMixInstruction::SFLOTU(1, 0, 3)),
            ("SFLOTU $1,0,5", MMixInstruction::SFLOTUI(1, 0, 5)),
        ];
        for (src, expected) in cases {
            assert_first_instruction(src, expected.clone());
        }
    }

    #[test]
    fn test_auto_irregular_operand_shapes_full_coverage() {
        // STCO's X and NEG's Y stay immediate bytes; only Z auto-selects.
        let cases: &[(&str, MMixInstruction)] = &[
            ("STCO 5,$2,$3", MMixInstruction::STCO(5, 2, 3)),
            ("STCO 5,$2,7", MMixInstruction::STCOI(5, 2, 7)),
            ("NEG $1,0,$3", MMixInstruction::NEG(1, 0, 3)),
            ("NEG $1,0,7", MMixInstruction::NEGI(1, 0, 7)),
            ("NEGU $1,0,$3", MMixInstruction::NEGU(1, 0, 3)),
            ("NEGU $1,0,7", MMixInstruction::NEGUI(1, 0, 7)),
            ("PUT rA,$1", MMixInstruction::PUT(21, 1)),
            ("PUT rA,7", MMixInstruction::PUTI(21, 7)),
        ];
        for (src, expected) in cases {
            assert_first_instruction(src, expected.clone());
        }
    }

    #[test]
    fn test_base_spelling_agrees_with_legacy_immediate_spelling() {
        let pairs: &[(&str, &str)] = &[
            ("LDHT $1,$2,5", "LDHTI $1,$2,5"),
            ("LDSF $1,$2,5", "LDSFI $1,$2,5"),
            ("LDUNC $1,$2,5", "LDUNCI $1,$2,5"),
            ("LDVTS $1,$2,5", "LDVTSI $1,$2,5"),
            ("STHT $1,$2,5", "STHTI $1,$2,5"),
            ("STSF $1,$2,5", "STSFI $1,$2,5"),
            ("STUNC $1,$2,5", "STUNCI $1,$2,5"),
            ("CSWAP $1,$2,5", "CSWAPI $1,$2,5"),
            ("PREGO $1,$2,5", "PREGOI $1,$2,5"),
            ("PRELD $1,$2,5", "PRELDI $1,$2,5"),
            ("PREST $1,$2,5", "PRESTI $1,$2,5"),
            ("SYNCD $1,$2,5", "SYNCDI $1,$2,5"),
            ("SYNCID $1,$2,5", "SYNCIDI $1,$2,5"),
            ("GO $1,$2,5", "GOI $1,$2,5"),
            ("PUSHGO $1,$2,5", "PUSHGOI $1,$2,5"),
            ("FLOT $1,0,5", "FLOTI $1,0,5"),
            ("FLOTU $1,0,5", "FLOTUI $1,0,5"),
            ("SFLOT $1,0,5", "SFLOTI $1,0,5"),
            ("SFLOTU $1,0,5", "SFLOTUI $1,0,5"),
            ("STCO 5,$2,7", "STCOI 5,$2,7"),
            ("NEG $1,0,7", "NEGI $1,0,7"),
            ("NEGU $1,0,7", "NEGUI $1,0,7"),
            ("PUT rA,7", "PUTI rA,7"),
        ];
        for (base, legacy) in pairs {
            assert_eq!(
                first_instruction(base),
                first_instruction(legacy),
                "{base:?} must emit what {legacy:?} emits"
            );
        }
    }

    #[test]
    fn test_no_previously_accepted_operand_form_narrowed() {
        // Every spelling these families accepted before their base
        // mnemonics auto-selected. Widening must displace none of them.
        let forms: &[&str] = &[
            "LDHT $1,$2,$3",
            "LDHTI $1,$2,5",
            "LDSF $1,$2,$3",
            "LDSFI $1,$2,5",
            "LDUNC $1,$2,$3",
            "LDUNCI $1,$2,5",
            "LDVTS $1,$2,$3",
            "LDVTSI $1,$2,5",
            "STHT $1,$2,$3",
            "STHTI $1,$2,5",
            "STSF $1,$2,$3",
            "STSFI $1,$2,5",
            "STUNC $1,$2,$3",
            "STUNCI $1,$2,5",
            "CSWAP $1,$2,$3",
            "CSWAPI $1,$2,5",
            "PREGO $1,$2,$3",
            "PREGOI $1,$2,5",
            "PRELD $1,$2,$3",
            "PRELDI $1,$2,5",
            "PREST $1,$2,$3",
            "PRESTI $1,$2,5",
            "SYNCD $1,$2,$3",
            "SYNCDI $1,$2,5",
            "SYNCID $1,$2,$3",
            "SYNCIDI $1,$2,5",
            "GO $1,$2,$3",
            "GOI $1,$2,5",
            "PUSHGO $1,$2,$3",
            "PUSHGOI $1,$2,5",
            "FLOT $1,0,$3",
            "FLOTI $1,0,5",
            "FLOTU $1,0,$3",
            "FLOTUI $1,0,5",
            "SFLOT $1,0,$3",
            "SFLOTI $1,0,5",
            "SFLOTU $1,0,$3",
            "SFLOTUI $1,0,5",
            "STCO 5,$2,$3",
            "STCOI 5,$2,7",
            "NEG $1,0,$3",
            "NEGI $1,0,7",
            "NEGU $1,0,$3",
            "NEGUI $1,0,7",
            "PUT rA,$1",
            "PUTI rA,7",
            "LDA $1,$2,3",
            "LDAI $1,$2,3",
        ];
        for src in forms {
            let mut asm = MMixAssembler::new(src, "<test>");
            asm.parse()
                .unwrap_or_else(|e| panic!("{src:?} no longer assembles: {e}"));
        }
    }

    #[test]
    fn test_flot_rejects_register_in_y_slot() {
        // Y in FLOT's grammar is `expr_value`-only, not `register`; a
        // register-Y spelling must now fail to parse, not silently
        // reinterpret $2's register number as a rounding-mode value.
        // `is_err()` alone survives a re-widened grammar that admits the
        // register but still leaves a trailing token elsewhere, so pin the
        // exact rejection: the 3-operand form
        // fails to match at Y (a register isn't `expr_value`), and the
        // 2-operand form then consumes only `$1,$2`, stranding `,$3`.
        let mut asm = MMixAssembler::new("FLOT $1,$2,$3", "<test>");
        let err = asm
            .parse()
            .expect_err("a register in FLOT's Y slot must no longer parse");
        assert_eq!(err, "<test>:1:11: syntax error: expected EOI");
    }

    #[test]
    fn test_round_mode_symbols_resolve_to_documented_values() {
        // The predefined-symbol table (MMIXAL reference), independent of
        // rA's own persistent-mode numbering.
        let asm = MMixAssembler::new("", "<test>");
        for (name, value) in [
            ("ROUND_CURRENT", 0u64),
            ("ROUND_OFF", 1),
            ("ROUND_UP", 2),
            ("ROUND_DOWN", 3),
        ] {
            assert_eq!(
                asm.symbols.get(name).copied(),
                Some(SymbolType::Constant(value)),
                "{name} must resolve to {value}"
            );
        }
    }

    #[test]
    fn test_lda_selects_addus_two_opcodes() {
        assert_first_instruction("LDA $1,$2,$3", MMixInstruction::LDA(1, 2, 3));
        assert_first_instruction("LDA $1,$2,3", MMixInstruction::LDAI(1, 2, 3));
        assert_first_instruction("LDAI $1,$2,3", MMixInstruction::LDAI(1, 2, 3));
    }

    #[test]
    fn test_lda_emits_the_same_bytes_as_addu() {
        // LDA carries no opcode of its own: it is ADDU under another name,
        // in both the register and the immediate operand form.
        let asm = MMixAssembler::new("", "<test>");
        for (lda, addu) in [
            ("LDA $1,$2,$3", "ADDU $1,$2,$3"),
            ("LDA $1,$2,3", "ADDU $1,$2,3"),
        ] {
            assert_eq!(
                asm.encode_instruction_bytes(&first_instruction(lda)),
                asm.encode_instruction_bytes(&first_instruction(addu)),
                "{lda:?} must emit the same bytes as {addu:?}"
            );
        }
    }

    #[test]
    fn test_stco_rejects_a_register_x_operand() {
        // STCO stores an immediate byte; X is that byte, never a register.
        let mut asm = MMixAssembler::new("STCO $1,$2,$3", "<test>");
        assert!(asm.parse().is_err(), "STCO's X operand is not a register");
    }

    #[test]
    fn test_jmpb_backward_target_encodes_knuth_field() {
        // JMPB sits at 0x104 (BACK's HALT is 4 bytes), target 0x100:
        // magnitude = 1 tetra, field = 2^24 - 1.
        let source = "LOC #100\nBACK: HALT\nJMPB BACK";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse().unwrap();
        assert_eq!(asm.instructions[1].1, MMixInstruction::JMPB(0xFFFFFF));
    }

    #[test]
    fn test_jmpb_forward_target_errors() {
        let source = "JMPB LABEL\nLOC #100\nLABEL: HALT";
        let mut asm = MMixAssembler::new(source, "<test>");
        let err = asm.parse().expect_err("JMPB encodes only backward targets");
        assert!(
            err.contains("use JMP instead"),
            "error should name JMP as the forward form, got: {err}"
        );
    }

    // ---- Mnemonic prefix-collision tests ----------------------------
    // These pin down PEG backtracking for prefix-overlapping mnemonics
    // (ADD vs ADDU vs ADDUI; AND vs ANDN vs ANDNI; CSN vs CSNN; etc.).

    #[test]
    fn test_prefix_robust_arith_signed_vs_unsigned() {
        // ADD must not steal "ADDU"; ADDU must not steal "ADDUI" (the
        // *I path must still match through inst_arith_rri).
        assert_first_instruction("ADD $1,$2,$3", MMixInstruction::ADD(1, 2, 3));
        assert_first_instruction("ADDU $1,$2,$3", MMixInstruction::ADDU(1, 2, 3));
        assert_first_instruction("ADDI $1,$2,7", MMixInstruction::ADDI(1, 2, 7));
        assert_first_instruction("ADDUI $1,$2,7", MMixInstruction::ADDUI(1, 2, 7));
        assert_first_instruction("ADD $1,$2,7", MMixInstruction::ADDI(1, 2, 7));
        assert_first_instruction("ADDU $1,$2,7", MMixInstruction::ADDUI(1, 2, 7));
    }

    #[test]
    fn test_prefix_robust_numeric_arith() {
        // 2ADDU through 16ADDU each must claim their own mnemonic and
        // their *I variant must still route via the rri path.
        assert_first_instruction("2ADDU $1,$2,$3", MMixInstruction::ADDU2(1, 2, 3));
        assert_first_instruction("4ADDU $1,$2,$3", MMixInstruction::ADDU4(1, 2, 3));
        assert_first_instruction("8ADDU $1,$2,$3", MMixInstruction::ADDU8(1, 2, 3));
        assert_first_instruction("16ADDU $1,$2,$3", MMixInstruction::ADDU16(1, 2, 3));
        assert_first_instruction("2ADDU $1,$2,5", MMixInstruction::ADDU2I(1, 2, 5));
        assert_first_instruction("4ADDU $1,$2,5", MMixInstruction::ADDU4I(1, 2, 5));
        assert_first_instruction("8ADDU $1,$2,5", MMixInstruction::ADDU8I(1, 2, 5));
        assert_first_instruction("16ADDU $1,$2,5", MMixInstruction::ADDU16I(1, 2, 5));
        assert_first_instruction("2ADDUI $1,$2,5", MMixInstruction::ADDU2I(1, 2, 5));
        assert_first_instruction("4ADDUI $1,$2,5", MMixInstruction::ADDU4I(1, 2, 5));
        assert_first_instruction("8ADDUI $1,$2,5", MMixInstruction::ADDU8I(1, 2, 5));
        assert_first_instruction("16ADDUI $1,$2,5", MMixInstruction::ADDU16I(1, 2, 5));
    }

    #[test]
    fn test_prefix_robust_bitwise_and_andn() {
        // AND vs ANDN vs ANDI vs ANDNI: each must route to its own
        // variant. Particularly important because mnemonic_and matches
        // the "AND" prefix of all four; backtracking has to recover.
        assert_first_instruction("AND $1,$2,$3", MMixInstruction::AND(1, 2, 3));
        assert_first_instruction("ANDN $1,$2,$3", MMixInstruction::ANDN(1, 2, 3));
        assert_first_instruction("AND $1,$2,7", MMixInstruction::ANDI(1, 2, 7));
        assert_first_instruction("ANDN $1,$2,7", MMixInstruction::ANDNI(1, 2, 7));
        assert_first_instruction("ANDI $1,$2,7", MMixInstruction::ANDI(1, 2, 7));
        assert_first_instruction("ANDNI $1,$2,7", MMixInstruction::ANDNI(1, 2, 7));
        // ANDN also collides with the wyde-field ANDNH/ANDNMH/ANDNML/ANDNL
        // family (2-operand reg,imm shape, distinct from the 3-operand
        // AND/ANDN/ANDNI forms above).
        assert_first_instruction("ANDNH $1,5", MMixInstruction::ANDNH(1, 5));
        assert_first_instruction("ANDNMH $1,5", MMixInstruction::ANDNMH(1, 5));
        assert_first_instruction("ANDNML $1,5", MMixInstruction::ANDNML(1, 5));
        assert_first_instruction("ANDNL $1,5", MMixInstruction::ANDNL(1, 5));
    }

    #[test]
    fn test_prefix_robust_bitwise_or_orn() {
        assert_first_instruction("OR $1,$2,$3", MMixInstruction::OR(1, 2, 3));
        assert_first_instruction("ORN $1,$2,$3", MMixInstruction::ORN(1, 2, 3));
        assert_first_instruction("OR $1,$2,7", MMixInstruction::ORI(1, 2, 7));
        assert_first_instruction("ORN $1,$2,7", MMixInstruction::ORNI(1, 2, 7));
        assert_first_instruction("ORI $1,$2,7", MMixInstruction::ORI(1, 2, 7));
        assert_first_instruction("ORNI $1,$2,7", MMixInstruction::ORNI(1, 2, 7));
        // OR also collides with the wyde-field ORH/ORMH/ORML/ORL family
        // (2-operand reg,imm shape, distinct from the 3-operand OR/ORN/ORNI
        // forms above).
        assert_first_instruction("ORH $1,5", MMixInstruction::ORH(1, 5));
        assert_first_instruction("ORMH $1,5", MMixInstruction::ORMH(1, 5));
        assert_first_instruction("ORML $1,5", MMixInstruction::ORML(1, 5));
        assert_first_instruction("ORL $1,5", MMixInstruction::ORL(1, 5));
    }

    #[test]
    fn test_prefix_robust_set_family() {
        // SET must not steal SETI's longer literal, and SETI/SETL/SETH/
        // SETMH/SETML — five mnemonics sharing the "SET" prefix — must each
        // route to their own variant.
        assert_first_instruction("SET $1,$2", MMixInstruction::SETRR(1, 2));
        assert_first_instruction("SETI $1,5", MMixInstruction::SET(1, 5));
        assert_first_instruction("SETL $1,5", MMixInstruction::SETL(1, 5));
        assert_first_instruction("SETH $1,5", MMixInstruction::SETH(1, 5));
        assert_first_instruction("SETMH $1,5", MMixInstruction::SETMH(1, 5));
        assert_first_instruction("SETML $1,5", MMixInstruction::SETML(1, 5));
    }

    #[test]
    fn test_prefix_robust_neg() {
        // NEG/NEGU/NEGI/NEGUI: NEG must not steal NEGU's, NEGI's, or
        // NEGUI's longer literal.
        assert_first_instruction("NEG $1,5,$3", MMixInstruction::NEG(1, 5, 3));
        assert_first_instruction("NEGU $1,5,$3", MMixInstruction::NEGU(1, 5, 3));
        assert_first_instruction("NEGI $1,5,7", MMixInstruction::NEGI(1, 5, 7));
        assert_first_instruction("NEGUI $1,5,7", MMixInstruction::NEGUI(1, 5, 7));
    }

    #[test]
    fn test_prefix_robust_float_fix_flot() {
        // FIX/FIXU and FLOT/FLOTI/FLOTU/FLOTUI and SFLOT/SFLOTI/SFLOTU/
        // SFLOTUI: FIX must not steal FIXU's literal, FLOT must not steal
        // FLOTU's/FLOTI's/FLOTUI's, and likewise for SFLOT. Y is a
        // rounding-mode value, not a register; 0 here is orthogonal to
        // what this test exercises.
        assert_first_instruction("FIX $1,0,$3", MMixInstruction::FIX(1, 0, 3));
        assert_first_instruction("FIXU $1,0,$3", MMixInstruction::FIXU(1, 0, 3));
        assert_first_instruction("FLOT $1,0,$3", MMixInstruction::FLOT(1, 0, 3));
        assert_first_instruction("FLOTU $1,0,$3", MMixInstruction::FLOTU(1, 0, 3));
        assert_first_instruction("FLOTI $1,0,5", MMixInstruction::FLOTI(1, 0, 5));
        assert_first_instruction("FLOTUI $1,0,5", MMixInstruction::FLOTUI(1, 0, 5));
        assert_first_instruction("SFLOT $1,0,$3", MMixInstruction::SFLOT(1, 0, 3));
        assert_first_instruction("SFLOTU $1,0,$3", MMixInstruction::SFLOTU(1, 0, 3));
        assert_first_instruction("SFLOTI $1,0,5", MMixInstruction::SFLOTI(1, 0, 5));
        assert_first_instruction("SFLOTUI $1,0,5", MMixInstruction::SFLOTUI(1, 0, 5));
    }

    #[test]
    fn test_prefix_robust_load_store_families() {
        // LDB/LDW/LDT/LDO and STB/STW/STT/STO each have a U sibling (LDBU,
        // ...) and an I sibling (LDBI, ...) and a UI sibling (LDBUI, ...);
        // the base mnemonic must not steal any of them.
        let cases: &[(&str, MMixInstruction)] = &[
            ("LDB $1,$2,$3", MMixInstruction::LDB(1, 2, 3)),
            ("LDBU $1,$2,$3", MMixInstruction::LDBU(1, 2, 3)),
            ("LDBI $1,$2,5", MMixInstruction::LDBI(1, 2, 5)),
            ("LDBUI $1,$2,5", MMixInstruction::LDBUI(1, 2, 5)),
            ("LDW $1,$2,$3", MMixInstruction::LDW(1, 2, 3)),
            ("LDWU $1,$2,$3", MMixInstruction::LDWU(1, 2, 3)),
            ("LDWI $1,$2,5", MMixInstruction::LDWI(1, 2, 5)),
            ("LDWUI $1,$2,5", MMixInstruction::LDWUI(1, 2, 5)),
            ("LDT $1,$2,$3", MMixInstruction::LDT(1, 2, 3)),
            ("LDTU $1,$2,$3", MMixInstruction::LDTU(1, 2, 3)),
            ("LDTI $1,$2,5", MMixInstruction::LDTI(1, 2, 5)),
            ("LDTUI $1,$2,5", MMixInstruction::LDTUI(1, 2, 5)),
            ("LDO $1,$2,$3", MMixInstruction::LDO(1, 2, 3)),
            ("LDOU $1,$2,$3", MMixInstruction::LDOU(1, 2, 3)),
            ("LDOI $1,$2,5", MMixInstruction::LDOI(1, 2, 5)),
            ("LDOUI $1,$2,5", MMixInstruction::LDOUI(1, 2, 5)),
            ("STB $1,$2,$3", MMixInstruction::STB(1, 2, 3)),
            ("STBU $1,$2,$3", MMixInstruction::STBU(1, 2, 3)),
            ("STBI $1,$2,5", MMixInstruction::STBI(1, 2, 5)),
            ("STBUI $1,$2,5", MMixInstruction::STBUI(1, 2, 5)),
            ("STW $1,$2,$3", MMixInstruction::STW(1, 2, 3)),
            ("STWU $1,$2,$3", MMixInstruction::STWU(1, 2, 3)),
            ("STWI $1,$2,5", MMixInstruction::STWI(1, 2, 5)),
            ("STWUI $1,$2,5", MMixInstruction::STWUI(1, 2, 5)),
            ("STT $1,$2,$3", MMixInstruction::STT(1, 2, 3)),
            ("STTU $1,$2,$3", MMixInstruction::STTU(1, 2, 3)),
            ("STTI $1,$2,5", MMixInstruction::STTI(1, 2, 5)),
            ("STTUI $1,$2,5", MMixInstruction::STTUI(1, 2, 5)),
            ("STO $1,$2,$3", MMixInstruction::STO(1, 2, 3)),
            ("STOU $1,$2,$3", MMixInstruction::STOU(1, 2, 3)),
            ("STOI $1,$2,5", MMixInstruction::STOI(1, 2, 5)),
            ("STOUI $1,$2,5", MMixInstruction::STOUI(1, 2, 5)),
        ];
        for (src, expected) in cases {
            assert_first_instruction(src, expected.clone());
        }
    }

    #[test]
    fn test_prefix_robust_lda() {
        // LDA must not steal LDAI's longer literal. Both spellings select
        // the immediate opcode here; only LDA's register form selects 0x22.
        assert_first_instruction("LDA $1,$2,$3", MMixInstruction::LDA(1, 2, 3));
        assert_first_instruction("LDA $1,$2,5", MMixInstruction::LDAI(1, 2, 5));
        assert_first_instruction("LDAI $1,$2,5", MMixInstruction::LDAI(1, 2, 5));
    }

    #[test]
    fn test_prefix_robust_get_geta_getab() {
        // GET must not swallow the "GET" prefix of GETA/GETAB, and GETA
        // must not swallow GETAB's. GETA/GETAB carry a computed PC-relative
        // offset, so only the variant discriminant (and the un-computed X
        // register) is checked here, per the offset-bearing-family note.
        assert_first_instruction("GET $1,0", MMixInstruction::GET(1, 0));
        assert_first_instruction_matches("GETA $0,4", |i| {
            matches!(i, MMixInstruction::GETA(0, _, _))
        });
        let source = "LOC #100\nBACK: HALT\nGETAB $0,BACK";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse()
            .unwrap_or_else(|e| panic!("failed to parse {source:?}: {e}"));
        assert!(matches!(
            asm.instructions[1].1,
            MMixInstruction::GETAB(0, _, _)
        ));
    }

    #[test]
    fn test_prefix_robust_go_pushgo() {
        // GO/GOI and PUSHGO/PUSHGOI: the base mnemonic must not steal its
        // *I sibling's literal.
        assert_first_instruction("GO $1,$2,$3", MMixInstruction::GO(1, 2, 3));
        assert_first_instruction("GOI $1,$2,5", MMixInstruction::GOI(1, 2, 5));
        assert_first_instruction("PUSHGO $1,$2,$3", MMixInstruction::PUSHGO(1, 2, 3));
        assert_first_instruction("PUSHGOI $1,$2,5", MMixInstruction::PUSHGOI(1, 2, 5));
    }

    #[test]
    fn test_prefix_robust_pushj() {
        // PUSHJ must not steal PUSHJB's longer literal. Both carry a
        // computed offset, so only the discriminant and X register are
        // checked (offset-bearing-family note).
        assert_first_instruction_matches("PUSHJ $1,4", |i| {
            matches!(i, MMixInstruction::PUSHJ(1, _, _))
        });
        let source = "LOC #100\nBACK: HALT\nPUSHJB $1,BACK";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse()
            .unwrap_or_else(|e| panic!("failed to parse {source:?}: {e}"));
        assert!(matches!(
            asm.instructions[1].1,
            MMixInstruction::PUSHJB(1, _, _)
        ));
    }

    #[test]
    fn test_prefix_robust_put() {
        // PUT must not steal PUTI's longer literal.
        assert_first_instruction("PUT 5,$1", MMixInstruction::PUT(5, 1));
        assert_first_instruction("PUTI 5,7", MMixInstruction::PUTI(5, 7));
    }

    #[test]
    fn test_prefix_robust_prefetch_and_sync() {
        // PREGO/PRELD/PREST/SYNCD/SYNCID each have an *I sibling, and SYNC
        // itself is a literal prefix of SYNCD/SYNCDI/SYNCID/SYNCIDI.
        assert_first_instruction("PREGO $1,$2,$3", MMixInstruction::PREGO(1, 2, 3));
        assert_first_instruction("PREGOI $1,$2,5", MMixInstruction::PREGOI(1, 2, 5));
        assert_first_instruction("PRELD $1,$2,$3", MMixInstruction::PRELD(1, 2, 3));
        assert_first_instruction("PRELDI $1,$2,5", MMixInstruction::PRELDI(1, 2, 5));
        assert_first_instruction("PREST $1,$2,$3", MMixInstruction::PREST(1, 2, 3));
        assert_first_instruction("PRESTI $1,$2,5", MMixInstruction::PRESTI(1, 2, 5));
        assert_first_instruction("SYNCD $1,$2,$3", MMixInstruction::SYNCD(1, 2, 3));
        assert_first_instruction("SYNCDI $1,$2,5", MMixInstruction::SYNCDI(1, 2, 5));
        assert_first_instruction("SYNCID $1,$2,$3", MMixInstruction::SYNCID(1, 2, 3));
        assert_first_instruction("SYNCIDI $1,$2,5", MMixInstruction::SYNCIDI(1, 2, 5));
        assert_first_instruction("SYNC 5", MMixInstruction::SYNC(5));
    }

    #[test]
    fn test_prefix_robust_extra_load_store() {
        // LDUNC/STUNC/LDHT/STHT/LDSF/STSF/LDVTS/CSWAP/STCO each have an *I
        // sibling; the base mnemonic must not steal it.
        assert_first_instruction("LDUNC $1,$2,$3", MMixInstruction::LDUNC(1, 2, 3));
        assert_first_instruction("LDUNCI $1,$2,5", MMixInstruction::LDUNCI(1, 2, 5));
        assert_first_instruction("STUNC $1,$2,$3", MMixInstruction::STUNC(1, 2, 3));
        assert_first_instruction("STUNCI $1,$2,5", MMixInstruction::STUNCI(1, 2, 5));
        assert_first_instruction("LDHT $1,$2,$3", MMixInstruction::LDHT(1, 2, 3));
        assert_first_instruction("LDHTI $1,$2,5", MMixInstruction::LDHTI(1, 2, 5));
        assert_first_instruction("STHT $1,$2,$3", MMixInstruction::STHT(1, 2, 3));
        assert_first_instruction("STHTI $1,$2,5", MMixInstruction::STHTI(1, 2, 5));
        assert_first_instruction("LDSF $1,$2,$3", MMixInstruction::LDSF(1, 2, 3));
        assert_first_instruction("LDSFI $1,$2,5", MMixInstruction::LDSFI(1, 2, 5));
        assert_first_instruction("STSF $1,$2,$3", MMixInstruction::STSF(1, 2, 3));
        assert_first_instruction("STSFI $1,$2,5", MMixInstruction::STSFI(1, 2, 5));
        assert_first_instruction("LDVTS $1,$2,$3", MMixInstruction::LDVTS(1, 2, 3));
        assert_first_instruction("LDVTSI $1,$2,5", MMixInstruction::LDVTSI(1, 2, 5));
        assert_first_instruction("CSWAP $1,$2,$3", MMixInstruction::CSWAP(1, 2, 3));
        assert_first_instruction("CSWAPI $1,$2,5", MMixInstruction::CSWAPI(1, 2, 5));

        assert_first_instruction("STCO 5,$1,$2", MMixInstruction::STCO(5, 1, 2));
        assert_first_instruction("STCOI 5,$1,7", MMixInstruction::STCOI(5, 1, 7));
    }

    /// Predicate over a parsed instruction's variant, paired with source in
    /// the `branch`/`pbranch` family tests below (offset-bearing, so the
    /// exact value isn't what those tests are proving).
    type InstructionPredicate = fn(&MMixInstruction) -> bool;

    #[test]
    fn test_prefix_robust_branch_family() {
        // BN/BNB/BNN/BNNB/BNP/BNPB/BNZ/BNZB/BEV/BEVB/BOD/BODB/BP/BPB/BZ/BZB:
        // every short mnemonic in this family is a literal prefix of at
        // least one longer sibling. Offsets are computed, so only the
        // discriminant and X register are checked. A *B mnemonic needs a
        // target behind it, so those cases branch to a preceding label.
        let cases: &[(&str, InstructionPredicate)] = &[
            ("BN $1,4", |i| matches!(i, MMixInstruction::BN(1, _))),
            ("BACK: HALT\nBNB $1,BACK", |i| {
                matches!(i, MMixInstruction::BNB(1, _))
            }),
            ("BNN $1,4", |i| matches!(i, MMixInstruction::BNN(1, _))),
            ("BACK: HALT\nBNNB $1,BACK", |i| {
                matches!(i, MMixInstruction::BNNB(1, _))
            }),
            ("BNP $1,4", |i| matches!(i, MMixInstruction::BNP(1, _))),
            ("BACK: HALT\nBNPB $1,BACK", |i| {
                matches!(i, MMixInstruction::BNPB(1, _))
            }),
            ("BNZ $1,4", |i| matches!(i, MMixInstruction::BNZ(1, _))),
            ("BACK: HALT\nBNZB $1,BACK", |i| {
                matches!(i, MMixInstruction::BNZB(1, _))
            }),
            ("BEV $1,4", |i| matches!(i, MMixInstruction::BEV(1, _))),
            ("BACK: HALT\nBEVB $1,BACK", |i| {
                matches!(i, MMixInstruction::BEVB(1, _))
            }),
            ("BOD $1,4", |i| matches!(i, MMixInstruction::BOD(1, _))),
            ("BACK: HALT\nBODB $1,BACK", |i| {
                matches!(i, MMixInstruction::BODB(1, _))
            }),
            ("BP $1,4", |i| matches!(i, MMixInstruction::BP(1, _))),
            ("BACK: HALT\nBPB $1,BACK", |i| {
                matches!(i, MMixInstruction::BPB(1, _))
            }),
            ("BZ $1,4", |i| matches!(i, MMixInstruction::BZ(1, _))),
            ("BACK: HALT\nBZB $1,BACK", |i| {
                matches!(i, MMixInstruction::BZB(1, _))
            }),
        ];
        for (src, pred) in cases {
            assert_last_instruction_matches(src, pred);
        }
    }

    #[test]
    fn test_prefix_robust_pbranch_family() {
        // Same collision shape as the branch family above, one level up
        // (PBN/PBNB/PBNN/...), with the same backward-target requirement.
        let cases: &[(&str, InstructionPredicate)] = &[
            ("PBN $1,4", |i| matches!(i, MMixInstruction::PBN(1, _, _))),
            ("BACK: HALT\nPBNB $1,BACK", |i| {
                matches!(i, MMixInstruction::PBNB(1, _, _))
            }),
            ("PBNN $1,4", |i| matches!(i, MMixInstruction::PBNN(1, _, _))),
            ("BACK: HALT\nPBNNB $1,BACK", |i| {
                matches!(i, MMixInstruction::PBNNB(1, _, _))
            }),
            ("PBNP $1,4", |i| matches!(i, MMixInstruction::PBNP(1, _, _))),
            ("BACK: HALT\nPBNPB $1,BACK", |i| {
                matches!(i, MMixInstruction::PBNPB(1, _, _))
            }),
            ("PBNZ $1,4", |i| matches!(i, MMixInstruction::PBNZ(1, _, _))),
            ("BACK: HALT\nPBNZB $1,BACK", |i| {
                matches!(i, MMixInstruction::PBNZB(1, _, _))
            }),
            ("PBEV $1,4", |i| matches!(i, MMixInstruction::PBEV(1, _, _))),
            ("BACK: HALT\nPBEVB $1,BACK", |i| {
                matches!(i, MMixInstruction::PBEVB(1, _, _))
            }),
            ("PBOD $1,4", |i| matches!(i, MMixInstruction::PBOD(1, _, _))),
            ("BACK: HALT\nPBODB $1,BACK", |i| {
                matches!(i, MMixInstruction::PBODB(1, _, _))
            }),
            ("PBP $1,4", |i| matches!(i, MMixInstruction::PBP(1, _, _))),
            ("BACK: HALT\nPBPB $1,BACK", |i| {
                matches!(i, MMixInstruction::PBPB(1, _, _))
            }),
            ("PBZ $1,4", |i| matches!(i, MMixInstruction::PBZ(1, _, _))),
            ("BACK: HALT\nPBZB $1,BACK", |i| {
                matches!(i, MMixInstruction::PBZB(1, _, _))
            }),
        ];
        for (src, pred) in cases {
            assert_last_instruction_matches(src, pred);
        }
    }

    #[test]
    fn test_prefix_robust_shift_signed_vs_unsigned() {
        assert_first_instruction("SL $1,$2,$3", MMixInstruction::SL(1, 2, 3));
        assert_first_instruction("SLU $1,$2,$3", MMixInstruction::SLU(1, 2, 3));
        assert_first_instruction("SR $1,$2,$3", MMixInstruction::SR(1, 2, 3));
        assert_first_instruction("SRU $1,$2,$3", MMixInstruction::SRU(1, 2, 3));
        assert_first_instruction("SL $1,$2,7", MMixInstruction::SLI(1, 2, 7));
        assert_first_instruction("SLU $1,$2,7", MMixInstruction::SLUI(1, 2, 7));
        assert_first_instruction("SR $1,$2,7", MMixInstruction::SRI(1, 2, 7));
        assert_first_instruction("SRU $1,$2,7", MMixInstruction::SRUI(1, 2, 7));
        assert_first_instruction("SLI $1,$2,7", MMixInstruction::SLI(1, 2, 7));
        assert_first_instruction("SRUI $1,$2,7", MMixInstruction::SRUI(1, 2, 7));
    }

    #[test]
    fn test_prefix_robust_conditional_csn_csnn() {
        // CSN must not steal CSNN/CSNZ/CSNP. And the *I siblings must
        // route via the rri path (CSNI vs CSNNI etc.).
        assert_first_instruction("CSN $1,$2,$3", MMixInstruction::CSN(1, 2, 3));
        assert_first_instruction("CSNN $1,$2,$3", MMixInstruction::CSNN(1, 2, 3));
        assert_first_instruction("CSNZ $1,$2,$3", MMixInstruction::CSNZ(1, 2, 3));
        assert_first_instruction("CSNP $1,$2,$3", MMixInstruction::CSNP(1, 2, 3));
        assert_first_instruction("CSN $1,$2,7", MMixInstruction::CSNI(1, 2, 7));
        assert_first_instruction("CSNN $1,$2,7", MMixInstruction::CSNNI(1, 2, 7));
        assert_first_instruction("CSNZ $1,$2,7", MMixInstruction::CSNZI(1, 2, 7));
        assert_first_instruction("CSNP $1,$2,7", MMixInstruction::CSNPI(1, 2, 7));
        assert_first_instruction("CSNI $1,$2,7", MMixInstruction::CSNI(1, 2, 7));
        assert_first_instruction("CSNNI $1,$2,7", MMixInstruction::CSNNI(1, 2, 7));
    }

    #[test]
    fn test_prefix_robust_zero_or_set_zsn_zsnn() {
        assert_first_instruction("ZSN $1,$2,$3", MMixInstruction::ZSN(1, 2, 3));
        assert_first_instruction("ZSNN $1,$2,$3", MMixInstruction::ZSNN(1, 2, 3));
        assert_first_instruction("ZSNZ $1,$2,$3", MMixInstruction::ZSNZ(1, 2, 3));
        assert_first_instruction("ZSNP $1,$2,$3", MMixInstruction::ZSNP(1, 2, 3));
        assert_first_instruction("ZSN $1,$2,7", MMixInstruction::ZSNI(1, 2, 7));
        assert_first_instruction("ZSNN $1,$2,7", MMixInstruction::ZSNNI(1, 2, 7));
        assert_first_instruction("ZSNZ $1,$2,7", MMixInstruction::ZSNZI(1, 2, 7));
        assert_first_instruction("ZSNP $1,$2,7", MMixInstruction::ZSNPI(1, 2, 7));
    }

    // ---- Boundary value tests ---------------------------------------

    #[test]
    fn test_immediate_boundary_zero() {
        assert_first_instruction("ADD $1,$2,0", MMixInstruction::ADDI(1, 2, 0));
        assert_first_instruction("AND $1,$2,0", MMixInstruction::ANDI(1, 2, 0));
        assert_first_instruction("SR $1,$2,0", MMixInstruction::SRI(1, 2, 0));
    }

    #[test]
    fn test_immediate_boundary_max_decimal_255() {
        assert_first_instruction("ADD $1,$2,255", MMixInstruction::ADDI(1, 2, 255));
        assert_first_instruction("OR $1,$2,255", MMixInstruction::ORI(1, 2, 255));
        assert_first_instruction("ZSP $1,$2,255", MMixInstruction::ZSPI(1, 2, 255));
    }

    #[test]
    fn test_immediate_boundary_max_hex_ff() {
        assert_first_instruction("ADD $1,$2,#FF", MMixInstruction::ADDI(1, 2, 0xFF));
        assert_first_instruction("XOR $1,$2,#FF", MMixInstruction::XORI(1, 2, 0xFF));
        assert_first_instruction("CSN $1,$2,#FF", MMixInstruction::CSNI(1, 2, 0xFF));
    }

    #[test]
    fn test_immediate_boundary_overflow_decimal_256() {
        assert_parse_error_contains("ADD $1,$2,256", "out of range 0..255");
        assert_parse_error_contains("AND $1,$2,256", "out of range 0..255");
        assert_parse_error_contains("SRU $1,$2,256", "out of range 0..255");
    }

    #[test]
    fn test_immediate_boundary_overflow_hex_100() {
        assert_parse_error_contains("ADD $1,$2,#100", "out of range 0..255");
    }

    #[test]
    fn test_immediate_boundary_overflow_large_value() {
        // A genuinely large value must not silently truncate; it must
        // be rejected by the auto-immediate range check.
        assert_parse_error_contains("ADD $1,$2,#10000", "out of range 0..255");
        assert_parse_error_contains("ADD $1,$2,1000000", "out of range 0..255");
    }

    #[test]
    fn test_immediate_boundary_negative_rejected_in_auto() {
        // The auto path is strict 0..=255. Negative literals (which
        // wrap to large u64s) must be rejected. The explicit *I path
        // keeps its silent-wrap behavior — see
        // `test_parse_negative_literal_8bit_wrap`.
        assert_parse_error_contains("ADD $1,$2,-1", "out of range 0..255");
        assert_parse_error_contains("AND $1,$2,-128", "out of range 0..255");
    }

    #[test]
    fn test_immediate_register_max_255() {
        // $255 as Z must remain a register reference, not get
        // confused with the immediate 255.
        assert_first_instruction("ADD $1,$2,$255", MMixInstruction::ADD(1, 2, 255));
        assert_first_instruction("AND $1,$2,$255", MMixInstruction::AND(1, 2, 255));
    }

    #[test]
    fn test_immediate_char_literal() {
        assert_first_instruction("ADD $1,$2,'A'", MMixInstruction::ADDI(1, 2, 65));
        assert_first_instruction("AND $1,$2,'\\n'", MMixInstruction::ANDI(1, 2, 10));
        assert_first_instruction("OR $1,$2,'\\0'", MMixInstruction::ORI(1, 2, 0));
    }

    // ---- Symbol/label resolution at the Z slot ----------------------

    #[test]
    fn test_symbol_z_constant_in_range() {
        assert_first_instruction("K IS 0\nADD $1,$2,K", MMixInstruction::ADDI(1, 2, 0));
        assert_first_instruction("K IS 255\nAND $1,$2,K", MMixInstruction::ANDI(1, 2, 255));
        assert_first_instruction("K IS 42\nCSZ $1,$2,K", MMixInstruction::CSZI(1, 2, 42));
    }

    #[test]
    fn test_symbol_z_constant_out_of_range() {
        assert_parse_error_contains("K IS 256\nADD $1,$2,K", "out of range 0..255");
        assert_parse_error_contains("K IS 1000\nAND $1,$2,K", "out of range 0..255");
    }

    #[test]
    // NEG's immediate spellings carry Z as an 8-bit field: an operand above
    // 255 is an error rather than a silent truncation, whether it is written
    // as a literal or resolved from a symbol.
    fn test_neg_immediate_spelling_range_checks_its_z() {
        assert_parse_error_contains("NEGI $1,0,#300", "out of range 0..255");
        assert_parse_error_contains("NEGUI $1,0,#300", "out of range 0..255");
        assert_parse_error_contains("BigC IS #300\nNEGI $1,0,BigC", "out of range 0..255");
        assert_parse_error_contains("BigC IS #300\nNEGUI $1,0,BigC", "out of range 0..255");
        assert_parse_error_contains("NEGI $1,0,-1", "out of range 0..255");
        assert_parse_error_contains("NEGUI $1,0,-1", "out of range 0..255");
        assert_first_instruction("NEGI $1,0,5", MMixInstruction::NEGI(1, 0, 5));
        assert_first_instruction("NEGUI $1,0,5", MMixInstruction::NEGUI(1, 0, 5));
        assert_first_instruction(
            "SmallC IS 5\nNEGI $1,0,SmallC",
            MMixInstruction::NEGI(1, 0, 5),
        );
    }

    #[test]
    fn test_symbol_z_register_alias_zero() {
        assert_first_instruction("Z IS $0\nADD $1,$2,Z", MMixInstruction::ADD(1, 2, 0));
    }

    #[test]
    fn test_symbol_z_register_alias_max() {
        assert_first_instruction("M IS $255\nAND $1,$2,M", MMixInstruction::AND(1, 2, 255));
    }

    #[test]
    fn test_symbol_z_label_address_out_of_range() {
        // A label whose address is above 255 must error rather than
        // silently truncate, even though it grammatically parses as a
        // bare identifier in the Z slot.
        let src = "\
LOC #200
Foo  OCTA 0
Main ADD $1,$2,Foo
";
        assert_parse_error_contains(src, "out of range 0..255");
    }

    #[test]
    fn test_symbol_z_undefined_errors() {
        assert_parse_error_contains("ADD $1,$2,Nope", "Undefined symbol");
        assert_parse_error_contains("AND $1,$2,Nope", "Undefined symbol");
    }

    // ---- Cross-family non-interference ------------------------------
    // Multiple base mnemonics from different families in one source —
    // each must route to its own family's auto rule.

    #[test]
    fn test_cross_family_routing_in_one_program() {
        let src = "\
ADD  $1,$2,5
AND  $3,$4,7
SR   $5,$6,3
BDIF $7,$8,9
CSZ  $1,$2,1
ZSP  $3,$4,2
";
        let mut asm = MMixAssembler::new(src, "<test>");
        asm.parse().unwrap();
        assert_eq!(
            asm.instructions
                .iter()
                .map(|(_, i)| i.clone())
                .collect::<Vec<_>>(),
            vec![
                MMixInstruction::ADDI(1, 2, 5),
                MMixInstruction::ANDI(3, 4, 7),
                MMixInstruction::SRI(5, 6, 3),
                MMixInstruction::BDIFI(7, 8, 9),
                MMixInstruction::CSZI(1, 2, 1),
                MMixInstruction::ZSPI(3, 4, 2),
            ]
        );
    }

    // ---- Existing-test perturbation ---------------------------------
    // Pick a handful of pre-existing register-form assertions and add
    // matching auto-immediate assertions so that any future grammar
    // change that breaks the auto path will be caught alongside the
    // original tests.

    #[test]
    fn test_perturbation_and_xor_or() {
        // Mirrors test_parse_and / test_parse_xor / test_parse_or but
        // uses the auto-immediate path.
        assert_first_instruction("AND $1,$2,#FF", MMixInstruction::ANDI(1, 2, 0xFF));
        assert_first_instruction("XOR $5,$6,#0F", MMixInstruction::XORI(5, 6, 0x0F));
        assert_first_instruction("OR $10,$20,#80", MMixInstruction::ORI(10, 20, 0x80));
    }

    #[test]
    fn test_perturbation_bitfiddle_family() {
        // Mirrors test_parse_bdif/wdif/tdif/odif/sadd/mor/mxor.
        assert_first_instruction("BDIF $1,$2,#10", MMixInstruction::BDIFI(1, 2, 0x10));
        assert_first_instruction("WDIF $1,$2,100", MMixInstruction::WDIFI(1, 2, 100));
        assert_first_instruction("TDIF $1,$2,50", MMixInstruction::TDIFI(1, 2, 50));
        assert_first_instruction("ODIF $1,$2,255", MMixInstruction::ODIFI(1, 2, 255));
        assert_first_instruction("SADD $1,$2,0", MMixInstruction::SADDI(1, 2, 0));
        assert_first_instruction("MOR $1,$2,128", MMixInstruction::MORI(1, 2, 128));
        assert_first_instruction("MXOR $1,$2,64", MMixInstruction::MXORI(1, 2, 64));
    }

    #[test]
    fn test_perturbation_shift_family() {
        // Mirrors test_parse_sl / sli / slu / slui / sr / sri / sru / srui.
        assert_first_instruction("SL $3,$1,8", MMixInstruction::SLI(3, 1, 8));
        assert_first_instruction("SLU $1,$2,16", MMixInstruction::SLUI(1, 2, 16));
        assert_first_instruction("SR $1,$2,4", MMixInstruction::SRI(1, 2, 4));
        assert_first_instruction("SRU $1,$2,32", MMixInstruction::SRUI(1, 2, 32));
    }

    // ---- Comprehensive byte-identical regression --------------------
    // Every base mnemonic in the six in-scope families paired with its
    // explicit *I sibling. This is the strongest cross-validation that
    // the auto path produces exactly the same encoded bytes as the
    // legacy path.

    #[test]
    fn test_byte_identical_regression_all_families() {
        let pairs: &[(&str, &str)] = &[
            // Arithmetic
            ("ADD $1,$2,5", "ADDI $1,$2,5"),
            ("ADDU $1,$2,5", "ADDUI $1,$2,5"),
            ("2ADDU $1,$2,5", "2ADDUI $1,$2,5"),
            ("4ADDU $1,$2,5", "4ADDUI $1,$2,5"),
            ("8ADDU $1,$2,5", "8ADDUI $1,$2,5"),
            ("16ADDU $1,$2,5", "16ADDUI $1,$2,5"),
            ("SUB $1,$2,5", "SUBI $1,$2,5"),
            ("SUBU $1,$2,5", "SUBUI $1,$2,5"),
            ("MUL $1,$2,5", "MULI $1,$2,5"),
            ("MULU $1,$2,5", "MULUI $1,$2,5"),
            ("DIV $1,$2,5", "DIVI $1,$2,5"),
            ("DIVU $1,$2,5", "DIVUI $1,$2,5"),
            ("CMP $1,$2,5", "CMPI $1,$2,5"),
            ("CMPU $1,$2,5", "CMPUI $1,$2,5"),
            // Bitwise
            ("AND $1,$2,5", "ANDI $1,$2,5"),
            ("OR $1,$2,5", "ORI $1,$2,5"),
            ("XOR $1,$2,5", "XORI $1,$2,5"),
            ("ANDN $1,$2,5", "ANDNI $1,$2,5"),
            ("ORN $1,$2,5", "ORNI $1,$2,5"),
            ("NAND $1,$2,5", "NANDI $1,$2,5"),
            ("NOR $1,$2,5", "NORI $1,$2,5"),
            ("NXOR $1,$2,5", "NXORI $1,$2,5"),
            ("MUX $1,$2,5", "MUXI $1,$2,5"),
            // Bit-fiddle
            ("BDIF $1,$2,5", "BDIFI $1,$2,5"),
            ("WDIF $1,$2,5", "WDIFI $1,$2,5"),
            ("TDIF $1,$2,5", "TDIFI $1,$2,5"),
            ("ODIF $1,$2,5", "ODIFI $1,$2,5"),
            ("SADD $1,$2,5", "SADDI $1,$2,5"),
            ("MOR $1,$2,5", "MORI $1,$2,5"),
            ("MXOR $1,$2,5", "MXORI $1,$2,5"),
            // Shift
            ("SL $1,$2,5", "SLI $1,$2,5"),
            ("SLU $1,$2,5", "SLUI $1,$2,5"),
            ("SR $1,$2,5", "SRI $1,$2,5"),
            ("SRU $1,$2,5", "SRUI $1,$2,5"),
            // Conditional set
            ("CSN $1,$2,5", "CSNI $1,$2,5"),
            ("CSZ $1,$2,5", "CSZI $1,$2,5"),
            ("CSP $1,$2,5", "CSPI $1,$2,5"),
            ("CSOD $1,$2,5", "CSODI $1,$2,5"),
            ("CSNN $1,$2,5", "CSNNI $1,$2,5"),
            ("CSNZ $1,$2,5", "CSNZI $1,$2,5"),
            ("CSNP $1,$2,5", "CSNPI $1,$2,5"),
            ("CSEV $1,$2,5", "CSEVI $1,$2,5"),
            // Zero or set
            ("ZSN $1,$2,5", "ZSNI $1,$2,5"),
            ("ZSZ $1,$2,5", "ZSZI $1,$2,5"),
            ("ZSP $1,$2,5", "ZSPI $1,$2,5"),
            ("ZSOD $1,$2,5", "ZSODI $1,$2,5"),
            ("ZSNN $1,$2,5", "ZSNNI $1,$2,5"),
            ("ZSNZ $1,$2,5", "ZSNZI $1,$2,5"),
            ("ZSNP $1,$2,5", "ZSNPI $1,$2,5"),
            ("ZSEV $1,$2,5", "ZSEVI $1,$2,5"),
        ];

        for (auto_src, explicit_src) in pairs {
            let mut auto_asm = MMixAssembler::new(auto_src, "<auto>");
            auto_asm
                .parse()
                .unwrap_or_else(|e| panic!("auto src {auto_src:?} failed: {e}"));
            let mut explicit_asm = MMixAssembler::new(explicit_src, "<explicit>");
            explicit_asm
                .parse()
                .unwrap_or_else(|e| panic!("explicit src {explicit_src:?} failed: {e}"));
            let auto_bytes = auto_asm.encode_instruction_bytes(&auto_asm.instructions[0].1);
            let explicit_bytes =
                explicit_asm.encode_instruction_bytes(&explicit_asm.instructions[0].1);
            assert_eq!(
                auto_bytes,
                explicit_bytes,
                "byte mismatch: auto {auto_src:?} -> {:?} {:?} vs explicit {explicit_src:?} -> {:?} {:?}",
                auto_asm.instructions[0].1,
                auto_bytes,
                explicit_asm.instructions[0].1,
                explicit_bytes
            );
        }
    }

    // ---- Sanity: these *I spellings stay unchanged for negatives -----
    // Lock in that `test_parse_negative_literal_8bit_wrap`'s policy
    // (silent wrap of -1 to 0xFF) is preserved for the spellings named
    // below while the auto path rejects the same input. `NEGI`/`NEGUI`
    // range-check their Z and are the exception, pinned in
    // `test_neg_immediate_spelling_range_checks_its_z`.
    #[test]
    fn test_explicit_i_negative_still_wraps() {
        assert_first_instruction("ADDI $1,$2,-1", MMixInstruction::ADDI(1, 2, 0xFF));
        assert_first_instruction("ANDI $1,$2,-1", MMixInstruction::ANDI(1, 2, 0xFF));
        assert_first_instruction("SLUI $1,$2,-1", MMixInstruction::SLUI(1, 2, 0xFF));
        // Auto path rejects:
        assert_parse_error_contains("ADD $1,$2,-1", "out of range 0..255");
    }

    // ---- Source-level debug info (SourceLoc / source_loc / addr_for_line /
    // source_text): pc.1 of the mmixdb effort. ----------------------------

    /// Line fidelity across a labeled `debug` directive: the pinning test.
    /// Mirrors `examples/hello_world.mms`'s shape (a labeled `debug "..."`
    /// line, then a labeled instruction a couple of lines down). Reverting
    /// the `preprocess_debug` line-count-preserving fix (Step 1) -- i.e.
    /// restoring the old two-line label/PUSHJ expansion -- shifts every
    /// following line by one and makes this assertion fail; that was
    /// verified by hand before landing (see the prompt's report).
    #[test]
    fn test_debug_directive_preserves_line_fidelity() {
        let lines = [
            "\tLOC\tData_Segment",
            "\tGREG\t@",
            "Text\tBYTE\t\"Hello world!\",'\\n',0",
            "",
            "\tLOC\t#100",
            "",
            "Main\tdebug \"Version 0.1: Hello World Example\"",
            "Start\tLDA\t$255,Text",
            "\tTRAP\t0,Fputs,StdOut",
            "\tTRAP\t0,Halt,0",
        ];
        let lda_line = lines.iter().position(|l| l.contains("LDA")).unwrap() + 1;
        let source = lines.join("\n");

        let mut asm = MMixAssembler::new(&source, "hello_world.mms");
        asm.parse().unwrap();

        let lda_addr = *asm.labels.get("Start").expect("Start label defined");
        let loc = asm
            .source_loc(lda_addr)
            .expect("LDA's address should have a source location");
        assert_eq!(loc.file, "hello_world.mms");
        assert_eq!(loc.line, lda_line, "LDA must report its ORIGINAL line");
    }

    /// Inverse round-trip: `addr_for_line` returns the same address
    /// `source_loc` mapped back from.
    #[test]
    fn test_addr_for_line_round_trips_with_source_loc() {
        let source = "Main\tdebug \"hi\"\nStart\tLDA\t$255,Start\n\tTRAP\t0,Halt,0\n";

        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse().unwrap();

        let lda_addr = *asm.labels.get("Start").unwrap();
        let loc = asm.source_loc(lda_addr).unwrap();
        assert_eq!(
            asm.addr_for_line(&loc.file, loc.line),
            Some(lda_addr),
            "addr_for_line must invert source_loc"
        );
    }

    /// `source_text` returns the ORIGINAL line (the `debug` directive as the
    /// user wrote it), not the preprocessed `PUSHJ` text.
    #[test]
    fn test_source_text_returns_original_not_preprocessed() {
        let source = "Main\tdebug \"hi\"\nStart\tLDA\t$255,Start\n";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse().unwrap();

        let text = asm.source_text("<test>", 1).expect("line 1 exists");
        assert!(
            text.contains("debug"),
            "expected original text, got {text:?}"
        );
        assert!(
            !text.contains("PUSHJ"),
            "source_text must not leak preprocessed text, got {text:?}"
        );

        let lda_text = asm.source_text("<test>", 2).expect("line 2 exists");
        assert!(lda_text.contains("LDA"));
    }

    /// Compiler-generated code (the appended debug-subroutine block) has no
    /// user source line.
    #[test]
    fn test_generated_debug_subroutine_has_no_source_loc() {
        let source = "Main\tdebug \"hi\"\nStart\tLDA\t$255,Start\n";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse().unwrap();

        let debug_sub_addr = *asm
            .labels
            .get("DbgStr_0001")
            .expect("generated debug subroutine label exists");
        assert_eq!(
            asm.source_loc(debug_sub_addr),
            None,
            "generated code must not map to a user source line"
        );
    }

    /// A syntax error after a `debug` line must name the ORIGINAL line, not
    /// the preprocessed one the landing pad shifts it to.
    #[test]
    fn test_syntax_error_after_a_debug_line_reports_the_original_line() {
        let source = "\
\tLOC\t#100
Main\tdebug\t\"hi\"
\tSET\t$1,7
\tFLOT\t$1,$2,$3
";
        let mut asm = MMixAssembler::new(source, "<test>");
        let err = asm
            .parse()
            .expect_err("FLOT $1,$2,$3 must still fail to parse");
        assert_eq!(
            err, "<test>:4:12: syntax error: expected EOI",
            "must report original line 4, not the preprocessed line the \
             debug expansion's landing pad shifts it to"
        );
    }

    /// A symbol redefined after two `debug` lines reports both the current
    /// and the first-definition site at their ORIGINAL lines.
    #[test]
    fn test_redefinition_after_two_debug_lines_reports_original_lines() {
        let source = "\
\tLOC\t#100
Main\tdebug\t\"hi\"
\tdebug\t\"ho\"
Foo\tIS\t1
\tSET\t$1,7
Foo\tIS\t2
";
        let mut asm = MMixAssembler::new(source, "<test>");
        let err = asm
            .parse()
            .expect_err("redefining Foo must still be rejected");
        assert_eq!(
            err, "<test>:6: symbol 'Foo' redefined (first defined at <test>:4)",
            "both sites must report their ORIGINAL lines, not the \
             preprocessed lines two debug expansions shift them to"
        );
    }

    /// A data directive that emits multiple words maps every emitted address
    /// to the same source line, and `addr_for_line` returns the lowest one.
    /// Checked for `BYTE` (1-byte units) and `OCTA` (8-byte units), so the
    /// invariant is shown to hold independent of unit width.
    #[test]
    fn test_multi_word_data_directive_maps_to_one_line() {
        let source = "Data\tBYTE\t1,2,3\nWide\tOCTA\t1,2,3\n";
        let mut asm = MMixAssembler::new(source, "<test>");
        asm.parse().unwrap();

        let base_addr = *asm.labels.get("Data").unwrap();
        for offset in 0..3 {
            let loc = asm
                .source_loc(base_addr + offset)
                .unwrap_or_else(|| panic!("no source_loc at offset {offset}"));
            assert_eq!(loc.line, 1);
        }
        assert_eq!(asm.addr_for_line("<test>", 1), Some(base_addr));

        let wide_addr = *asm.labels.get("Wide").unwrap();
        for offset in 0..3 {
            let addr = wide_addr + offset * 8;
            let loc = asm
                .source_loc(addr)
                .unwrap_or_else(|| panic!("no source_loc at unit {offset}"));
            assert_eq!(loc.line, 2);
        }
        assert_eq!(asm.addr_for_line("<test>", 2), Some(wide_addr));
    }

    /// A stack program with both a data and a text region, so `source_loc`
    /// is asked about an address in the gap between them.
    const TWO_REGION_PROGRAM: &str = "\
        LOC     Data_Segment
Cells   OCTA    0
        OCTA    0
        OCTA    0
Sp      GREG    Cells

        LOC     #100
Main    SETI    $1,7
        STOI    $1,Sp,0
        ADDUI   Sp,Sp,8
        SETI    $1,35
        STOI    $1,Sp,0
        LDOI    $2,Sp,0
        SUBUI   Sp,Sp,8
        LDOI    $3,Sp,0
        ADDU    $255,$2,$3
        TRAP    0,Halt,0
";

    /// `SETI $X,imm` expands to four tetras. Every address in the expansion
    /// belongs to the statement that emitted it, and the address just past
    /// the last text entry belongs to nothing -- the data region lies far
    /// above it, and a lookup that ran to the end of the image would hand
    /// that whole gap to the last text line.
    #[test]
    fn test_source_loc_covers_an_expansion_and_stops_at_its_end() {
        let mut asm = MMixAssembler::new(TWO_REGION_PROGRAM, "stack.mms");
        asm.parse().unwrap();

        let main = *asm.labels.get("Main").unwrap();
        assert_eq!(main, 0x100);
        for addr in [0x100, 0x104, 0x108, 0x10c] {
            let loc = asm
                .source_loc(addr)
                .unwrap_or_else(|| panic!("no source_loc at 0x{addr:x}"));
            assert_eq!(loc.line, 8, "0x{addr:x} is inside line 8's SETI");
        }
        assert_eq!(asm.source_loc(0x110).map(|loc| loc.line), Some(9));

        // One tetra past the TRAP that ends the text region, and far below
        // the data region.
        assert_eq!(asm.source_loc(0x140), None);
    }

    /// The data region keeps its own lines; the text region above it does
    /// not bleed into the gap, nor the data region below.
    #[test]
    fn test_source_loc_maps_the_data_region_independently() {
        let mut asm = MMixAssembler::new(TWO_REGION_PROGRAM, "stack.mms");
        asm.parse().unwrap();

        let cells = *asm.labels.get("Cells").unwrap();
        assert!(cells >= 0x2000_0000_0000_0000);
        assert_eq!(asm.source_loc(cells).map(|loc| loc.line), Some(2));
        assert_eq!(asm.source_loc(cells + 7).map(|loc| loc.line), Some(2));
        assert_eq!(asm.source_loc(cells + 8).map(|loc| loc.line), Some(3));
        assert_eq!(asm.source_loc(cells + 24), None);
    }

    /// Duplicate-name translation units: reverse lookups (`addr_for_line`,
    /// `source_text`) resolve to the FIRST unit with that filename in
    /// command-line order, while `source_loc` (keyed by address) stays
    /// unambiguous regardless.
    #[test]
    fn test_source_text_resolves_duplicate_filename_to_first_unit() {
        let mut asm = MMixAssembler::new("First\tHALT\n", "dup.mms");
        asm.add_source("Second\tHALT\n", "dup.mms");
        asm.parse().unwrap();

        let text = asm.source_text("dup.mms", 1).unwrap();
        assert!(text.contains("First"));
    }

    // --- resolve_includes (INCLUDE directive) ---

    /// Build an in-memory `read` closure keyed by exact `PathBuf`s, so tests
    /// stay hermetic (no real filesystem access).
    fn fixture_reader(
        files: Vec<(&str, &str)>,
    ) -> impl Fn(&std::path::Path) -> std::io::Result<String> {
        let map: HashMap<std::path::PathBuf, String> = files
            .into_iter()
            .map(|(p, s)| (std::path::PathBuf::from(p), s.to_string()))
            .collect();
        move |p: &std::path::Path| {
            map.get(p).cloned().ok_or_else(|| {
                std::io::Error::new(std::io::ErrorKind::NotFound, "no such fixture file")
            })
        }
    }

    #[test]
    fn resolve_includes_single_include_inserts_a_unit() {
        let reader = fixture_reader(vec![("lib.mms", "OCTA 1\n")]);
        let units = MMixAssembler::resolve_includes(
            "INCLUDE lib.mms\nOCTA 2\n",
            "root.mms",
            std::path::Path::new(""),
            &reader,
        )
        .unwrap();

        assert_eq!(units.len(), 2);
        assert_eq!(units[0].0, "lib.mms");
        assert!(units[0].1.contains("OCTA 1"));
        assert_eq!(units[1].0, "root.mms");
        assert!(units[1].1.contains("OCTA 2"));
    }

    #[test]
    fn resolve_includes_filename_fidelity() {
        // The included unit's filename must be the included file's own path,
        // NOT the including (root) file's name -- the property text-splicing
        // could never give, since a spliced file has no filename of its own.
        let reader = fixture_reader(vec![("lib.mms", "OCTA 1\n")]);
        let units = MMixAssembler::resolve_includes(
            "INCLUDE lib.mms\nOCTA 2\n",
            "root.mms",
            std::path::Path::new(""),
            &reader,
        )
        .unwrap();

        assert_eq!(units[0].0, "lib.mms");
        assert_ne!(units[0].0, "root.mms");
    }

    #[test]
    fn resolve_includes_pads_line_numbers_after_an_include() {
        let reader = fixture_reader(vec![("lib.mms", "OCTA 1\n")]);
        let units = MMixAssembler::resolve_includes(
            "% a\nINCLUDE lib.mms\nBYTE 0\n",
            "root.mms",
            std::path::Path::new(""),
            &reader,
        )
        .unwrap();

        // Trailing host segment: `BYTE 0` was on absolute line 3, so it must
        // be preceded by exactly 2 padding newlines.
        let host_segment = &units.last().unwrap().1;
        assert_eq!(host_segment.matches('\n').count() - 1, 2);
        assert!(host_segment.starts_with("\n\nBYTE 0"));

        // Parse it through the real assembler and confirm the reported line
        // number is the ABSOLUTE line 3, not the padded segment's line 1.
        let mut asm = MMixAssembler::new(&units[0].1, &units[0].0);
        for (name, src) in units.iter().skip(1) {
            asm.add_source(src, name);
        }
        asm.parse().unwrap();
        // `lib.mms`'s `OCTA 1` occupies address 0..8, so `BYTE 0` -- at
        // absolute line 3 thanks to padding -- lands at address 8.
        assert_eq!(asm.addr_for_line("root.mms", 3), Some(8));
    }

    #[test]
    fn resolve_includes_nested_relative_resolution() {
        let reader = fixture_reader(vec![
            ("a/sub/b.mms", "INCLUDE c.mms\nOCTA 2\n"),
            ("a/sub/c.mms", "OCTA 3\n"),
        ]);
        let units = MMixAssembler::resolve_includes(
            "INCLUDE sub/b.mms\nOCTA 1\n",
            "a/root.mms",
            std::path::Path::new("a"),
            &reader,
        )
        .unwrap();

        let c_unit = units
            .iter()
            .find(|(name, _)| name.contains("c.mms"))
            .expect("c.mms unit present");
        assert_eq!(c_unit.0, "a/sub/c.mms");
        assert!(c_unit.1.contains("OCTA 3"));
    }

    #[test]
    fn resolve_includes_cycle_is_an_error() {
        let reader = fixture_reader(vec![
            ("a.mms", "INCLUDE b.mms\n"),
            ("b.mms", "INCLUDE a.mms\n"),
        ]);
        let err = MMixAssembler::resolve_includes(
            "INCLUDE a.mms\n",
            "driver.mms",
            std::path::Path::new(""),
            &reader,
        )
        .unwrap_err();

        assert!(err.contains("cycle"));
        assert!(err.contains("a.mms"));
        assert!(err.contains("b.mms"));
    }

    #[test]
    fn resolve_includes_missing_file_is_an_error_not_a_panic() {
        let reader = fixture_reader(vec![]);
        let err = MMixAssembler::resolve_includes(
            "INCLUDE missing.mms\n",
            "root.mms",
            std::path::Path::new(""),
            &reader,
        )
        .unwrap_err();

        assert!(err.contains("missing.mms"));
    }

    #[test]
    fn resolve_includes_passthrough_preserves_content_with_no_include() {
        let reader = fixture_reader(vec![]);
        let source = "OCTA 1\nOCTA 2";
        let units =
            MMixAssembler::resolve_includes(source, "root.mms", std::path::Path::new(""), &reader)
                .unwrap();

        assert_eq!(units.len(), 1);
        assert_eq!(units[0].0, "root.mms");
        assert_eq!(units[0].1, source);
    }

    #[test]
    fn resolve_includes_recognizes_comment_case_and_leading_dot() {
        let reader = fixture_reader(vec![("lib.mms", "OCTA 1\n")]);

        let lower_with_comment = MMixAssembler::resolve_includes(
            ".include lib.mms  % pull it in\n",
            "root.mms",
            std::path::Path::new(""),
            &reader,
        )
        .unwrap();
        let quoted = MMixAssembler::resolve_includes(
            "INCLUDE \"lib.mms\"\n",
            "root.mms",
            std::path::Path::new(""),
            &reader,
        )
        .unwrap();

        assert_eq!(lower_with_comment.len(), 1);
        assert_eq!(quoted.len(), 1);
        assert_eq!(lower_with_comment[0].1, quoted[0].1);
        assert!(quoted[0].1.contains("OCTA 1"));
    }
}