daaki-imap 0.1.0

//! IMAP command encoder.
//!
//! Serializes [`Command`] values into bytes suitable for sending to the server.
//! Each command is prefixed with a unique tag (e.g. `A001`, `A002`, ...).
//!
//! Command syntax is defined in RFC 3501 Section 6 / RFC 9051 Section 6.
//! String encoding (quoted vs literal) follows RFC 3501 Section 9 / RFC 9051 Section 9.

use bytes::BytesMut;

use crate::types::{Command, MailboxAttribute, QresyncParams};

/// Validates that a sequence set matches RFC 3501 Section 9 formal syntax:
/// `sequence-set = (seq-number / seq-range) *("," sequence-set)`
/// where `seq-number = nz-number / "*"` and `seq-range = seq-number ":" seq-number`
/// and `nz-number = digit-nz *DIGIT` (must not start with '0').
///
/// Per RFC 3501 Section 9, `nz-number` is a non-zero unsigned 32-bit integer
/// (0 < n < 4,294,967,296), so each numeric element must parse as a valid `u32`
/// and must not be zero.
fn validate_sequence_set(s: &str) -> bool {
    if s.is_empty() {
        return false;
    }
    s.split(',').all(|part| {
        if part.is_empty() {
            return false;
        }
        // RFC 5182 Section 2: "$" references saved search results.
        // RFC 5182 Section 5 extends grammar: sequence-set =/ seq-last-command.
        // "$" is valid as a standalone component in comma-separated lists
        // but cannot form a range (it is not a seq-number).
        if part == "$" {
            return true;
        }
        part.split(':').all(|num| {
            if num == "*" {
                return true;
            }
            // Must be non-empty, all digits, and not start with '0'.
            if num.is_empty() || num.starts_with('0') || !num.chars().all(|c| c.is_ascii_digit()) {
                return false;
            }
            // RFC 3501 Section 9: nz-number is a u32 (0 < n < 4,294,967,296).
            // Reject values that overflow u32.
            num.parse::<u32>().is_ok()
        }) && part.matches(':').count() <= 1
    })
}

/// Validate a sequence set, returning a protocol error if invalid.
///
/// RFC 3501 Section 9: `sequence-set = (seq-number / seq-range) *("," sequence-set)`.
fn validate_sequence_set_or_err(s: &str) -> Result<(), crate::Error> {
    if !validate_sequence_set(s) {
        return Err(crate::Error::Protocol(format!(
            "invalid sequence set per RFC 3501 Section 9: {s:?}"
        )));
    }
    Ok(())
}

/// Maximum value for `mod-sequence-value` and `mod-sequence-valzer`
/// (RFC 7162 Section 7): a positive unsigned 63-bit integer.
const MOD_SEQ_MAX: u64 = i64::MAX as u64;

/// Validates a `mod-sequence-value` per RFC 7162 Section 7:
/// `mod-sequence-value = 1*DIGIT` where `1 <= n <= 9,223,372,036,854,775,807`.
///
/// Used for CHANGEDSINCE (RFC 7162 Section 3.1.4.1) and QRESYNC `mod_seq`
/// (RFC 7162 Section 3.2.5.2).
fn validate_mod_sequence_value(val: u64, context: &str) -> Result<(), crate::Error> {
    if val == 0 {
        return Err(crate::Error::Protocol(format!(
            "{context} mod-sequence-value must be >= 1 per RFC 7162 Section 7, got 0"
        )));
    }
    if val > MOD_SEQ_MAX {
        return Err(crate::Error::Protocol(format!(
            "{context} mod-sequence-value must be <= {MOD_SEQ_MAX} per RFC 7162 Section 7, got {val}"
        )));
    }
    Ok(())
}

/// Validates a `mod-sequence-valzer` per RFC 7162 Section 7:
/// `mod-sequence-valzer = "0" / mod-sequence-value` where `0 <= n <= 9,223,372,036,854,775,807`.
///
/// Used for UNCHANGEDSINCE (RFC 7162 Section 3.1.3).
fn validate_mod_sequence_valzer(val: u64, context: &str) -> Result<(), crate::Error> {
    if val > MOD_SEQ_MAX {
        return Err(crate::Error::Protocol(format!(
            "{context} mod-sequence-valzer must be <= {MOD_SEQ_MAX} per RFC 7162 Section 7, got {val}"
        )));
    }
    Ok(())
}

/// Encode the CHANGEDSINCE fetch modifier (RFC 7162 Section 3.1.4.1),
/// optionally followed by VANISHED (RFC 7162 Section 3.2.6).
///
/// Emits ` (CHANGEDSINCE <modseq>)` or ` (CHANGEDSINCE <modseq> VANISHED)`.
/// Validates that `modseq` satisfies the `mod-sequence-value` production
/// (>= 1, <= `i64::MAX`).
fn encode_changedsince_modifier(
    buf: &mut BytesMut,
    modseq: u64,
    vanished: bool,
) -> Result<(), crate::Error> {
    validate_mod_sequence_value(modseq, "CHANGEDSINCE")?;
    buf.extend_from_slice(b" (CHANGEDSINCE ");
    buf.extend_from_slice(modseq.to_string().as_bytes());
    // RFC 7162 Section 3.2.6: VANISHED modifier appended in the same
    // parenthesized fetch modifier list as CHANGEDSINCE.
    if vanished {
        buf.extend_from_slice(b" VANISHED");
    }
    buf.extend_from_slice(b")");
    Ok(())
}

/// Encodes an IMAP command into the provided buffer, prefixed with the given tag.
///
/// Appends CRLF. APPEND is handled separately by `ImapConnection::append()`
/// because it requires literal synchronization.
/// Tag-command format per RFC 3501 Section 2.2.1 / RFC 9051 Section 2.2.1.
#[allow(clippy::too_many_lines)]
pub(crate) fn encode_command(
    buf: &mut BytesMut,
    tag: &str,
    command: &Command,
) -> Result<(), crate::Error> {
    match command {
        Command::Login { user, pass } => {
            encode_login(buf, tag, user, pass);
        }
        Command::Authenticate {
            mechanism,
            initial_response,
        } => {
            encode_authenticate(buf, tag, mechanism, initial_response.as_deref());
        }
        // RFC 3501 Section 6.2.1 / RFC 9051 Section 6.2.1
        Command::StartTls => {
            encode_simple(buf, tag, "STARTTLS");
        }
        // RFC 3501 Section 6.1.3 / RFC 9051 Section 6.1.3
        Command::Logout => {
            encode_simple(buf, tag, "LOGOUT");
        }
        Command::List { reference, pattern } => {
            encode_two_quoted_args(buf, tag, "LIST", reference, pattern);
        }
        Command::ListStatus {
            reference,
            pattern,
            status_items,
        } => {
            encode_list_status(buf, tag, reference, pattern, status_items);
        }
        Command::Select {
            mailbox,
            condstore,
            qresync,
        } => {
            encode_select_or_examine(buf, tag, "SELECT", mailbox, *condstore, qresync.as_ref())?;
        }
        Command::Examine {
            mailbox,
            condstore,
            qresync,
        } => {
            encode_select_or_examine(buf, tag, "EXAMINE", mailbox, *condstore, qresync.as_ref())?;
        }
        Command::Create { mailbox } => {
            encode_mailbox_cmd(buf, tag, "CREATE", mailbox);
        }
        Command::CreateSpecialUse {
            mailbox,
            special_use,
        } => {
            encode_create_special_use(buf, tag, mailbox, special_use);
        }
        Command::Delete { mailbox } => {
            encode_mailbox_cmd(buf, tag, "DELETE", mailbox);
        }
        Command::Rename { mailbox, new_name } => {
            encode_two_quoted_args(buf, tag, "RENAME", mailbox, new_name);
        }
        Command::Subscribe { mailbox } => {
            encode_mailbox_cmd(buf, tag, "SUBSCRIBE", mailbox);
        }
        Command::Unsubscribe { mailbox } => {
            encode_mailbox_cmd(buf, tag, "UNSUBSCRIBE", mailbox);
        }
        Command::Lsub { reference, pattern } => {
            encode_two_quoted_args(buf, tag, "LSUB", reference, pattern);
        }
        // RFC 3501 Section 6.4.2 / RFC 9051 Section 6.4.1
        Command::Close => {
            encode_simple(buf, tag, "CLOSE");
        }
        // RFC 3691 Section 2 / RFC 9051 Section 6.4.2
        Command::Unselect => {
            encode_simple(buf, tag, "UNSELECT");
        }
        Command::Unauthenticate => {
            // RFC 8437 Section 2: UNAUTHENTICATE takes no arguments.
            encode_simple(buf, tag, "UNAUTHENTICATE");
        }
        Command::Status { mailbox, items } => {
            encode_status(buf, tag, mailbox, items);
        }
        Command::Search { criteria } => {
            encode_search(buf, tag, "SEARCH", criteria, None);
        }
        Command::SearchReturn {
            criteria,
            return_opts,
        } => {
            encode_search(buf, tag, "SEARCH", criteria, Some(return_opts));
        }
        Command::SearchSave { criteria } => {
            encode_search(buf, tag, "SEARCH RETURN (SAVE)", criteria, None);
        }
        Command::Fetch {
            sequence_set,
            items,
            changed_since,
        } => {
            validate_sequence_set_or_err(sequence_set)?;
            encode_fetch(buf, tag, sequence_set, items, *changed_since)?;
        }
        Command::Store {
            sequence_set,
            operation,
            flags,
            unchanged_since,
        } => {
            validate_sequence_set_or_err(sequence_set)?;
            encode_store(
                buf,
                tag,
                false,
                sequence_set,
                *operation,
                flags,
                *unchanged_since,
            )?;
        }
        Command::Copy {
            sequence_set,
            mailbox,
        } => {
            validate_sequence_set_or_err(sequence_set)?;
            encode_two_arg(buf, tag, false, "COPY", sequence_set, mailbox);
        }
        Command::Move {
            sequence_set,
            mailbox,
        } => {
            validate_sequence_set_or_err(sequence_set)?;
            encode_two_arg(buf, tag, false, "MOVE", sequence_set, mailbox);
        }
        Command::UidSearch { criteria } => {
            encode_search(buf, tag, "UID SEARCH", criteria, None);
        }
        Command::UidSearchReturn {
            criteria,
            return_opts,
        } => {
            encode_search(buf, tag, "UID SEARCH", criteria, Some(return_opts));
        }
        Command::UidSearchSave { criteria } => {
            encode_search(buf, tag, "UID SEARCH RETURN (SAVE)", criteria, None);
        }
        Command::UidFetch {
            sequence_set,
            items,
            changed_since,
            vanished,
        } => {
            validate_sequence_set_or_err(sequence_set)?;
            encode_uid_fetch(buf, tag, sequence_set, items, *changed_since, *vanished)?;
        }
        Command::UidStore {
            sequence_set,
            operation,
            flags,
            unchanged_since,
        } => {
            validate_sequence_set_or_err(sequence_set)?;
            encode_store(
                buf,
                tag,
                true,
                sequence_set,
                *operation,
                flags,
                *unchanged_since,
            )?;
        }
        Command::UidMove {
            sequence_set,
            mailbox,
        } => {
            validate_sequence_set_or_err(sequence_set)?;
            encode_two_arg(buf, tag, true, "MOVE", sequence_set, mailbox);
        }
        Command::UidCopy {
            sequence_set,
            mailbox,
        } => {
            validate_sequence_set_or_err(sequence_set)?;
            encode_two_arg(buf, tag, true, "COPY", sequence_set, mailbox);
        }
        Command::UidExpunge { sequence_set } => {
            validate_sequence_set_or_err(sequence_set)?;
            encode_uid_expunge(buf, tag, sequence_set);
        }
        // RFC 2342 Section 5 / RFC 9051 Section 6.3.10
        Command::Namespace => {
            encode_simple(buf, tag, "NAMESPACE");
        }
        // RFC 3501 Section 6.4.1 (removed in IMAP4rev2)
        Command::Check => {
            encode_simple(buf, tag, "CHECK");
        }
        // RFC 3501 Section 6.4.3 / RFC 9051 Section 6.4.3
        Command::Expunge => {
            encode_simple(buf, tag, "EXPUNGE");
        }
        // RFC 2177 Section 3 / RFC 9051 Section 6.3.13
        Command::Idle => {
            encode_simple(buf, tag, "IDLE");
        }
        Command::Done => {
            // DONE is sent without a tag, as a continuation response
            // per RFC 2177 Section 3 / RFC 9051 Section 6.3.13.
            buf.extend_from_slice(b"DONE\r\n");
        }
        // RFC 3501 Section 6.1.1 / RFC 9051 Section 6.1.1
        Command::Capability => {
            encode_simple(buf, tag, "CAPABILITY");
        }
        // RFC 3501 Section 6.1.2 / RFC 9051 Section 6.1.2
        Command::Noop => {
            encode_simple(buf, tag, "NOOP");
        }
        Command::Enable(caps) => {
            encode_enable(buf, tag, caps)?;
        }
        Command::Id(params) => {
            encode_id(buf, tag, params)?;
        }
        Command::GetMetadata {
            mailbox,
            entries,
            max_size,
            depth,
        } => {
            encode_getmetadata(buf, tag, mailbox, entries, *max_size, depth.as_deref())?;
        }
        Command::SetMetadata { mailbox, entries } => {
            encode_setmetadata(buf, tag, mailbox, entries)?;
        }
        Command::Thread {
            algorithm,
            charset,
            criteria,
        } => {
            encode_thread_or_sort_cmd(buf, tag, "THREAD", algorithm, charset, criteria, false);
        }
        Command::UidThread {
            algorithm,
            charset,
            criteria,
        } => {
            encode_thread_or_sort_cmd(buf, tag, "UID THREAD", algorithm, charset, criteria, false);
        }
        Command::Sort {
            algorithm,
            charset,
            criteria,
        } => {
            encode_thread_or_sort_cmd(buf, tag, "SORT", algorithm, charset, criteria, true);
        }
        Command::UidSort {
            algorithm,
            charset,
            criteria,
        } => {
            encode_thread_or_sort_cmd(buf, tag, "UID SORT", algorithm, charset, criteria, true);
        }
        Command::Compress => {
            // COMPRESS DEFLATE (RFC 4978 Section 4)
            buf.extend_from_slice(tag.as_bytes());
            buf.extend_from_slice(b" COMPRESS DEFLATE\r\n");
        }

        // --- QUOTA (RFC 2087) ---
        Command::GetQuota { root } => {
            encode_mailbox_cmd(buf, tag, "GETQUOTA", root);
        }
        Command::GetQuotaRoot { mailbox } => {
            encode_mailbox_cmd(buf, tag, "GETQUOTAROOT", mailbox);
        }
        Command::SetQuota { root, resources } => {
            encode_set_quota(buf, tag, root, resources)?;
        }

        // --- ACL (RFC 4314) ---
        Command::SetAcl {
            mailbox,
            identifier,
            rights,
        } => {
            encode_set_acl(buf, tag, mailbox, identifier, rights);
        }
        Command::DeleteAcl {
            mailbox,
            identifier,
        } => {
            encode_two_quoted_args(buf, tag, "DELETEACL", mailbox, identifier);
        }
        Command::GetAcl { mailbox } => {
            encode_mailbox_cmd(buf, tag, "GETACL", mailbox);
        }
        Command::ListRights {
            mailbox,
            identifier,
        } => {
            encode_two_quoted_args(buf, tag, "LISTRIGHTS", mailbox, identifier);
        }
        Command::MyRights { mailbox } => {
            encode_mailbox_cmd(buf, tag, "MYRIGHTS", mailbox);
        }
    }
    Ok(())
}

// ---------------------------------------------------------------------------
// Encoding helpers
// ---------------------------------------------------------------------------

/// Encode a simple command with no arguments (e.g. `NOOP`, `LOGOUT`).
///
/// Used for commands whose ABNF is just the command name followed by CRLF
/// (RFC 3501 Section 6 / RFC 9051 Section 6).
fn encode_simple(buf: &mut BytesMut, tag: &str, command: &str) {
    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" ");
    buf.extend_from_slice(command.as_bytes());
    buf.extend_from_slice(b"\r\n");
}

/// Encode LOGIN command (RFC 3501 Section 6.2.3 / RFC 9051 Section 6.2.3).
fn encode_login(buf: &mut BytesMut, tag: &str, user: &str, pass: &str) {
    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" LOGIN ");
    encode_quoted_or_literal(buf, user.as_bytes());
    buf.extend_from_slice(b" ");
    encode_quoted_or_literal(buf, pass.as_bytes());
    buf.extend_from_slice(b"\r\n");
}

/// Encode AUTHENTICATE command (RFC 3501 Section 6.2.2 / RFC 9051 Section 6.2.2).
fn encode_authenticate(
    buf: &mut BytesMut,
    tag: &str,
    mechanism: &str,
    initial_response: Option<&str>,
) {
    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" AUTHENTICATE ");
    buf.extend_from_slice(mechanism.as_bytes());
    if let Some(ir) = initial_response {
        // SASL-IR (RFC 4959): send initial response on the same line.
        // RFC 4959 Section 3: empty initial response MUST be sent as `=`.
        if ir.is_empty() {
            buf.extend_from_slice(b" =");
        } else {
            buf.extend_from_slice(b" ");
            buf.extend_from_slice(ir.as_bytes());
        }
    }
    buf.extend_from_slice(b"\r\n");
}

/// Encode STATUS command (RFC 3501 Section 6.3.10 / RFC 9051 Section 6.3.11).
fn encode_status(buf: &mut BytesMut, tag: &str, mailbox: &str, items: &str) {
    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" STATUS ");
    encode_quoted_or_literal(buf, mailbox.as_bytes());
    buf.extend_from_slice(b" ");
    buf.extend_from_slice(items.as_bytes());
    buf.extend_from_slice(b"\r\n");
}

/// Encode a SEARCH-family command (RFC 3501 Section 6.4.4 / RFC 9051 Section 6.4.4).
///
/// Shared by all SEARCH variants. `cmd` is the command prefix
/// (e.g. `"SEARCH"`, `"UID SEARCH"`, `"SEARCH RETURN (SAVE)"`).
///
/// When `return_opts` is `Some`, emits `RETURN (<opts>)` between the command
/// and criteria (RFC 4731 Section 3.2 / Section 4 ABNF).
fn encode_search(
    buf: &mut BytesMut,
    tag: &str,
    cmd: &str,
    criteria: &str,
    return_opts: Option<&[String]>,
) {
    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" ");
    buf.extend_from_slice(cmd.as_bytes());
    if let Some(opts) = return_opts {
        // RFC 4731 Section 3.2: RETURN (opt1 opt2 ...)
        buf.extend_from_slice(b" RETURN (");
        for (i, opt) in opts.iter().enumerate() {
            if i > 0 {
                buf.extend_from_slice(b" ");
            }
            buf.extend_from_slice(opt.as_bytes());
        }
        buf.extend_from_slice(b")");
    }
    buf.extend_from_slice(b" ");
    buf.extend_from_slice(criteria.as_bytes());
    buf.extend_from_slice(b"\r\n");
}

/// Encode FETCH command (RFC 3501 Section 6.4.5 / RFC 9051 Section 6.4.5).
///
/// When `changed_since` is `Some`, appends the CHANGEDSINCE modifier
/// per RFC 7162 Section 3.1.4.1:
/// `"FETCH" SP sequence-set SP fetch-att SP "(CHANGEDSINCE" SP mod-sequence-value ")"`
fn encode_fetch(
    buf: &mut BytesMut,
    tag: &str,
    sequence_set: &str,
    items: &str,
    changed_since: Option<u64>,
) -> Result<(), crate::Error> {
    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" FETCH ");
    buf.extend_from_slice(sequence_set.as_bytes());
    buf.extend_from_slice(b" ");
    buf.extend_from_slice(items.as_bytes());
    if let Some(modseq) = changed_since {
        encode_changedsince_modifier(buf, modseq, false)?;
    }
    buf.extend_from_slice(b"\r\n");
    Ok(())
}

/// Encode STORE / UID STORE command (RFC 3501 Section 6.4.6 / RFC 9051 Section 6.4.6).
fn encode_store(
    buf: &mut BytesMut,
    tag: &str,
    uid: bool,
    sequence_set: &str,
    operation: crate::types::StoreOperation,
    flags: &[crate::types::Flag],
    unchanged_since: Option<u64>,
) -> Result<(), crate::Error> {
    buf.extend_from_slice(tag.as_bytes());
    if uid {
        buf.extend_from_slice(b" UID STORE ");
    } else {
        buf.extend_from_slice(b" STORE ");
    }
    buf.extend_from_slice(sequence_set.as_bytes());

    // CONDSTORE modifier (RFC 7162 Section 3.1.3): UNCHANGEDSINCE uses mod-sequence-valzer
    if let Some(modseq) = unchanged_since {
        validate_mod_sequence_valzer(modseq, "UNCHANGEDSINCE")?;
        buf.extend_from_slice(b" (UNCHANGEDSINCE ");
        buf.extend_from_slice(modseq.to_string().as_bytes());
        buf.extend_from_slice(b")");
    }

    encode_store_flags(buf, operation, flags)
}

/// Encode a command with two arguments: one atom and one quoted-or-literal string.
///
/// Used for COPY (RFC 3501 Section 6.4.7 / RFC 9051 Section 6.4.7),
/// UID COPY (RFC 3501 Section 6.4.8 / RFC 9051 Section 6.4.9),
/// and MOVE / UID MOVE (RFC 6851 Section 3 / RFC 9051 Section 6.4.8).
fn encode_two_arg(buf: &mut BytesMut, tag: &str, uid: bool, cmd: &str, arg1: &str, arg2: &str) {
    buf.extend_from_slice(tag.as_bytes());
    if uid {
        buf.extend_from_slice(b" UID ");
    } else {
        buf.extend_from_slice(b" ");
    }
    buf.extend_from_slice(cmd.as_bytes());
    buf.extend_from_slice(b" ");
    buf.extend_from_slice(arg1.as_bytes());
    buf.extend_from_slice(b" ");
    encode_quoted_or_literal(buf, arg2.as_bytes());
    buf.extend_from_slice(b"\r\n");
}

/// Encode a command with two quoted-or-literal arguments.
///
/// Format: `tag SP cmd SP quoted-or-literal(arg1) SP quoted-or-literal(arg2) CRLF`.
/// Used by LIST (RFC 3501 Section 6.3.8), LSUB (RFC 3501 Section 6.3.9),
/// and RENAME (RFC 3501 Section 6.3.5).
fn encode_two_quoted_args(buf: &mut BytesMut, tag: &str, cmd: &str, arg1: &str, arg2: &str) {
    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" ");
    buf.extend_from_slice(cmd.as_bytes());
    buf.extend_from_slice(b" ");
    encode_quoted_or_literal(buf, arg1.as_bytes());
    buf.extend_from_slice(b" ");
    encode_quoted_or_literal(buf, arg2.as_bytes());
    buf.extend_from_slice(b"\r\n");
}

/// Encode LIST with STATUS return option (RFC 5819 Section 2).
///
/// Format: `LIST <reference> <pattern> RETURN (STATUS (<items>))`.
/// The server returns interleaved LIST and STATUS untagged responses.
fn encode_list_status(
    buf: &mut BytesMut,
    tag: &str,
    reference: &str,
    pattern: &str,
    status_items: &str,
) {
    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" LIST ");
    encode_quoted_or_literal(buf, reference.as_bytes());
    buf.extend_from_slice(b" ");
    encode_quoted_or_literal(buf, pattern.as_bytes());
    buf.extend_from_slice(b" RETURN (STATUS (");
    buf.extend_from_slice(status_items.as_bytes());
    buf.extend_from_slice(b"))\r\n");
}

/// Encode CREATE with USE special-use attributes (RFC 6154 Section 3).
///
/// RFC 6154 Section 3 / Section 6 ABNF:
/// `create-param =/ "USE" SP "(" [use-attr *(SP use-attr)] ")"`
/// where `use-attr = "\All" / "\Archive" / "\Drafts" / "\Flagged" /
///                    "\Junk" / "\Sent" / "\Trash" / use-attr-ext`
///
/// Wire format: `tag CREATE mailbox (USE (\Attr1 \Attr2))\r\n`
fn encode_create_special_use(
    buf: &mut BytesMut,
    tag: &str,
    mailbox: &str,
    special_use: &[MailboxAttribute],
) {
    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" CREATE ");
    encode_quoted_or_literal(buf, mailbox.as_bytes());
    buf.extend_from_slice(b" (USE (");
    for (i, attr) in special_use.iter().enumerate() {
        if i > 0 {
            buf.extend_from_slice(b" ");
        }
        buf.extend_from_slice(attr.as_imap_str().as_bytes());
    }
    buf.extend_from_slice(b"))\r\n");
}

/// Encode a command that takes a single mailbox argument as a quoted-or-literal string.
///
/// Used for SELECT, EXAMINE, CREATE, DELETE, SUBSCRIBE, UNSUBSCRIBE
/// (RFC 3501 Sections 6.3.1-6.3.7 / RFC 9051 Sections 6.3.1-6.3.7).
fn encode_mailbox_cmd(buf: &mut BytesMut, tag: &str, cmd: &str, mailbox: &str) {
    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" ");
    buf.extend_from_slice(cmd.as_bytes());
    buf.extend_from_slice(b" ");
    encode_quoted_or_literal(buf, mailbox.as_bytes());
    buf.extend_from_slice(b"\r\n");
}

/// Validates that a QRESYNC known-uids / known-sequence-set / known-uid-set
/// is a syntactically valid `sequence-set` (RFC 3501 Section 9) with the
/// additional constraints from RFC 7162 Section 7 / Section 3.2.5.2:
/// - `*` is not allowed (known-uids uses `nz-number`, not `seq-number`)
/// - `$` (RFC 5182 search result reference) is not meaningful in QRESYNC context
fn validate_known_sequence_set(s: &str) -> Result<(), crate::Error> {
    // First, reject `*` — RFC 7162 Section 3.2.5.2 explicitly disallows it.
    if s.contains('*') {
        return Err(crate::Error::Protocol(
            "\"*\" is not allowed in QRESYNC known-uids/sequence-set (RFC 7162 Section 3.2.5.2)"
                .into(),
        ));
    }
    // Reject `$` — RFC 5182 search result reference is not valid in QRESYNC context.
    if s.contains('$') {
        return Err(crate::Error::Protocol(
            "\"$\" (search result reference) is not allowed in QRESYNC \
             known-uids/sequence-set (RFC 7162 Section 7)"
                .into(),
        ));
    }
    // Validate full sequence-set ABNF: sequence-set = (seq-number / seq-range)
    // *("," sequence-set) where seq-number = nz-number (since * is already
    // excluded) and nz-number = digit-nz *DIGIT (RFC 3501 Section 9).
    if !validate_sequence_set(s) {
        return Err(crate::Error::Protocol(
            "QRESYNC known-uids/sequence-set is not a valid sequence-set \
             (RFC 7162 Section 7: known-uids = sequence-set)"
                .into(),
        ));
    }
    Ok(())
}

/// Validate that a string is a valid `atom` per RFC 3501 Section 9.
///
/// RFC 3501 Section 9: `atom = 1*ATOM-CHAR`,
/// `ATOM-CHAR = <any CHAR except atom-specials>`,
/// `atom-specials = "(" / ")" / "{" / SP / CTL / list-wildcards / quoted-specials / resp-specials`,
/// `list-wildcards = "%" / "*"`, `quoted-specials = DQUOTE / "\"`,
/// `resp-specials = "]"`.
///
/// `context` is a human-readable label for error messages (e.g., "flag keyword",
/// "SETQUOTA resource name").
fn validate_atom(s: &str, context: &str) -> Result<(), crate::Error> {
    if s.is_empty() {
        return Err(crate::Error::Protocol(format!(
            "{context} must be at least one character \
             (RFC 3501 Section 9: atom = 1*ATOM-CHAR)"
        )));
    }
    for b in s.bytes() {
        let is_atom_special = matches!(
            b,
            b'(' | b')' | b'{' | b' ' | b'%' | b'*' | b'"' | b'\\' | b']'
        );
        let is_ctl = b < 0x20 || b == 0x7F;
        let is_outside_char = b == 0 || b > 0x7F;
        if is_atom_special || is_ctl || is_outside_char {
            return Err(crate::Error::Protocol(format!(
                "{context} contains invalid byte 0x{b:02X} — must be an atom \
                 (RFC 3501 Section 9: ATOM-CHAR excludes atom-specials, CTL, non-ASCII)"
            )));
        }
    }
    Ok(())
}

/// Validate that a custom flag keyword contains only ATOM-CHARs.
///
/// RFC 3501 Section 9: `flag-keyword = atom`.
/// Delegates to [`validate_atom`].
pub(crate) fn validate_flag_keyword(s: &str) -> Result<(), crate::Error> {
    validate_atom(s, "flag keyword")
}

/// Filter and validate flags for client commands (STORE, APPEND).
///
/// RFC 3501 Section 9: the `flag` production excludes `\Recent`
/// (read-only, server-set) and `\*` (only valid in `flag-perm` for
/// PERMANENTFLAGS responses).  Custom flag keywords are validated
/// against ATOM-CHAR (RFC 3501 Section 9: `flag-keyword = atom`).
///
/// Returns the filtered flags with `\Recent` and `\*` removed.
fn validate_and_filter_flags<'a>(
    flags: &'a [crate::types::Flag],
    context: &str,
) -> Result<Vec<&'a crate::types::Flag>, crate::Error> {
    let valid_flags: Vec<_> = flags
        .iter()
        .filter(|f| {
            if matches!(f, crate::types::Flag::Recent | crate::types::Flag::Wildcard) {
                tracing::debug!(
                    flag = %f,
                    "Skipping flag not permitted in {context} per RFC 3501 Section 9 (flag production)"
                );
                false
            } else {
                true
            }
        })
        .collect();
    for flag in &valid_flags {
        if let crate::types::Flag::Custom(s) = flag {
            validate_flag_keyword(s)?;
        }
    }
    Ok(valid_flags)
}

/// Validate an APPEND date-time string against RFC 3501 Section 9.
///
/// The expected format (without the surrounding DQUOTEs, which the caller adds):
///
/// ```text
/// date-day-fixed "-" date-month "-" date-year SP time SP zone
/// date-day-fixed = (SP DIGIT) / 2DIGIT          ; 1-31, space-padded or zero-padded
/// date-month     = "Jan" / "Feb" / "Mar" / "Apr" / "May" / "Jun" /
///                  "Jul" / "Aug" / "Sep" / "Oct" / "Nov" / "Dec"
/// date-year      = 4DIGIT
/// time           = 2DIGIT ":" 2DIGIT ":" 2DIGIT  ; HH:MM:SS
/// zone           = ("+" / "-") 4DIGIT
/// ```
#[allow(clippy::too_many_lines)]
pub(crate) fn validate_append_datetime(date: &str) -> Result<(), crate::Error> {
    const MONTHS: [&[u8]; 12] = [
        b"Jan", b"Feb", b"Mar", b"Apr", b"May", b"Jun", b"Jul", b"Aug", b"Sep", b"Oct", b"Nov",
        b"Dec",
    ];

    let b = date.as_bytes();

    // Expected length: " 7-Jul-1996 02:44:25 -0700" = 26 bytes.
    // date-day-fixed (2) + "-" (1) + month (3) + "-" (1) + year (4)
    //   + SP (1) + time (8) + SP (1) + zone (5) = 26
    if b.len() != 26 {
        return Err(crate::Error::InvalidAppendDate(format!(
            "expected 26 characters, got {} — \
             date-time must be date-day-fixed \"-\" date-month \"-\" date-year \
             SP time SP zone (RFC 3501 Section 9)",
            b.len()
        )));
    }

    // date-day-fixed = (SP DIGIT) / 2DIGIT (RFC 3501 Section 9).
    //
    // The `(SP DIGIT)` form covers space-padded single-digit days (` 1`–` 9`).
    // The `2DIGIT` form covers any two-digit day; semantically valid days are
    // `01`–`31`. Zero-padded single-digit days (`01`–`09`) are valid per the
    // `2DIGIT` alternative — RFC 5234 Section 3.4 defines `2DIGIT = DIGIT DIGIT`.
    let day_hi = b[0];
    let day_lo = b[1];
    let valid_day = match day_hi {
        b' ' => day_lo.is_ascii_digit() && day_lo != b'0',
        b'0' => (b'1'..=b'9').contains(&day_lo),
        b'1'..=b'2' => day_lo.is_ascii_digit(),
        b'3' => day_lo == b'0' || day_lo == b'1',
        _ => false,
    };
    if !valid_day {
        return Err(crate::Error::InvalidAppendDate(format!(
            "invalid day {:?} — date-day-fixed must be (SP DIGIT) / 2DIGIT \
             with values 1-31 (RFC 3501 Section 9)",
            std::str::from_utf8(&b[0..2]).unwrap_or("??")
        )));
    }

    // First separator: "-" (RFC 3501 Section 9).
    if b[2] != b'-' {
        return Err(crate::Error::InvalidAppendDate(format!(
            "expected '-' at position 2, got {:?} (RFC 3501 Section 9)",
            b[2] as char
        )));
    }

    // date-month (RFC 3501 Section 9).
    // RFC 3501 Section 9 paragraph (1): "all alphabetic characters are
    // case-insensitive … Implementations MUST accept these strings in a
    // case-insensitive fashion."  RFC 5234 Section 2.3 confirms ABNF
    // literal strings are case-insensitive.
    let month = &b[3..6];
    if !MONTHS.iter().any(|m| m.eq_ignore_ascii_case(month)) {
        return Err(crate::Error::InvalidAppendDate(format!(
            "invalid month {:?} — date-month must be Jan/Feb/.../Dec (RFC 3501 Section 9)",
            std::str::from_utf8(month).unwrap_or("???")
        )));
    }

    // Day-vs-month cross-check (RFC 3501 Section 9).
    //
    // The ABNF `date-day-fixed` allows 1-31 structurally, but not every day
    // is valid for every month.  We enforce:
    //   - 31-day months: Jan, Mar, May, Jul, Aug, Oct, Dec
    //   - 30-day months: Apr, Jun, Sep, Nov
    //   - Feb: max 29 (we accept 29 universally since a leap-year check
    //     would require parsing the 4-digit year; this is a practical
    //     compromise — the server will reject truly invalid dates anyway)
    let day: u8 = match day_hi {
        b' ' => day_lo - b'0',
        _ => (day_hi - b'0') * 10 + (day_lo - b'0'),
    };
    let max_day: u8 = match month[0].to_ascii_lowercase() {
        // Feb → 29
        b'f' => 29,
        // Apr → 30
        b'a' if month[1].eq_ignore_ascii_case(&b'p') => 30,
        // Jun → 30
        b'j' if month[1].eq_ignore_ascii_case(&b'u') && month[2].eq_ignore_ascii_case(&b'n') => 30,
        // Sep, Nov → 30
        b's' | b'n' => 30,
        // Jan, Mar, May, Jul, Aug, Oct, Dec → 31
        _ => 31,
    };
    if day > max_day {
        return Err(crate::Error::InvalidAppendDate(format!(
            "invalid day {} for month {:?} — maximum is {} (RFC 3501 Section 9)",
            day,
            std::str::from_utf8(month).unwrap_or("???"),
            max_day
        )));
    }

    // Second separator: "-" (RFC 3501 Section 9).
    if b[6] != b'-' {
        return Err(crate::Error::InvalidAppendDate(format!(
            "expected '-' at position 6, got {:?} (RFC 3501 Section 9)",
            b[6] as char
        )));
    }

    // date-year = 4DIGIT (RFC 3501 Section 9).
    if !b[7..11].iter().all(u8::is_ascii_digit) {
        return Err(crate::Error::InvalidAppendDate(format!(
            "invalid year {:?} — date-year must be 4DIGIT (RFC 3501 Section 9)",
            std::str::from_utf8(&b[7..11]).unwrap_or("????")
        )));
    }

    // SP between date and time (RFC 3501 Section 9).
    if b[11] != b' ' {
        return Err(crate::Error::InvalidAppendDate(format!(
            "expected SP at position 11, got {:?} (RFC 3501 Section 9)",
            b[11] as char
        )));
    }

    // time = 2DIGIT ":" 2DIGIT ":" 2DIGIT (RFC 3501 Section 9).
    let time = &b[12..20];
    let valid_time = time[0].is_ascii_digit()
        && time[1].is_ascii_digit()
        && time[2] == b':'
        && time[3].is_ascii_digit()
        && time[4].is_ascii_digit()
        && time[5] == b':'
        && time[6].is_ascii_digit()
        && time[7].is_ascii_digit();
    if !valid_time {
        return Err(crate::Error::InvalidAppendDate(format!(
            "invalid time {:?} — time must be 2DIGIT \":\" 2DIGIT \":\" 2DIGIT \
             (RFC 3501 Section 9)",
            std::str::from_utf8(time).unwrap_or("????????")
        )));
    }

    // Semantic range checks for time components (RFC 3501 Section 9).
    // The ABNF `time = 2DIGIT ":" 2DIGIT ":" 2DIGIT` is purely structural,
    // but since we already enforce semantic day ranges (1-31) and month names,
    // we apply the same rigour here.  Valid ranges follow RFC 5322 Section 3.3:
    //   hour   = 00-23
    //   minute = 00-59
    //   second = 00-60  (60 allows for leap seconds)
    let hour = (time[0] - b'0') * 10 + (time[1] - b'0');
    let minute = (time[3] - b'0') * 10 + (time[4] - b'0');
    let second = (time[6] - b'0') * 10 + (time[7] - b'0');

    if hour > 23 {
        return Err(crate::Error::InvalidAppendDate(format!(
            "invalid hour {hour:02} — must be 00-23 (RFC 3501 Section 9, \
             RFC 5322 Section 3.3)"
        )));
    }
    if minute > 59 {
        return Err(crate::Error::InvalidAppendDate(format!(
            "invalid minute {minute:02} — must be 00-59 (RFC 3501 Section 9, \
             RFC 5322 Section 3.3)"
        )));
    }
    if second > 60 {
        return Err(crate::Error::InvalidAppendDate(format!(
            "invalid second {second:02} — must be 00-60 (RFC 3501 Section 9, \
             RFC 5322 Section 3.3; 60 permits leap seconds)"
        )));
    }

    // SP between time and zone (RFC 3501 Section 9).
    if b[20] != b' ' {
        return Err(crate::Error::InvalidAppendDate(format!(
            "expected SP at position 20, got {:?} (RFC 3501 Section 9)",
            b[20] as char
        )));
    }

    // zone = ("+" / "-") 4DIGIT (RFC 3501 Section 9).
    let zone = &b[21..26];
    let valid_zone =
        (zone[0] == b'+' || zone[0] == b'-') && zone[1..].iter().all(u8::is_ascii_digit);
    if !valid_zone {
        return Err(crate::Error::InvalidAppendDate(format!(
            "invalid zone {:?} — zone must be (\"+\" / \"-\") 4DIGIT (RFC 3501 Section 9)",
            std::str::from_utf8(zone).unwrap_or("?????")
        )));
    }

    // Semantic range checks for zone components (RFC 3501 Section 9).
    // The zone is ±HHMM.  RFC 5322 Section 4.3 (obs-zone) does not
    // constrain the digits, but real UTC offsets range from -1200 to +1400,
    // and minutes are always 00-59.  We enforce those limits for consistency
    // with the semantic day/time checks above.
    let zone_hh = (zone[1] - b'0') * 10 + (zone[2] - b'0');
    let zone_mm = (zone[3] - b'0') * 10 + (zone[4] - b'0');

    if zone_hh > 14 {
        return Err(crate::Error::InvalidAppendDate(format!(
            "invalid zone hour {zone_hh:02} — must be 00-14 \
             (maximum real UTC offset is ±14:00, RFC 3501 Section 9)"
        )));
    }
    if zone_mm > 59 {
        return Err(crate::Error::InvalidAppendDate(format!(
            "invalid zone minute {zone_mm:02} — must be 00-59 \
             (RFC 3501 Section 9)"
        )));
    }

    Ok(())
}

/// Encode SELECT or EXAMINE with optional CONDSTORE/QRESYNC parameters.
///
/// Without parameters: `tag SELECT mailbox\r\n` (RFC 3501 Section 6.3.1).
/// With CONDSTORE: `tag SELECT mailbox (CONDSTORE)\r\n` (RFC 7162 Section 3.1.1).
/// With QRESYNC: `tag SELECT mailbox (QRESYNC (uidvalidity modseq [known-uids [seq-match-data]]))\r\n`
/// (RFC 7162 Section 3.2.5.2).
fn encode_select_or_examine(
    buf: &mut BytesMut,
    tag: &str,
    cmd: &str,
    mailbox: &str,
    condstore: bool,
    qresync: Option<&QresyncParams>,
) -> Result<(), crate::Error> {
    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" ");
    buf.extend_from_slice(cmd.as_bytes());
    buf.extend_from_slice(b" ");
    encode_quoted_or_literal(buf, mailbox.as_bytes());

    if condstore && qresync.is_none() {
        // RFC 7162 Section 3.1.1: SELECT mailbox (CONDSTORE)
        buf.extend_from_slice(b" (CONDSTORE)");
    }

    if let Some(params) = qresync {
        // RFC 7162 Section 3.2.5.2:
        // SELECT mailbox (QRESYNC (uidvalidity modseq [known-uids [seq-match-data]]))
        // seq-match-data = "(" known-sequence-set SP known-uid-set ")"
        // RFC 3501 Section 9: uidvalidity = nz-number (must be non-zero).
        if params.uid_validity == 0 {
            return Err(crate::Error::Protocol(
                "QRESYNC uid_validity must be non-zero (nz-number per RFC 3501 Section 9)".into(),
            ));
        }
        // mod_seq is mod-sequence-value per RFC 7162 Section 7 (>= 1, <= i64::MAX)
        validate_mod_sequence_value(params.mod_seq, "QRESYNC mod_seq")?;
        buf.extend_from_slice(b" (QRESYNC (");
        buf.extend_from_slice(params.uid_validity.to_string().as_bytes());
        buf.extend_from_slice(b" ");
        buf.extend_from_slice(params.mod_seq.to_string().as_bytes());
        if let Some(known_uids) = &params.known_uids {
            // RFC 7162 Section 3.2.5.2: "*" is not allowed in known-uids.
            validate_known_sequence_set(known_uids)?;
            buf.extend_from_slice(b" ");
            buf.extend_from_slice(known_uids.as_bytes());
        }
        if let Some((seq_set, uid_set)) = &params.seq_match_data {
            // RFC 7162 Section 7: The ABNF places [SP known-uids] and
            // [SP seq-match-data] at the same nesting level, but
            // seq-match-data is semantically meaningless without known-uids
            // (it maps message numbers to UIDs), so we require it.
            if params.known_uids.is_none() {
                return Err(crate::Error::Protocol(
                    "seq-match-data requires known-uids (RFC 7162 Section 3.2.5.2)".into(),
                ));
            }
            // RFC 7162 Section 3.2.5.2: "*" is not allowed in
            // known-sequence-set or known-uid-set.
            validate_known_sequence_set(seq_set)?;
            validate_known_sequence_set(uid_set)?;
            buf.extend_from_slice(b" (");
            buf.extend_from_slice(seq_set.as_bytes());
            buf.extend_from_slice(b" ");
            buf.extend_from_slice(uid_set.as_bytes());
            buf.extend_from_slice(b")");
        }
        buf.extend_from_slice(b"))");
    }

    buf.extend_from_slice(b"\r\n");
    Ok(())
}

/// Encode UID FETCH command (RFC 3501 Section 6.4.5 / RFC 9051 Section 6.4.5).
///
/// When `changed_since` is `Some`, appends the CHANGEDSINCE modifier
/// per RFC 7162 Section 3.1.4.1.
///
/// When `vanished` is `true`, appends the VANISHED modifier to the
/// fetch modifier list per RFC 7162 Section 3.2.6.  VANISHED requires
/// `changed_since` to be set (the modifier list must include CHANGEDSINCE).
fn encode_uid_fetch(
    buf: &mut BytesMut,
    tag: &str,
    sequence_set: &str,
    items: &str,
    changed_since: Option<u64>,
    vanished: bool,
) -> Result<(), crate::Error> {
    // RFC 7162 Section 3.2.6: VANISHED requires CHANGEDSINCE in the same
    // fetch modifier list.
    if vanished && changed_since.is_none() {
        return Err(crate::Error::Protocol(
            "VANISHED modifier requires CHANGEDSINCE per RFC 7162 Section 3.2.6".into(),
        ));
    }
    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" UID FETCH ");
    buf.extend_from_slice(sequence_set.as_bytes());
    buf.extend_from_slice(b" ");
    buf.extend_from_slice(items.as_bytes());
    if let Some(modseq) = changed_since {
        encode_changedsince_modifier(buf, modseq, vanished)?;
    }
    buf.extend_from_slice(b"\r\n");
    Ok(())
}

/// Encode the `store-att-flags` portion shared by STORE and UID STORE
/// (RFC 3501 Section 6.4.6 / RFC 9051 Section 6.4.6).
///
/// `store-att-flags = (["+" / "-"] "FLAGS" [".SILENT"]) SP (flag-list / (flag *(SP flag)))`
///
/// RFC 3501 Section 9: STORE uses the `flag` production, which excludes
/// `\Recent` (read-only, server-set) and `\*` (permanent-flag wildcard,
/// only valid in PERMANENTFLAGS responses).
fn encode_store_flags(
    buf: &mut BytesMut,
    operation: crate::types::StoreOperation,
    flags: &[crate::types::Flag],
) -> Result<(), crate::Error> {
    buf.extend_from_slice(b" ");
    match operation {
        crate::types::StoreOperation::Add => buf.extend_from_slice(b"+FLAGS"),
        crate::types::StoreOperation::Remove => buf.extend_from_slice(b"-FLAGS"),
        crate::types::StoreOperation::Replace => buf.extend_from_slice(b"FLAGS"),
        crate::types::StoreOperation::AddSilent => buf.extend_from_slice(b"+FLAGS.SILENT"),
        crate::types::StoreOperation::RemoveSilent => buf.extend_from_slice(b"-FLAGS.SILENT"),
        crate::types::StoreOperation::ReplaceSilent => buf.extend_from_slice(b"FLAGS.SILENT"),
    }
    let valid_flags = validate_and_filter_flags(flags, "STORE")?;
    // RFC 3501 Section 9 ABNF:
    // store-att-flags = (["+" / "-"] "FLAGS" [".SILENT"]) SP (flag-list / (flag *(SP flag)))
    // The SP and flag-list are mandatory even when all flags were filtered.
    // An empty flag-list is `()` per RFC 3501 Section 9.
    buf.extend_from_slice(b" (");
    for (i, flag) in valid_flags.iter().enumerate() {
        if i > 0 {
            buf.extend_from_slice(b" ");
        }
        buf.extend_from_slice(flag.as_imap_str().as_bytes());
    }
    buf.extend_from_slice(b")\r\n");
    Ok(())
}

/// Encode UID EXPUNGE command (RFC 4315 UIDPLUS Section 2.1).
fn encode_uid_expunge(buf: &mut BytesMut, tag: &str, sequence_set: &str) {
    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" UID EXPUNGE ");
    buf.extend_from_slice(sequence_set.as_bytes());
    buf.extend_from_slice(b"\r\n");
}

/// Encode ENABLE command (RFC 5161).
///
/// RFC 5161 ABNF: `"ENABLE" 1*(SP capability)` — at least one capability is required.
/// Returns an error if `caps` is empty.
fn encode_enable(buf: &mut BytesMut, tag: &str, caps: &[String]) -> Result<(), crate::Error> {
    // RFC 5161 ABNF: `"ENABLE" 1*(SP capability)` — at least one required.
    if caps.is_empty() {
        return Err(crate::Error::Protocol(
            "ENABLE requires at least one capability (RFC 5161)".into(),
        ));
    }
    // RFC 5161 Section 4: capability = ("AUTH=" auth-type) / atom.
    // Validate each name is a valid atom (RFC 3501 Section 9).
    for cap in caps {
        validate_atom(cap, "ENABLE capability")?;
    }
    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" ENABLE");
    for cap in caps {
        buf.extend_from_slice(b" ");
        buf.extend_from_slice(cap.as_bytes());
    }
    buf.extend_from_slice(b"\r\n");
    Ok(())
}

/// Encode GETMETADATA command (RFC 5464 Section 4.2).
///
/// Single entry: `GETMETADATA "<mailbox>" <entry>`
/// Multiple entries: `GETMETADATA "<mailbox>" (<entry1> <entry2> ...)`
///
/// Returns an error if `entries` is empty or if `depth` is not a valid value.
fn encode_getmetadata(
    buf: &mut BytesMut,
    tag: &str,
    mailbox: &str,
    entries: &[String],
    max_size: Option<u64>,
    depth: Option<&str>,
) -> Result<(), crate::Error> {
    // RFC 5464 Section 5: `maxsize-opt = "MAXSIZE" SP number`
    // RFC 3501 Section 9: `number = 1*DIGIT` — unsigned 32-bit integer (0..4_294_967_295).
    if let Some(n) = max_size {
        if n > u64::from(u32::MAX) {
            return Err(crate::Error::Protocol(format!(
                "GETMETADATA MAXSIZE must fit in number (u32) per RFC 5464 Section 5 / RFC 3501 Section 9, got {n}"
            )));
        }
    }

    // RFC 5464 Section 4.2 ABNF: `entries = entry / "(" entry *(SP entry) ")"` — at least one.
    if entries.is_empty() {
        return Err(crate::Error::Protocol(
            "GETMETADATA requires at least one entry (RFC 5464 Section 4.2)".into(),
        ));
    }

    // RFC 5464 Section 4.2.2: `scope-opt = "DEPTH" SP ("0" / "1" / "infinity")`
    if let Some(d) = depth {
        if d != "0" && d != "1" && d != "infinity" {
            return Err(crate::Error::Protocol(format!(
                "GETMETADATA DEPTH must be \"0\", \"1\", or \"infinity\" \
                 (RFC 5464 Section 4.2.2), got: {d:?}"
            )));
        }
    }

    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" GETMETADATA");

    // RFC 5464 Section 4.2: mailbox comes first, then optional options.
    // The ABNF in Section 5 places options before the mailbox, but every
    // example in Sections 4.2.1 and 4.2.2 places options AFTER the mailbox,
    // and all real-world servers implement the example syntax.
    buf.extend_from_slice(b" ");
    encode_quoted_or_literal(buf, mailbox.as_bytes());

    // Options: `(MAXSIZE n DEPTH "0"|"1"|"infinity")`
    if max_size.is_some() || depth.is_some() {
        buf.extend_from_slice(b" (");
        let first_opt = if let Some(n) = max_size {
            buf.extend_from_slice(b"MAXSIZE ");
            buf.extend_from_slice(n.to_string().as_bytes());
            false
        } else {
            true
        };
        if let Some(d) = depth {
            if !first_opt {
                buf.extend_from_slice(b" ");
            }
            buf.extend_from_slice(b"DEPTH ");
            buf.extend_from_slice(d.as_bytes());
        }
        buf.extend_from_slice(b")");
    }

    buf.extend_from_slice(b" ");
    if entries.len() == 1 {
        // Single entry — no parentheses per RFC 5464 Section 4.2
        encode_quoted_or_literal(buf, entries[0].as_bytes());
    } else {
        buf.extend_from_slice(b"(");
        for (i, entry) in entries.iter().enumerate() {
            if i > 0 {
                buf.extend_from_slice(b" ");
            }
            encode_quoted_or_literal(buf, entry.as_bytes());
        }
        buf.extend_from_slice(b")");
    }
    buf.extend_from_slice(b"\r\n");
    Ok(())
}

/// Encode SETMETADATA command (RFC 5464 Section 4.3).
///
/// Format: `SETMETADATA <mailbox> (<entry> <value> ...)`.
/// A `None` value is encoded as `NIL` to delete the entry.
/// RFC 5464 Section 5: `value = nstring / literal8` — values are raw bytes.
fn encode_setmetadata(
    buf: &mut BytesMut,
    tag: &str,
    mailbox: &str,
    entries: &[(String, Option<Vec<u8>>)],
) -> Result<(), crate::Error> {
    // RFC 5464 Section 5 ABNF: `entry-values = "(" entry *(SP entry) ")"` — at least one.
    if entries.is_empty() {
        return Err(crate::Error::Protocol(
            "SETMETADATA requires at least one entry (RFC 5464 Section 5)".into(),
        ));
    }

    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" SETMETADATA ");
    encode_quoted_or_literal(buf, mailbox.as_bytes());
    buf.extend_from_slice(b" (");
    for (i, (name, value)) in entries.iter().enumerate() {
        if i > 0 {
            buf.extend_from_slice(b" ");
        }
        encode_quoted_or_literal(buf, name.as_bytes());
        buf.extend_from_slice(b" ");
        match value {
            // RFC 5464 Section 5: value = nstring / literal8
            // Use literal8 (RFC 3516) for binary data to preserve NUL bytes.
            Some(v) => encode_nstring_or_literal8(buf, v),
            None => buf.extend_from_slice(b"NIL"),
        }
    }
    buf.extend_from_slice(b")\r\n");
    Ok(())
}

/// Encode a THREAD or SORT command (RFC 5256 Sections 2-3).
///
/// Shared by THREAD, UID THREAD, SORT, and UID SORT.
/// THREAD format: `<cmd> <algorithm> <charset> <criteria>`.
/// SORT format:   `<cmd> (<algorithm>) <charset> <criteria>`.
/// `parenthesize_algo` controls whether the algorithm is wrapped in `()`.
fn encode_thread_or_sort_cmd(
    buf: &mut BytesMut,
    tag: &str,
    cmd: &str,
    algorithm: &str,
    charset: &str,
    criteria: &str,
    parenthesize_algo: bool,
) {
    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" ");
    buf.extend_from_slice(cmd.as_bytes());
    if parenthesize_algo {
        // RFC 5256 Section 2: sort-criteria = "(" sort-key *(SP sort-key) ")"
        buf.extend_from_slice(b" (");
        buf.extend_from_slice(algorithm.as_bytes());
        buf.extend_from_slice(b") ");
    } else {
        // RFC 5256 Section 3: thread-alg is unparenthesized
        buf.extend_from_slice(b" ");
        buf.extend_from_slice(algorithm.as_bytes());
        buf.extend_from_slice(b" ");
    }
    buf.extend_from_slice(charset.as_bytes());
    buf.extend_from_slice(b" ");
    buf.extend_from_slice(criteria.as_bytes());
    buf.extend_from_slice(b"\r\n");
}

/// Encode ID command (RFC 2971 Section 3.1).
///
/// Empty params produce `ID NIL` per RFC 2971 Section 3.1:
/// `id ::= "ID" SPACE id_params_list`
/// `id_params_list ::= "(" #(string SPACE nstring) ")" / nil`
///
/// Values are `nstring` per RFC 2971 Section 3.1: a `None` value is encoded as `NIL`.
///
/// RFC 2971 Section 3.3 limits are enforced:
/// - No more than 30 field-value pairs.
/// - Field strings MUST NOT exceed 30 octets.
/// - Value strings MUST NOT exceed 1024 octets.
fn encode_id(
    buf: &mut BytesMut,
    tag: &str,
    params: &[(String, Option<String>)],
) -> Result<(), crate::Error> {
    // RFC 2971 Section 3.3: "Implementations MUST NOT send more than 30
    // field-value pairs."
    if params.len() > 30 {
        return Err(crate::Error::Protocol(format!(
            "ID command has {} field-value pairs, but RFC 2971 Section 3.3 \
             allows at most 30",
            params.len()
        )));
    }

    for (key, value) in params {
        // RFC 2971 Section 3.3: "Field strings MUST NOT be longer than
        // 30 octets."
        if key.len() > 30 {
            return Err(crate::Error::Protocol(format!(
                "ID field name is {} octets, but RFC 2971 Section 3.3 \
                 allows at most 30",
                key.len()
            )));
        }
        // RFC 2971 Section 3.3: "Value strings MUST NOT be longer than
        // 1024 octets."
        if let Some(v) = value {
            if v.len() > 1024 {
                return Err(crate::Error::Protocol(format!(
                    "ID value is {} octets, but RFC 2971 Section 3.3 \
                     allows at most 1024",
                    v.len()
                )));
            }
        }
    }

    buf.extend_from_slice(tag.as_bytes());
    if params.is_empty() {
        // RFC 2971 Section 3.1: NIL means "no data to send".
        buf.extend_from_slice(b" ID NIL\r\n");
    } else {
        buf.extend_from_slice(b" ID (");
        for (i, (key, value)) in params.iter().enumerate() {
            if i > 0 {
                buf.extend_from_slice(b" ");
            }
            encode_quoted_or_literal(buf, key.as_bytes());
            buf.extend_from_slice(b" ");
            // RFC 2971 Section 3.1: values are nstring — None encodes as NIL.
            match value {
                Some(v) => encode_quoted_or_literal(buf, v.as_bytes()),
                None => buf.extend_from_slice(b"NIL"),
            }
        }
        buf.extend_from_slice(b")\r\n");
    }
    Ok(())
}

/// Encode a byte slice as a quoted string or literal, depending on content.
///
/// Uses quoted form when safe (no CR, LF, NUL, or backslash/quote without escaping issues).
/// Falls back to literal for binary-unsafe content.
/// Quoted and literal formats per RFC 3501 Section 9 / RFC 9051 Section 9.
///
/// NUL bytes (%x00) are stripped from the data before encoding, per
/// RFC 3501 Section 9 rule (3): "The ASCII NUL character, %x00, MUST NOT
/// be used at any time." A `tracing::warn!` is emitted when NUL bytes are
/// encountered so that callers passing NUL bytes are noticed in logs.
pub(crate) fn encode_quoted_or_literal(buf: &mut BytesMut, data: &[u8]) {
    let data = strip_nul_bytes(data);

    // Check if the data can be safely quoted.
    // TEXT-CHAR per RFC 3501 Section 9: CHAR = %x01-7F, TEXT-CHAR = <any CHAR except CR and LF>.
    // NUL (%x00) is already stripped above.
    // DEL (%x7F) is included since it is within CHAR and is not CR/LF.
    let quotable = data.iter().all(|&b| b != b'\r' && b != b'\n' && b <= 0x7F);

    emit_quoted_or_literal(buf, &data, quotable);
}

/// Encode a byte slice as a quoted string or literal, with optional UTF-8 mode.
///
/// When `utf8_mode` is `true` (i.e., UTF8=ACCEPT is active per RFC 6855 Section 3),
/// valid UTF-8 sequences are permitted in quoted strings. RFC 6855 Section 3:
/// "The server MUST accept UTF-8 in quoted strings." RFC 9051 Section 9 extends
/// `CHAR` to include `UTF8-2 / UTF8-3 / UTF8-4`, making non-ASCII UTF-8 bytes
/// legal in quoted strings.
///
/// When `utf8_mode` is `false`, uses the standard RFC 3501 Section 9 check where
/// only `%x01-7F` (minus CR/LF) is quotable.
///
/// NUL bytes (%x00) are stripped regardless of mode, per RFC 3501 Section 9
/// rule (3): "The ASCII NUL character, %x00, MUST NOT be used at any time."
pub(crate) fn encode_quoted_or_literal_utf8(buf: &mut BytesMut, data: &[u8], utf8_mode: bool) {
    if !utf8_mode {
        // Delegate to the existing ASCII-only encoder.
        encode_quoted_or_literal(buf, data);
        return;
    }

    let data = strip_nul_bytes(data);

    // RFC 6855 Section 3 / RFC 9051 Section 9: when UTF8=ACCEPT is active,
    // quoted strings may contain UTF-8 sequences. The quotable check becomes:
    // the data must be valid UTF-8, and must not contain CR (%x0D) or LF (%x0A).
    // NUL is already stripped above.
    let quotable =
        std::str::from_utf8(&data).is_ok() && data.iter().all(|&b| b != b'\r' && b != b'\n');

    emit_quoted_or_literal(buf, &data, quotable);
}

/// Defensively strip NUL bytes from IMAP string data.
///
/// RFC 3501 Section 9: CHAR8 = %x01-ff — NUL (%x00) is forbidden.
/// Returns a `Cow` to avoid allocation when no NUL bytes are present.
fn strip_nul_bytes(data: &[u8]) -> std::borrow::Cow<'_, [u8]> {
    if data.contains(&0x00) {
        tracing::warn!(
            "Stripped NUL bytes from IMAP string data — RFC 3501 Section 9 forbids %x00"
        );
        std::borrow::Cow::Owned(data.iter().copied().filter(|&b| b != 0x00).collect())
    } else {
        std::borrow::Cow::Borrowed(data)
    }
}

/// Write data as a quoted string, escaping `\` and `"`.
///
/// RFC 3501 Section 9: `quoted = DQUOTE *QUOTED-CHAR DQUOTE`, where
/// quoted-specials (backslash and double-quote) are escaped with backslash.
///
/// The caller must ensure the data is quotable (no CR, LF, or bytes outside
/// the allowed range for the current encoding mode).
fn emit_quoted_string(buf: &mut BytesMut, data: &[u8]) {
    buf.extend_from_slice(b"\"");
    for &byte in data {
        // Escape backslash and double-quote per RFC 3501 Section 9.
        if byte == b'\\' || byte == b'"' {
            buf.extend_from_slice(b"\\");
        }
        buf.extend_from_slice(&[byte]);
    }
    buf.extend_from_slice(b"\"");
}

/// Write data as either a quoted string or literal to the buffer.
///
/// RFC 3501 Section 9: uses quoted form when `quotable` is true,
/// otherwise falls back to literal form: `{size}\r\n<data>`.
fn emit_quoted_or_literal(buf: &mut BytesMut, data: &[u8], quotable: bool) {
    if quotable {
        emit_quoted_string(buf, data);
    } else {
        // Use literal form: {size}\r\n<data>
        buf.extend_from_slice(b"{");
        buf.extend_from_slice(data.len().to_string().as_bytes());
        buf.extend_from_slice(b"}\r\n");
        buf.extend_from_slice(data);
    }
}

/// Encode a byte slice as a literal8 (`~{N}\r\n<data>`).
///
/// RFC 3516: `literal8 = "~{" number "}" CRLF *OCTET`
/// Unlike standard literals, literal8 uses `*OCTET` (%x00-FF) which includes
/// NUL bytes. This is required for binary data such as METADATA values.
fn encode_literal8(buf: &mut BytesMut, data: &[u8]) {
    // RFC 3516: ~{<size>}\r\n<data>
    buf.extend_from_slice(b"~{");
    buf.extend_from_slice(data.len().to_string().as_bytes());
    buf.extend_from_slice(b"}\r\n");
    buf.extend_from_slice(data);
}

/// Encode a byte slice as an nstring (quoted or NIL) or literal8, depending on content.
///
/// RFC 5464 Section 5: `value = nstring / literal8`
/// Uses quoted form when the data is ASCII-safe (no CR, LF, NUL, or bytes > 0x7F).
/// Falls back to literal8 (`~{N}\r\n<data>`) for binary data, preserving all bytes
/// including NUL (%x00).
///
/// This differs from [`encode_quoted_or_literal`] which strips NUL bytes and uses
/// standard literal form. SETMETADATA values MUST use this function because
/// RFC 5464 Section 5 defines `value = nstring / literal8`, and literal8
/// (RFC 3516) permits `*OCTET` (%x00-FF).
fn encode_nstring_or_literal8(buf: &mut BytesMut, data: &[u8]) {
    // Check if the data can be safely quoted as an nstring.
    // TEXT-CHAR per RFC 3501 Section 9: CHAR = %x01-7F, TEXT-CHAR = <any CHAR except CR and LF>.
    // NUL (%x00) and bytes > 0x7F cannot be represented in quoted form.
    let quotable = data
        .iter()
        .all(|&b| b != 0x00 && b != b'\r' && b != b'\n' && b <= 0x7F);

    if quotable {
        emit_quoted_string(buf, data);
    } else {
        // RFC 5464 Section 5 / RFC 3516: use literal8 for binary data.
        encode_literal8(buf, data);
    }
}

/// Encode SETQUOTA command (RFC 2087 Section 4.1).
///
/// Format: `SETQUOTA "<root>" (<resource> <limit> ...)`.
/// RFC 2087 Section 4.1:
/// `setquota = "SETQUOTA" SP astring SP setquota_list`
/// `setquota_list = "(" 0#setquota_resource ")"`
/// `setquota_resource = atom SP number`
///
/// `number` is defined as `1*DIGIT` in RFC 3501 Section 9, constrained to u32.
/// Returns an error if any resource name is not a valid atom or any limit exceeds `u32::MAX`.
fn encode_set_quota(
    buf: &mut BytesMut,
    tag: &str,
    root: &str,
    resources: &[(String, u64)],
) -> Result<(), crate::Error> {
    // RFC 2087 Section 4.1: setquota_resource = atom SP number
    // RFC 3501 Section 9: number = 1*DIGIT (u32 range)
    for (resource, limit) in resources {
        // RFC 2087 Section 4.1: resource name must be an atom
        validate_atom(resource, "SETQUOTA resource name")?;
        if *limit > u64::from(u32::MAX) {
            return Err(crate::Error::Protocol(format!(
                "SETQUOTA resource limit {limit} for \"{resource}\" exceeds u32::MAX \
                 (RFC 2087 Section 4.1: number is constrained to 32 bits per RFC 3501 Section 9)"
            )));
        }
    }
    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" SETQUOTA ");
    encode_quoted_or_literal(buf, root.as_bytes());
    buf.extend_from_slice(b" (");
    for (i, (resource, limit)) in resources.iter().enumerate() {
        if i > 0 {
            buf.extend_from_slice(b" ");
        }
        buf.extend_from_slice(resource.as_bytes());
        buf.extend_from_slice(b" ");
        buf.extend_from_slice(limit.to_string().as_bytes());
    }
    buf.extend_from_slice(b")\r\n");
    Ok(())
}

/// Encode SETACL command (RFC 4314 Section 3.1).
///
/// Format: `SETACL <mailbox> <identifier> <rights>`.
fn encode_set_acl(buf: &mut BytesMut, tag: &str, mailbox: &str, identifier: &str, rights: &str) {
    buf.extend_from_slice(tag.as_bytes());
    buf.extend_from_slice(b" SETACL ");
    encode_quoted_or_literal(buf, mailbox.as_bytes());
    buf.extend_from_slice(b" ");
    encode_quoted_or_literal(buf, identifier.as_bytes());
    buf.extend_from_slice(b" ");
    encode_quoted_or_literal(buf, rights.as_bytes());
    buf.extend_from_slice(b"\r\n");
}

/// Encode the header portion of one message in a MULTIAPPEND command (RFC 3502 Section 3).
///
/// Writes: `[tag " APPEND " mailbox] [" (" flags ")"] [" " quoted-date] " {" size ["+" ] "}"`.
/// If `first` is `true`, the `tag APPEND mailbox` prefix is included.
/// The literal data itself is NOT included — the caller must send it separately
/// (because literal synchronization may require a server continuation).
///
/// `literal_plus` should be `true` when the server advertises LITERAL+ (RFC 7888).
#[allow(clippy::too_many_arguments)]
pub(crate) fn encode_multi_append_header(
    buf: &mut BytesMut,
    tag: &str,
    mailbox: &str,
    flags: &[crate::types::Flag],
    date: Option<&str>,
    message_len: usize,
    first: bool,
    literal_plus: bool,
    utf8: bool,
) -> Result<(), crate::Error> {
    if first {
        // Tag + APPEND + mailbox (RFC 3502 Section 3).
        // RFC 6855 Section 3: when UTF8=ACCEPT is active, the server MUST accept
        // UTF-8 in quoted strings, so non-ASCII mailbox names can use quoted form
        // instead of falling back to a synchronizing literal.
        buf.extend_from_slice(tag.as_bytes());
        buf.extend_from_slice(b" APPEND ");
        encode_quoted_or_literal_utf8(buf, mailbox.as_bytes(), utf8);
    }

    // Flags (RFC 3501 Section 6.3.11).
    let valid_flags = validate_and_filter_flags(flags, "APPEND")?;
    if !valid_flags.is_empty() {
        buf.extend_from_slice(b" (");
        for (i, flag) in valid_flags.iter().enumerate() {
            if i > 0 {
                buf.extend_from_slice(b" ");
            }
            buf.extend_from_slice(flag.as_imap_str().as_bytes());
        }
        buf.extend_from_slice(b")");
    }

    // Internal date (RFC 3501 Section 6.3.11).
    // Validate against the date-time production (RFC 3501 Section 9).
    if let Some(d) = date {
        validate_append_datetime(d)?;
        buf.extend_from_slice(b" ");
        encode_quoted_or_literal(buf, d.as_bytes());
    }

    // Literal header (RFC 3501 Section 9 / RFC 7888 for LITERAL+).
    // RFC 6855 Section 4: when UTF8=ACCEPT is enabled, use the UTF8
    // APPEND data extension: `UTF8 (~{size}\r\n<message>)`.
    // RFC 9051 Section 9: literal8 = "~{" number64 "}" CRLF *OCTET — no `["+"]`
    // modifier, so the non-synchronizing `+` suffix must NOT be used with literal8.
    if utf8 {
        buf.extend_from_slice(b" UTF8 (~{");
    } else {
        buf.extend_from_slice(b" {");
    }
    buf.extend_from_slice(message_len.to_string().as_bytes());
    if literal_plus && !utf8 {
        buf.extend_from_slice(b"+");
    }
    buf.extend_from_slice(b"}\r\n");
    Ok(())
}

#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::expect_used)]
mod tests {
    use super::*;

    #[test]
    fn encode_simple_command() {
        let mut buf = BytesMut::new();
        encode_simple(&mut buf, "A001", "NOOP");
        assert_eq!(&buf[..], b"A001 NOOP\r\n");
    }

    #[test]
    fn encode_login_simple() {
        let mut buf = BytesMut::new();
        encode_login(&mut buf, "A001", "user", "pass");
        assert_eq!(&buf[..], b"A001 LOGIN \"user\" \"pass\"\r\n");
    }

    #[test]
    fn encode_login_special_chars() {
        let mut buf = BytesMut::new();
        encode_login(&mut buf, "A001", "user", r#"p"a\ss"#);
        assert_eq!(&buf[..], b"A001 LOGIN \"user\" \"p\\\"a\\\\ss\"\r\n");
    }

    #[test]
    fn encode_quoted_string() {
        let mut buf = BytesMut::new();
        encode_quoted_or_literal(&mut buf, b"hello world");
        assert_eq!(&buf[..], b"\"hello world\"");
    }

    #[test]
    fn encode_literal_for_binary() {
        let mut buf = BytesMut::new();
        encode_quoted_or_literal(&mut buf, b"line1\r\nline2");
        // Should use literal form because of CRLF.
        assert_eq!(&buf[..], b"{12}\r\nline1\r\nline2");
    }

    #[test]
    fn encode_select() {
        let mut buf = BytesMut::new();
        let cmd = Command::Select {
            mailbox: "INBOX".into(),
            condstore: false,
            qresync: None,
        };
        encode_command(&mut buf, "A002", &cmd).unwrap();
        assert_eq!(&buf[..], b"A002 SELECT \"INBOX\"\r\n");
    }

    #[test]
    fn encode_select_qresync() {
        let mut buf = BytesMut::new();
        let cmd = Command::Select {
            mailbox: "INBOX".into(),
            condstore: false,
            qresync: Some(QresyncParams {
                uid_validity: 67890,
                mod_seq: 12345,
                known_uids: None,
                seq_match_data: None,
            }),
        };
        encode_command(&mut buf, "A005", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A005 SELECT \"INBOX\" (QRESYNC (67890 12345))\r\n"
        );
    }

    #[test]
    fn encode_select_qresync_with_known_uids() {
        let mut buf = BytesMut::new();
        let cmd = Command::Select {
            mailbox: "INBOX".into(),
            condstore: false,
            qresync: Some(QresyncParams {
                uid_validity: 67890,
                mod_seq: 12345,
                known_uids: Some("1:500".into()),
                seq_match_data: None,
            }),
        };
        encode_command(&mut buf, "A006", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A006 SELECT \"INBOX\" (QRESYNC (67890 12345 1:500))\r\n"
        );
    }

    #[test]
    fn encode_examine_qresync() {
        let mut buf = BytesMut::new();
        let cmd = Command::Examine {
            mailbox: "INBOX".into(),
            condstore: false,
            qresync: Some(QresyncParams {
                uid_validity: 100,
                mod_seq: 50,
                known_uids: None,
                seq_match_data: None,
            }),
        };
        encode_command(&mut buf, "A007", &cmd).unwrap();
        assert_eq!(&buf[..], b"A007 EXAMINE \"INBOX\" (QRESYNC (100 50))\r\n");
    }

    /// RFC 3501 Section 9: uidvalidity = nz-number, so 0 is invalid.
    /// RFC 7162 Section 3.2.5.2: QRESYNC takes uidvalidity.
    #[test]
    fn encode_select_qresync_rejects_zero_uid_validity() {
        let cmd = Command::Select {
            mailbox: "INBOX".into(),
            condstore: false,
            qresync: Some(QresyncParams {
                uid_validity: 0,
                mod_seq: 1,
                known_uids: None,
                seq_match_data: None,
            }),
        };
        let mut buf = BytesMut::new();
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "QRESYNC uid_validity=0 must be rejected per RFC 3501 Section 9 (nz-number)"
        );
    }

    /// RFC 3501 Section 9: uidvalidity = nz-number, so 0 is invalid.
    /// RFC 7162 Section 3.2.5.2: QRESYNC takes uidvalidity.
    #[test]
    fn encode_examine_qresync_rejects_zero_uid_validity() {
        let cmd = Command::Examine {
            mailbox: "INBOX".into(),
            condstore: false,
            qresync: Some(QresyncParams {
                uid_validity: 0,
                mod_seq: 1,
                known_uids: None,
                seq_match_data: None,
            }),
        };
        let mut buf = BytesMut::new();
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "QRESYNC uid_validity=0 must be rejected per RFC 3501 Section 9 (nz-number)"
        );
    }

    #[test]
    fn encode_uid_fetch() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidFetch {
            sequence_set: "1:*".into(),
            items: "(UID FLAGS ENVELOPE)".into(),
            changed_since: None,
            vanished: false,
        };
        encode_command(&mut buf, "A003", &cmd).unwrap();
        assert_eq!(&buf[..], b"A003 UID FETCH 1:* (UID FLAGS ENVELOPE)\r\n");
    }

    #[test]
    fn encode_done_has_no_tag() {
        let mut buf = BytesMut::new();
        encode_command(&mut buf, "A999", &Command::Done).unwrap();
        assert_eq!(&buf[..], b"DONE\r\n");
    }

    #[test]
    fn encode_store_add_flags() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidStore {
            sequence_set: "1:3".into(),
            operation: crate::types::StoreOperation::Add,
            flags: vec![crate::types::Flag::Seen, crate::types::Flag::Flagged],
            unchanged_since: None,
        };
        encode_command(&mut buf, "A004", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A004 UID STORE 1:3 +FLAGS (\\Seen \\Flagged)\r\n"
        );
    }

    #[test]
    fn encode_store_with_condstore() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidStore {
            sequence_set: "5".into(),
            operation: crate::types::StoreOperation::Remove,
            flags: vec![crate::types::Flag::Deleted],
            unchanged_since: Some(12345),
        };
        encode_command(&mut buf, "A005", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A005 UID STORE 5 (UNCHANGEDSINCE 12345) -FLAGS (\\Deleted)\r\n"
        );
    }

    #[test]
    fn encode_authenticate_with_sasl_ir() {
        let mut buf = BytesMut::new();
        let cmd = Command::Authenticate {
            mechanism: "XOAUTH2".into(),
            initial_response: Some("dXNlcj1hQGIuY29tAWF1dGg9QmVhcmVyIHRva2VuAQE=".into()),
        };
        encode_command(&mut buf, "A006", &cmd).unwrap();
        let expected =
            b"A006 AUTHENTICATE XOAUTH2 dXNlcj1hQGIuY29tAWF1dGg9QmVhcmVyIHRva2VuAQE=\r\n";
        assert_eq!(&buf[..], &expected[..]);
    }

    #[test]
    fn encode_authenticate_without_sasl_ir() {
        let mut buf = BytesMut::new();
        let cmd = Command::Authenticate {
            mechanism: "PLAIN".into(),
            initial_response: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 AUTHENTICATE PLAIN\r\n");
    }

    #[test]
    fn encode_starttls() {
        let mut buf = BytesMut::new();
        encode_command(&mut buf, "A001", &Command::StartTls).unwrap();
        assert_eq!(&buf[..], b"A001 STARTTLS\r\n");
    }

    #[test]
    fn encode_logout() {
        let mut buf = BytesMut::new();
        encode_command(&mut buf, "A001", &Command::Logout).unwrap();
        assert_eq!(&buf[..], b"A001 LOGOUT\r\n");
    }

    #[test]
    fn encode_capability() {
        let mut buf = BytesMut::new();
        encode_command(&mut buf, "A001", &Command::Capability).unwrap();
        assert_eq!(&buf[..], b"A001 CAPABILITY\r\n");
    }

    #[test]
    fn encode_noop() {
        let mut buf = BytesMut::new();
        encode_command(&mut buf, "A001", &Command::Noop).unwrap();
        assert_eq!(&buf[..], b"A001 NOOP\r\n");
    }

    #[test]
    fn encode_expunge() {
        let mut buf = BytesMut::new();
        encode_command(&mut buf, "A001", &Command::Expunge).unwrap();
        assert_eq!(&buf[..], b"A001 EXPUNGE\r\n");
    }

    #[test]
    fn encode_close() {
        let mut buf = BytesMut::new();
        encode_command(&mut buf, "A001", &Command::Close).unwrap();
        assert_eq!(&buf[..], b"A001 CLOSE\r\n");
    }

    #[test]
    fn encode_unselect() {
        let mut buf = BytesMut::new();
        encode_command(&mut buf, "A001", &Command::Unselect).unwrap();
        assert_eq!(&buf[..], b"A001 UNSELECT\r\n");
    }

    #[test]
    fn encode_idle() {
        let mut buf = BytesMut::new();
        encode_command(&mut buf, "A001", &Command::Idle).unwrap();
        assert_eq!(&buf[..], b"A001 IDLE\r\n");
    }

    #[test]
    fn encode_examine() {
        let mut buf = BytesMut::new();
        let cmd = Command::Examine {
            mailbox: "INBOX".into(),
            condstore: false,
            qresync: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 EXAMINE \"INBOX\"\r\n");
    }

    #[test]
    fn encode_create() {
        let mut buf = BytesMut::new();
        let cmd = Command::Create {
            mailbox: "Archive".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 CREATE \"Archive\"\r\n");
    }

    #[test]
    fn encode_create_special_use_single() {
        let mut buf = BytesMut::new();
        let cmd = Command::CreateSpecialUse {
            mailbox: "Sent".into(),
            special_use: vec![crate::types::MailboxAttribute::Sent],
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 CREATE \"Sent\" (USE (\\Sent))\r\n");
    }

    #[test]
    fn encode_create_special_use_multiple() {
        let mut buf = BytesMut::new();
        let cmd = Command::CreateSpecialUse {
            mailbox: "Important Sent".into(),
            special_use: vec![
                crate::types::MailboxAttribute::Sent,
                crate::types::MailboxAttribute::Important,
            ],
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 CREATE \"Important Sent\" (USE (\\Sent \\Important))\r\n"
        );
    }

    #[test]
    fn encode_create_special_use_special_char_mailbox() {
        let mut buf = BytesMut::new();
        let cmd = Command::CreateSpecialUse {
            mailbox: "My Drafts".into(),
            special_use: vec![crate::types::MailboxAttribute::Drafts],
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 CREATE \"My Drafts\" (USE (\\Drafts))\r\n");
    }

    #[test]
    fn encode_create_special_use_empty() {
        // RFC 6154 Section 6 ABNF: `"USE" SP "(" [use-attr *(SP use-attr)] ")"`
        // Brackets mean the use-attr list is optional.
        let mut buf = BytesMut::new();
        let cmd = Command::CreateSpecialUse {
            mailbox: "Test".into(),
            special_use: vec![],
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 CREATE \"Test\" (USE ())\r\n");
    }

    #[test]
    fn encode_delete() {
        let mut buf = BytesMut::new();
        let cmd = Command::Delete {
            mailbox: "OldMail".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 DELETE \"OldMail\"\r\n");
    }

    #[test]
    fn encode_rename() {
        let mut buf = BytesMut::new();
        let cmd = Command::Rename {
            mailbox: "OldName".into(),
            new_name: "NewName".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 RENAME \"OldName\" \"NewName\"\r\n");
    }

    #[test]
    fn encode_list() {
        let mut buf = BytesMut::new();
        let cmd = Command::List {
            reference: String::new(),
            pattern: "*".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 LIST \"\" \"*\"\r\n");
    }

    #[test]
    fn encode_status() {
        let mut buf = BytesMut::new();
        let cmd = Command::Status {
            mailbox: "INBOX".into(),
            items: "(MESSAGES UNSEEN)".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 STATUS \"INBOX\" (MESSAGES UNSEEN)\r\n");
    }

    #[test]
    fn encode_uid_search() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidSearch {
            criteria: "ALL".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 UID SEARCH ALL\r\n");
    }

    #[test]
    fn encode_uid_move() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidMove {
            sequence_set: "1:5".into(),
            mailbox: "Trash".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 UID MOVE 1:5 \"Trash\"\r\n");
    }

    #[test]
    fn encode_uid_copy() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidCopy {
            sequence_set: "10:20".into(),
            mailbox: "Archive".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 UID COPY 10:20 \"Archive\"\r\n");
    }

    #[test]
    fn encode_uid_expunge() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidExpunge {
            sequence_set: "1:3".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 UID EXPUNGE 1:3\r\n");
    }

    #[test]
    fn encode_enable() {
        let mut buf = BytesMut::new();
        let cmd = Command::Enable(vec!["CONDSTORE".into(), "UTF8=ACCEPT".into()]);
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 ENABLE CONDSTORE UTF8=ACCEPT\r\n");
    }

    #[test]
    fn encode_id() {
        let mut buf = BytesMut::new();
        let cmd = Command::Id(vec![
            ("name".into(), Some("myapp".into())),
            ("version".into(), Some("1.0".into())),
        ]);
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 ID (\"name\" \"myapp\" \"version\" \"1.0\")\r\n"
        );
    }

    #[test]
    fn encode_store_replace_flags() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidStore {
            sequence_set: "42".into(),
            operation: crate::types::StoreOperation::Replace,
            flags: vec![crate::types::Flag::Seen],
            unchanged_since: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 UID STORE 42 FLAGS (\\Seen)\r\n");
    }

    /// STORE +FLAGS.SILENT suppresses implicit FETCH (RFC 3501 Section 6.4.6).
    #[test]
    fn encode_uid_store_add_silent() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidStore {
            sequence_set: "1:3".into(),
            operation: crate::types::StoreOperation::AddSilent,
            flags: vec![crate::types::Flag::Seen],
            unchanged_since: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 UID STORE 1:3 +FLAGS.SILENT (\\Seen)\r\n");
    }

    /// STORE -FLAGS.SILENT (RFC 3501 Section 6.4.6).
    #[test]
    fn encode_uid_store_remove_silent() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidStore {
            sequence_set: "5".into(),
            operation: crate::types::StoreOperation::RemoveSilent,
            flags: vec![crate::types::Flag::Deleted],
            unchanged_since: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 UID STORE 5 -FLAGS.SILENT (\\Deleted)\r\n");
    }

    /// STORE FLAGS.SILENT (RFC 3501 Section 6.4.6).
    #[test]
    fn encode_store_replace_silent() {
        let mut buf = BytesMut::new();
        let cmd = Command::Store {
            sequence_set: "10".into(),
            operation: crate::types::StoreOperation::ReplaceSilent,
            flags: vec![crate::types::Flag::Flagged],
            unchanged_since: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 STORE 10 FLAGS.SILENT (\\Flagged)\r\n");
    }

    /// RFC 6851 Section 3.3: The MOVE fallback emulation sequence uses
    /// `UID STORE +FLAGS.SILENT (\Deleted)` — the `.SILENT` modifier is
    /// required to suppress implicit FETCH responses (RFC 3501 Section 6.4.6).
    /// This test documents the wire format that the MOVE fallback path in
    /// `ImapConnection::uid_move` must produce.
    #[test]
    fn encode_uid_store_move_fallback_uses_silent() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidStore {
            sequence_set: "1:5".into(),
            operation: crate::types::StoreOperation::AddSilent,
            flags: vec![crate::types::Flag::Deleted],
            unchanged_since: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 UID STORE 1:5 +FLAGS.SILENT (\\Deleted)\r\n",
            "MOVE fallback must use +FLAGS.SILENT per RFC 6851 Section 3.3"
        );
    }

    #[test]
    fn encode_quoted_with_nul_strips_nul_and_quotes() {
        // RFC 3501 Section 9: NUL (%x00) is stripped; remaining "hasnul" is quotable.
        let mut buf = BytesMut::new();
        encode_quoted_or_literal(&mut buf, b"has\0nul");
        assert_eq!(&buf[..], b"\"hasnul\"");
    }

    #[test]
    fn encode_non_ascii_falls_back_to_literal() {
        // Per RFC 3501 Section 9, quoted-string characters must be in %x01-7F
        // (all ASCII) minus CR, LF, and NUL. Non-ASCII bytes (>0x7F) must use literal form.
        let mut buf = BytesMut::new();
        encode_quoted_or_literal(&mut buf, "café".as_bytes());
        // "café" is 5 bytes in UTF-8: 63 61 66 c3 a9
        assert_eq!(&buf[..], b"{5}\r\ncaf\xc3\xa9");
    }

    #[test]
    fn encode_mailbox_with_special_chars() {
        let mut buf = BytesMut::new();
        let cmd = Command::Select {
            mailbox: r#"folder"name"#.into(),
            condstore: false,
            qresync: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 SELECT \"folder\\\"name\"\r\n");
    }

    #[test]
    fn encode_subscribe() {
        let mut buf = BytesMut::new();
        let cmd = Command::Subscribe {
            mailbox: "INBOX.Sent".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 SUBSCRIBE \"INBOX.Sent\"\r\n");
    }

    #[test]
    fn encode_unsubscribe() {
        let mut buf = BytesMut::new();
        let cmd = Command::Unsubscribe {
            mailbox: "INBOX.Old".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 UNSUBSCRIBE \"INBOX.Old\"\r\n");
    }

    #[test]
    fn encode_lsub() {
        let mut buf = BytesMut::new();
        let cmd = Command::Lsub {
            reference: String::new(),
            pattern: "*".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 LSUB \"\" \"*\"\r\n");
    }

    #[test]
    fn encode_search() {
        let mut buf = BytesMut::new();
        let cmd = Command::Search {
            criteria: "UNSEEN".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 SEARCH UNSEEN\r\n");
    }

    #[test]
    fn encode_fetch() {
        let mut buf = BytesMut::new();
        let cmd = Command::Fetch {
            sequence_set: "1:*".into(),
            items: "(FLAGS)".into(),
            changed_since: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 FETCH 1:* (FLAGS)\r\n");
    }

    #[test]
    fn encode_store() {
        let mut buf = BytesMut::new();
        let cmd = Command::Store {
            sequence_set: "1:3".into(),
            operation: crate::types::StoreOperation::Add,
            flags: vec![crate::types::Flag::Seen],
            unchanged_since: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 STORE 1:3 +FLAGS (\\Seen)\r\n");
    }

    #[test]
    fn encode_copy() {
        let mut buf = BytesMut::new();
        let cmd = Command::Copy {
            sequence_set: "1:5".into(),
            mailbox: "Archive".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 COPY 1:5 \"Archive\"\r\n");
    }

    #[test]
    fn encode_namespace() {
        let mut buf = BytesMut::new();
        encode_command(&mut buf, "A001", &Command::Namespace).unwrap();
        assert_eq!(&buf[..], b"A001 NAMESPACE\r\n");
    }

    #[test]
    fn encode_check() {
        let mut buf = BytesMut::new();
        encode_command(&mut buf, "A001", &Command::Check).unwrap();
        assert_eq!(&buf[..], b"A001 CHECK\r\n");
    }

    #[test]
    fn encode_search_save() {
        let mut buf = BytesMut::new();
        let cmd = Command::SearchSave {
            criteria: "UNSEEN".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 SEARCH RETURN (SAVE) UNSEEN\r\n");
    }

    #[test]
    fn encode_uid_search_save() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidSearchSave {
            criteria: "ALL".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 UID SEARCH RETURN (SAVE) ALL\r\n");
    }

    #[test]
    fn encode_search_return_min_max_count() {
        let mut buf = BytesMut::new();
        let cmd = Command::SearchReturn {
            criteria: "UNSEEN".into(),
            return_opts: vec!["MIN".into(), "MAX".into(), "COUNT".into()],
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 SEARCH RETURN (MIN MAX COUNT) UNSEEN\r\n");
    }

    #[test]
    fn encode_uid_search_return_all() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidSearchReturn {
            criteria: "ALL".into(),
            return_opts: vec!["ALL".into(), "COUNT".into()],
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 UID SEARCH RETURN (ALL COUNT) ALL\r\n");
    }

    #[test]
    fn encode_search_return_empty_opts() {
        let mut buf = BytesMut::new();
        let cmd = Command::SearchReturn {
            criteria: "FLAGGED".into(),
            return_opts: vec![],
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 SEARCH RETURN () FLAGGED\r\n");
    }

    #[test]
    fn encode_list_status() {
        let mut buf = BytesMut::new();
        let cmd = Command::ListStatus {
            reference: String::new(),
            pattern: "*".into(),
            status_items: "MESSAGES UNSEEN".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 LIST \"\" \"*\" RETURN (STATUS (MESSAGES UNSEEN))\r\n"
        );
    }

    #[test]
    fn encode_list_status_with_reference() {
        let mut buf = BytesMut::new();
        let cmd = Command::ListStatus {
            reference: "INBOX".into(),
            pattern: "%".into(),
            status_items: "MESSAGES RECENT UNSEEN".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 LIST \"INBOX\" \"%\" RETURN (STATUS (MESSAGES RECENT UNSEEN))\r\n"
        );
    }

    // --- QUOTA (RFC 2087) encoder tests ---

    #[test]
    fn encode_get_quota() {
        let mut buf = BytesMut::new();
        let cmd = Command::GetQuota {
            root: String::new(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 GETQUOTA \"\"\r\n");
    }

    #[test]
    fn encode_get_quota_named_root() {
        let mut buf = BytesMut::new();
        let cmd = Command::GetQuota {
            root: "user.alice".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 GETQUOTA \"user.alice\"\r\n");
    }

    #[test]
    fn encode_get_quota_root() {
        let mut buf = BytesMut::new();
        let cmd = Command::GetQuotaRoot {
            mailbox: "INBOX".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 GETQUOTAROOT \"INBOX\"\r\n");
    }

    #[test]
    fn encode_get_quota_root_folder() {
        let mut buf = BytesMut::new();
        let cmd = Command::GetQuotaRoot {
            mailbox: "INBOX.Drafts".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 GETQUOTAROOT \"INBOX.Drafts\"\r\n");
    }

    // --- ACL (RFC 4314) encoder tests ---

    #[test]
    fn encode_setacl() {
        let mut buf = BytesMut::new();
        let cmd = Command::SetAcl {
            mailbox: "INBOX".into(),
            identifier: "fred".into(),
            rights: "lrswipcda".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 SETACL \"INBOX\" \"fred\" \"lrswipcda\"\r\n"
        );
    }

    #[test]
    fn encode_deleteacl() {
        let mut buf = BytesMut::new();
        let cmd = Command::DeleteAcl {
            mailbox: "INBOX".into(),
            identifier: "fred".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 DELETEACL \"INBOX\" \"fred\"\r\n");
    }

    #[test]
    fn encode_getacl() {
        let mut buf = BytesMut::new();
        let cmd = Command::GetAcl {
            mailbox: "INBOX".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 GETACL \"INBOX\"\r\n");
    }

    #[test]
    fn encode_listrights() {
        let mut buf = BytesMut::new();
        let cmd = Command::ListRights {
            mailbox: "INBOX".into(),
            identifier: "fred".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 LISTRIGHTS \"INBOX\" \"fred\"\r\n");
    }

    #[test]
    fn encode_myrights() {
        let mut buf = BytesMut::new();
        let cmd = Command::MyRights {
            mailbox: "INBOX".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 MYRIGHTS \"INBOX\"\r\n");
    }

    #[test]
    fn encode_setacl_with_special_chars() {
        let mut buf = BytesMut::new();
        let cmd = Command::SetAcl {
            mailbox: "Shared Folders".into(),
            identifier: "user@example.com".into(),
            rights: "+lrs".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 SETACL \"Shared Folders\" \"user@example.com\" \"+lrs\"\r\n"
        );
    }

    #[test]
    fn encode_getacl_nested_folder() {
        let mut buf = BytesMut::new();
        let cmd = Command::GetAcl {
            mailbox: "INBOX.Sent Items".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 GETACL \"INBOX.Sent Items\"\r\n");
    }

    // --- GETMETADATA / SETMETADATA (RFC 5464) encoder tests ---

    #[test]
    fn encode_getmetadata_single_entry() {
        let mut buf = BytesMut::new();
        let cmd = Command::GetMetadata {
            mailbox: "INBOX".into(),
            entries: vec!["/private/comment".into()],
            max_size: None,
            depth: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 GETMETADATA \"INBOX\" \"/private/comment\"\r\n"
        );
    }

    #[test]
    fn encode_getmetadata_multiple_entries() {
        let mut buf = BytesMut::new();
        let cmd = Command::GetMetadata {
            mailbox: "INBOX".into(),
            entries: vec!["/private/comment".into(), "/shared/vendor/foo".into()],
            max_size: None,
            depth: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 GETMETADATA \"INBOX\" (\"/private/comment\" \"/shared/vendor/foo\")\r\n"
        );
    }

    #[test]
    fn encode_setmetadata_with_values() {
        let mut buf = BytesMut::new();
        let cmd = Command::SetMetadata {
            mailbox: "INBOX".into(),
            entries: vec![("/private/comment".into(), Some(b"my comment".to_vec()))],
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 SETMETADATA \"INBOX\" (\"/private/comment\" \"my comment\")\r\n"
        );
    }

    #[test]
    fn encode_setmetadata_with_nil_delete() {
        let mut buf = BytesMut::new();
        let cmd = Command::SetMetadata {
            mailbox: "INBOX".into(),
            entries: vec![("/private/comment".into(), None)],
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 SETMETADATA \"INBOX\" (\"/private/comment\" NIL)\r\n"
        );
    }

    #[test]
    fn encode_setmetadata_multiple_entries() {
        let mut buf = BytesMut::new();
        let cmd = Command::SetMetadata {
            mailbox: "INBOX".into(),
            entries: vec![
                ("/private/comment".into(), Some(b"hello".to_vec())),
                ("/shared/vendor/x".into(), None),
            ],
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 SETMETADATA \"INBOX\" (\"/private/comment\" \"hello\" \"/shared/vendor/x\" NIL)\r\n"
        );
    }

    /// SETMETADATA values containing NUL bytes must be preserved,
    /// and binary values must use literal8 syntax (`~{N}\r\n<data>`), not
    /// standard literal (`{N}\r\n<data>`).
    ///
    /// RFC 5464 Section 5: `value = nstring / literal8`
    /// RFC 3516: `literal8 = "~{" number "}" CRLF *OCTET` — *OCTET includes NUL (%x00).
    #[test]
    fn encode_setmetadata_literal8_preserves_nul_bytes() {
        let mut buf = BytesMut::new();
        // Binary value with NUL bytes — must not be stripped.
        let value = b"\x00\x01\x02\x03".to_vec();
        let cmd = Command::SetMetadata {
            mailbox: "INBOX".into(),
            entries: vec![("/private/binary".into(), Some(value))],
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        let output = &buf[..];

        // NUL bytes must be preserved in the output (not stripped).
        assert!(
            output.windows(4).any(|w| w == b"\x00\x01\x02\x03"),
            "NUL bytes must be preserved in SETMETADATA values per RFC 3516 literal8 *OCTET"
        );

        // Must use literal8 syntax ~{N}\r\n, not standard literal {N}\r\n.
        assert!(
            output.windows(5).any(|w| w == b"~{4}\r"),
            "Binary SETMETADATA value must use literal8 ~{{N}} syntax per RFC 5464 Section 5 / RFC 3516, got: {:?}",
            String::from_utf8_lossy(output)
        );
    }

    /// SETMETADATA values that are ASCII-safe should still use
    /// quoted string form (nstring), not literal8.
    ///
    /// RFC 5464 Section 5: `value = nstring / literal8` — nstring is preferred
    /// when the data is quotable.
    #[test]
    fn encode_setmetadata_ascii_value_uses_quoted_form() {
        let mut buf = BytesMut::new();
        let cmd = Command::SetMetadata {
            mailbox: "INBOX".into(),
            entries: vec![("/private/comment".into(), Some(b"hello".to_vec()))],
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        // ASCII-safe value should still be quoted, not literal8.
        assert_eq!(
            &buf[..],
            b"A001 SETMETADATA \"INBOX\" (\"/private/comment\" \"hello\")\r\n"
        );
    }

    /// SETMETADATA values with high bytes (>0x7F) must use literal8.
    ///
    /// RFC 5464 Section 5: `value = nstring / literal8`
    /// RFC 3516: `literal8 = "~{" number "}" CRLF *OCTET`
    #[test]
    fn encode_setmetadata_high_bytes_use_literal8() {
        let mut buf = BytesMut::new();
        let value = b"\x80\x81\xff".to_vec();
        let cmd = Command::SetMetadata {
            mailbox: "INBOX".into(),
            entries: vec![("/private/binary".into(), Some(value))],
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        let output = &buf[..];

        // Must use literal8 syntax.
        assert!(
            output.windows(5).any(|w| w == b"~{3}\r"),
            "High-byte SETMETADATA value must use literal8 ~{{N}} syntax per RFC 5464 Section 5, got: {:?}",
            String::from_utf8_lossy(output)
        );

        // High bytes must be preserved.
        assert!(
            output.windows(3).any(|w| w == b"\x80\x81\xff"),
            "High bytes must be preserved in SETMETADATA literal8 values"
        );
    }

    // --- encode_nstring_or_literal8 direct tests (lock down before refactoring) ---

    /// ASCII data with backslash and double-quote must be escaped in quoted form.
    /// RFC 3501 Section 9: quoted-specials = `"` / `\` are escaped with `\`.
    #[test]
    fn nstring_or_literal8_escapes_backslash_and_quote() {
        let mut buf = BytesMut::new();
        encode_nstring_or_literal8(&mut buf, b"a\\b\"c");
        assert_eq!(&buf[..], b"\"a\\\\b\\\"c\"");
    }

    /// ASCII data without special chars uses quoted form.
    #[test]
    fn nstring_or_literal8_ascii_uses_quoted() {
        let mut buf = BytesMut::new();
        encode_nstring_or_literal8(&mut buf, b"hello");
        assert_eq!(&buf[..], b"\"hello\"");
    }

    /// Data with CR/LF uses literal8.
    #[test]
    fn nstring_or_literal8_crlf_uses_literal8() {
        let mut buf = BytesMut::new();
        encode_nstring_or_literal8(&mut buf, b"line1\r\nline2");
        assert_eq!(&buf[..], b"~{12}\r\nline1\r\nline2");
    }

    /// Data with NUL byte uses literal8 (NUL is preserved, not stripped).
    /// RFC 3516: literal8 uses `*OCTET` (%x00-FF).
    #[test]
    fn nstring_or_literal8_nul_uses_literal8() {
        let mut buf = BytesMut::new();
        encode_nstring_or_literal8(&mut buf, b"\x00data");
        // NUL preserved; literal8 form.
        assert_eq!(&buf[..], b"~{5}\r\n\x00data");
    }

    /// Empty data uses empty quoted string.
    #[test]
    fn nstring_or_literal8_empty() {
        let mut buf = BytesMut::new();
        encode_nstring_or_literal8(&mut buf, b"");
        assert_eq!(&buf[..], b"\"\"");
    }

    /// Data with high bytes (>0x7F) uses literal8.
    #[test]
    fn nstring_or_literal8_high_bytes_uses_literal8() {
        let mut buf = BytesMut::new();
        encode_nstring_or_literal8(&mut buf, b"\x80\xff");
        assert_eq!(&buf[..], b"~{2}\r\n\x80\xff");
    }

    // --- THREAD (RFC 5256) encoder tests ---

    #[test]
    fn encode_thread_command() {
        let mut buf = BytesMut::new();
        let cmd = Command::Thread {
            algorithm: "REFERENCES".into(),
            charset: "UTF-8".into(),
            criteria: "ALL".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 THREAD REFERENCES UTF-8 ALL\r\n");
    }

    #[test]
    fn encode_uid_thread_command() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidThread {
            algorithm: "ORDEREDSUBJECT".into(),
            charset: "US-ASCII".into(),
            criteria: "SINCE 1-Jan-2025".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 UID THREAD ORDEREDSUBJECT US-ASCII SINCE 1-Jan-2025\r\n"
        );
    }

    // --- SORT (RFC 5256) encoder tests ---

    #[test]
    fn encode_sort_command() {
        let mut buf = BytesMut::new();
        let cmd = Command::Sort {
            algorithm: "DATE".into(),
            charset: "UTF-8".into(),
            criteria: "ALL".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 SORT (DATE) UTF-8 ALL\r\n");
    }

    #[test]
    fn encode_uid_sort_command() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidSort {
            algorithm: "SUBJECT".into(),
            charset: "US-ASCII".into(),
            criteria: "SINCE 1-Jan-2025".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 UID SORT (SUBJECT) US-ASCII SINCE 1-Jan-2025\r\n"
        );
    }

    // --- COMPRESS (RFC 4978) encoder test ---

    #[test]
    fn encode_compress() {
        let mut buf = BytesMut::new();
        encode_command(&mut buf, "A001", &Command::Compress).unwrap();
        assert_eq!(&buf[..], b"A001 COMPRESS DEFLATE\r\n");
    }

    // --- MULTIAPPEND (RFC 3502) encoder tests ---

    #[test]
    fn encode_multi_append_first_message_no_flags() {
        // First message with no flags and no date (RFC 3502 Section 3).
        let mut buf = BytesMut::new();
        encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[],
            None,
            100,
            true,
            false,
            false,
        )
        .unwrap();
        assert_eq!(&buf[..], b"A001 APPEND \"INBOX\" {100}\r\n");
    }

    #[test]
    fn encode_multi_append_first_message_with_flags() {
        // First message with flags (RFC 3502 Section 3 / RFC 3501 Section 6.3.11).
        let mut buf = BytesMut::new();
        encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[crate::types::Flag::Seen, crate::types::Flag::Flagged],
            None,
            200,
            true,
            false,
            false,
        )
        .unwrap();
        assert_eq!(
            &buf[..],
            b"A001 APPEND \"INBOX\" (\\Seen \\Flagged) {200}\r\n"
        );
    }

    #[test]
    fn encode_multi_append_first_message_with_date() {
        // First message with internal date (RFC 3502 Section 3 / RFC 3501 Section 6.3.11).
        let mut buf = BytesMut::new();
        encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[],
            Some("17-Jul-1996 02:44:25 -0700"),
            50,
            true,
            false,
            false,
        )
        .unwrap();
        assert_eq!(
            &buf[..],
            b"A001 APPEND \"INBOX\" \"17-Jul-1996 02:44:25 -0700\" {50}\r\n"
        );
    }

    #[test]
    fn encode_multi_append_first_message_with_flags_and_date() {
        // First message with both flags and date (RFC 3502 Section 3).
        let mut buf = BytesMut::new();
        encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[crate::types::Flag::Seen],
            Some(" 1-Jan-2024 00:00:00 +0000"),
            300,
            true,
            false,
            false,
        )
        .unwrap();
        assert_eq!(
            &buf[..],
            b"A001 APPEND \"INBOX\" (\\Seen) \" 1-Jan-2024 00:00:00 +0000\" {300}\r\n"
        );
    }

    #[test]
    fn encode_multi_append_subsequent_message() {
        // Subsequent message — no tag/APPEND/mailbox prefix (RFC 3502 Section 3).
        let mut buf = BytesMut::new();
        encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[crate::types::Flag::Draft],
            None,
            75,
            false,
            false,
            false,
        )
        .unwrap();
        assert_eq!(&buf[..], b" (\\Draft) {75}\r\n");
    }

    #[test]
    fn encode_multi_append_with_literal_plus() {
        // LITERAL+ (RFC 7888) — non-synchronizing literal.
        let mut buf = BytesMut::new();
        encode_multi_append_header(&mut buf, "A001", "INBOX", &[], None, 42, true, true, false)
            .unwrap();
        assert_eq!(&buf[..], b"A001 APPEND \"INBOX\" {42+}\r\n");
    }

    #[test]
    fn encode_multi_append_subsequent_with_literal_plus() {
        // Subsequent message with LITERAL+ (RFC 7888 / RFC 3502 Section 3).
        let mut buf = BytesMut::new();
        encode_multi_append_header(&mut buf, "A001", "INBOX", &[], None, 99, false, true, false)
            .unwrap();
        assert_eq!(&buf[..], b" {99+}\r\n");
    }

    #[test]
    fn encode_multi_append_two_messages_mixed_flags() {
        // Simulate a 2-message MULTIAPPEND: first with flags, second without (RFC 3502).
        let mut buf = BytesMut::new();

        // First message: with flags and date
        encode_multi_append_header(
            &mut buf,
            "A010",
            "INBOX",
            &[crate::types::Flag::Seen, crate::types::Flag::Answered],
            Some("15-Mar-2026 10:00:00 +0000"),
            50,
            true,
            false,
            false,
        )
        .unwrap();
        assert_eq!(
            &buf[..],
            b"A010 APPEND \"INBOX\" (\\Seen \\Answered) \"15-Mar-2026 10:00:00 +0000\" {50}\r\n"
        );

        // Simulate literal data would be sent here, then the second header:
        buf.clear();
        encode_multi_append_header(
            &mut buf,
            "A010",
            "INBOX",
            &[],
            None,
            30,
            false,
            false,
            false,
        )
        .unwrap();
        // Subsequent message: no flags, no date — just the literal header.
        assert_eq!(&buf[..], b" {30}\r\n");
    }

    #[test]
    fn encode_multi_append_three_messages_literal_plus() {
        // 3-message MULTIAPPEND with LITERAL+ (RFC 3502 / RFC 7888 Section 4).
        let mut buf = BytesMut::new();

        // Message 1
        encode_multi_append_header(
            &mut buf,
            "A020",
            "Archive",
            &[crate::types::Flag::Seen],
            None,
            100,
            true,
            true,
            false,
        )
        .unwrap();
        let expected1 = b"A020 APPEND \"Archive\" (\\Seen) {100+}\r\n";
        assert_eq!(&buf[..], &expected1[..]);

        // Message 2 (no flags, with date)
        buf.clear();
        encode_multi_append_header(
            &mut buf,
            "A020",
            "Archive",
            &[],
            Some(" 1-Jan-2025 00:00:00 +0000"),
            200,
            false,
            true,
            false,
        )
        .unwrap();
        assert_eq!(&buf[..], b" \" 1-Jan-2025 00:00:00 +0000\" {200+}\r\n");

        // Message 3 (flags only, no date)
        buf.clear();
        encode_multi_append_header(
            &mut buf,
            "A020",
            "Archive",
            &[crate::types::Flag::Flagged],
            None,
            300,
            false,
            true,
            false,
        )
        .unwrap();
        assert_eq!(&buf[..], b" (\\Flagged) {300+}\r\n");
    }

    #[test]
    fn encode_multi_append_subsequent_no_flags_with_date() {
        // Subsequent message with date but no flags (RFC 3502 Section 3).
        let mut buf = BytesMut::new();
        encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[],
            Some("25-Dec-2025 12:00:00 +0000"),
            500,
            false,
            false,
            false,
        )
        .unwrap();
        assert_eq!(&buf[..], b" \"25-Dec-2025 12:00:00 +0000\" {500}\r\n");
    }

    #[test]
    fn encode_multi_append_special_mailbox() {
        // Mailbox name with special characters uses quoting (RFC 3501 Section 9).
        let mut buf = BytesMut::new();
        encode_multi_append_header(
            &mut buf,
            "A001",
            r#"folder"name"#,
            &[],
            None,
            10,
            true,
            false,
            false,
        )
        .unwrap();
        assert_eq!(&buf[..], b"A001 APPEND \"folder\\\"name\" {10}\r\n");
    }

    // ===== Negative / edge-case encoding tests =====

    /// NUL byte in data is stripped per RFC 3501 Section 9 (CHAR8 = %x01-ff).
    #[test]
    fn encode_data_with_nul_byte_strips_nul() {
        let mut buf = BytesMut::new();
        encode_quoted_or_literal(&mut buf, b"hello\x00world");
        // NUL is stripped; "helloworld" is quotable ASCII.
        assert_eq!(&buf[..], b"\"helloworld\"");
        assert!(!buf.contains(&0x00), "output must not contain NUL bytes");
    }

    /// Non-ASCII bytes force literal encoding.
    #[test]
    fn encode_data_with_non_ascii_uses_literal() {
        let mut buf = BytesMut::new();
        encode_quoted_or_literal(&mut buf, "café".as_bytes());
        // Non-ASCII (0x80+) is not quotable
        assert!(buf.starts_with(b"{5}\r\n"));
    }

    /// Empty data encodes as empty quoted string.
    #[test]
    fn encode_empty_data_quoted() {
        let mut buf = BytesMut::new();
        encode_quoted_or_literal(&mut buf, b"");
        assert_eq!(&buf[..], b"\"\"");
    }

    /// Mailbox name with spaces gets properly quoted in SELECT.
    #[test]
    fn encode_select_mailbox_with_spaces() {
        let mut buf = BytesMut::new();
        let cmd = Command::Select {
            mailbox: "my folder".into(),
            condstore: false,
            qresync: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 SELECT \"my folder\"\r\n");
    }

    /// Login with CRLF in password falls back to literal.
    #[test]
    fn encode_login_crlf_in_password_uses_literal() {
        let mut buf = BytesMut::new();
        encode_login(&mut buf, "A001", "user", "pass\r\nword");
        // CRLF in password means it can't be quoted
        let output = String::from_utf8_lossy(&buf);
        assert!(
            output.contains("{10}\r\n"),
            "expected literal for password with CRLF"
        );
    }

    /// Very long quoted string is still properly quoted if all chars are quotable.
    #[test]
    fn encode_long_quotable_string() {
        let mut buf = BytesMut::new();
        let data = "a".repeat(10_000);
        encode_quoted_or_literal(&mut buf, data.as_bytes());
        // Should still be quoted since all chars are safe
        assert!(buf.starts_with(b"\""));
        assert!(buf.ends_with(b"\""));
        assert_eq!(buf.len(), 10_002); // 10000 + 2 quotes
    }

    // ===== DEL (0x7F) is a valid TEXT-CHAR =====
    // RFC 3501 Section 9: CHAR = %x01-7F, TEXT-CHAR = <any CHAR except CR and LF>
    // DEL (0x7F) is within CHAR range and is not CR/LF, so it must be quotable.

    #[test]
    fn encode_del_char_uses_quoted_form() {
        let mut buf = BytesMut::new();
        encode_quoted_or_literal(&mut buf, &[0x7F]);
        assert!(
            buf.starts_with(b"\""),
            "DEL (0x7F) is a valid TEXT-CHAR per RFC 3501 Section 9 and should use quoted form, \
             got literal form instead"
        );
    }

    // ===== non-UID MOVE command (RFC 6851 Section 3) =====
    // RFC 6851 Section 5: move = "MOVE" SP sequence-set SP mailbox
    // Both UID MOVE and non-UID MOVE must be supported.

    /// Non-UID MOVE command encoding (RFC 6851 Section 3).
    #[test]
    fn encode_move() {
        let mut buf = BytesMut::new();
        let cmd = Command::Move {
            sequence_set: "1:5".into(),
            mailbox: "Trash".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 MOVE 1:5 \"Trash\"\r\n");
    }

    // ===== ENABLE with zero args (RFC 5161 ABNF) =====
    // RFC 5161: command-any =/ "ENABLE" 1*(SP capability)
    // At least one capability is required.

    /// ENABLE with no arguments returns an error at the encoder level (RFC 5161).
    ///
    /// RFC 5161 ABNF: `"ENABLE" 1*(SP capability)` — at least one capability required.
    #[test]
    fn encode_enable_empty_args() {
        let mut buf = BytesMut::new();
        let cmd = Command::Enable(vec![]);
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "ENABLE with empty capabilities must fail (RFC 5161)"
        );
    }

    // ===== Audit: #6 ID empty params → NIL =====
    // RFC 2971 Section 3.1: the request is either a parenthesized list
    // or NIL. An empty parenthesized list "()" is not valid.

    /// Empty ID params should produce `ID NIL` per RFC 2971 Section 3.1.
    #[test]
    fn regression_encode_id_empty_params() {
        let mut buf = BytesMut::new();
        let cmd = Command::Id(vec![]);
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 ID NIL\r\n",
            "empty ID params should produce ID NIL per RFC 2971 Section 3.1"
        );
    }

    // ===== RFC 2971 Section 3.3 ID command limits =====
    // RFC 2971 Section 3.3: "Implementations MUST NOT send more than
    // 30 field-value pairs." / "Field strings MUST NOT be longer than
    // 30 octets." / "Value strings MUST NOT be longer than 1024 octets."

    /// RFC 2971 Section 3.3: more than 30 field-value pairs MUST be rejected.
    #[test]
    fn encode_id_rejects_more_than_30_pairs() {
        let mut buf = BytesMut::new();
        let params: Vec<(String, Option<String>)> = (0..31)
            .map(|i| (format!("k{i}"), Some(format!("v{i}"))))
            .collect();
        let cmd = Command::Id(params);
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "ID with 31 pairs must be rejected per RFC 2971 Section 3.3"
        );
        let msg = result.unwrap_err().to_string();
        assert!(
            msg.contains("RFC 2971"),
            "error message should cite RFC 2971, got: {msg}"
        );
    }

    /// RFC 2971 Section 3.3: field strings longer than 30 octets MUST be rejected.
    #[test]
    fn encode_id_rejects_key_longer_than_30_octets() {
        let mut buf = BytesMut::new();
        let long_key = "a".repeat(31);
        let cmd = Command::Id(vec![(long_key, Some("value".into()))]);
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "ID with key > 30 octets must be rejected per RFC 2971 Section 3.3"
        );
        let msg = result.unwrap_err().to_string();
        assert!(
            msg.contains("RFC 2971"),
            "error message should cite RFC 2971, got: {msg}"
        );
    }

    /// RFC 2971 Section 3.3: value strings longer than 1024 octets MUST be rejected.
    #[test]
    fn encode_id_rejects_value_longer_than_1024_octets() {
        let mut buf = BytesMut::new();
        let long_value = "v".repeat(1025);
        let cmd = Command::Id(vec![("key".into(), Some(long_value))]);
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "ID with value > 1024 octets must be rejected per RFC 2971 Section 3.3"
        );
        let msg = result.unwrap_err().to_string();
        assert!(
            msg.contains("RFC 2971"),
            "error message should cite RFC 2971, got: {msg}"
        );
    }

    /// RFC 2971 Section 3.3: exactly 30 pairs with 30-byte keys and 1024-byte
    /// values must succeed (boundary check).
    #[test]
    fn encode_id_accepts_exactly_at_limits() {
        let mut buf = BytesMut::new();
        let key = "k".repeat(30); // exactly 30 octets
        let value = "v".repeat(1024); // exactly 1024 octets
        let params: Vec<(String, Option<String>)> = (0..30)
            .map(|_| (key.clone(), Some(value.clone())))
            .collect();
        let cmd = Command::Id(params);
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_ok(),
            "ID with exactly 30 pairs, 30-byte keys, and 1024-byte values \
             should succeed per RFC 2971 Section 3.3, got: {:?}",
            result.unwrap_err()
        );
    }

    // M11: QRESYNC seq-match-data encoding (RFC 7162 Section 3.2.5.2)
    #[test]
    fn encode_select_qresync_seq_match_data() {
        let mut buf = BytesMut::new();
        let cmd = Command::Select {
            mailbox: "INBOX".into(),
            condstore: false,
            qresync: Some(QresyncParams {
                uid_validity: 67890,
                mod_seq: 12345,
                known_uids: Some("1:500".into()),
                seq_match_data: Some(("1:3".into(), "100:102".into())),
            }),
        };
        encode_command(&mut buf, "A008", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A008 SELECT \"INBOX\" (QRESYNC (67890 12345 1:500 (1:3 100:102)))\r\n"
        );
    }

    // M13: CONDSTORE SELECT parameter (RFC 7162 Section 3.1.1)
    #[test]
    fn encode_select_condstore() {
        let mut buf = BytesMut::new();
        let cmd = Command::Select {
            mailbox: "INBOX".into(),
            condstore: true,
            qresync: None,
        };
        encode_command(&mut buf, "A009", &cmd).unwrap();
        assert_eq!(&buf[..], b"A009 SELECT \"INBOX\" (CONDSTORE)\r\n");
    }

    #[test]
    fn encode_examine_condstore() {
        let mut buf = BytesMut::new();
        let cmd = Command::Examine {
            mailbox: "INBOX".into(),
            condstore: true,
            qresync: None,
        };
        encode_command(&mut buf, "A010", &cmd).unwrap();
        assert_eq!(&buf[..], b"A010 EXAMINE \"INBOX\" (CONDSTORE)\r\n");
    }

    // L14: FETCH CHANGEDSINCE modifier (RFC 7162 Section 3.1.4.1)

    #[test]
    fn encode_fetch_changedsince() {
        let mut buf = BytesMut::new();
        let cmd = Command::Fetch {
            sequence_set: "1:*".into(),
            items: "(FLAGS)".into(),
            changed_since: Some(12345),
        };
        encode_command(&mut buf, "A011", &cmd).unwrap();
        assert_eq!(&buf[..], b"A011 FETCH 1:* (FLAGS) (CHANGEDSINCE 12345)\r\n");
    }

    #[test]
    fn encode_fetch_no_changedsince() {
        let mut buf = BytesMut::new();
        let cmd = Command::Fetch {
            sequence_set: "1:10".into(),
            items: "(UID)".into(),
            changed_since: None,
        };
        encode_command(&mut buf, "A012", &cmd).unwrap();
        assert_eq!(&buf[..], b"A012 FETCH 1:10 (UID)\r\n");
    }

    #[test]
    fn encode_uid_fetch_changedsince() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidFetch {
            sequence_set: "1:500".into(),
            items: "(FLAGS ENVELOPE)".into(),
            changed_since: Some(67890),
            vanished: false,
        };
        encode_command(&mut buf, "A013", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A013 UID FETCH 1:500 (FLAGS ENVELOPE) (CHANGEDSINCE 67890)\r\n"
        );
    }

    // RFC 7162 Section 3.2.6: UID FETCH CHANGEDSINCE VANISHED modifier

    #[test]
    fn encode_uid_fetch_changedsince_vanished() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidFetch {
            sequence_set: "1:*".into(),
            items: "(FLAGS)".into(),
            changed_since: Some(12345),
            vanished: true,
        };
        encode_command(&mut buf, "A014", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A014 UID FETCH 1:* (FLAGS) (CHANGEDSINCE 12345 VANISHED)\r\n"
        );
    }

    #[test]
    fn encode_uid_fetch_vanished_without_changedsince_rejected() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidFetch {
            sequence_set: "1:*".into(),
            items: "(FLAGS)".into(),
            changed_since: None,
            vanished: true,
        };
        let result = encode_command(&mut buf, "A015", &cmd);
        assert!(
            result.is_err(),
            "VANISHED without CHANGEDSINCE must be rejected per RFC 7162 Section 3.2.6"
        );
    }

    #[test]
    fn encode_uid_fetch_changedsince_without_vanished_unchanged() {
        // Existing behavior: CHANGEDSINCE alone, vanished=false
        let mut buf = BytesMut::new();
        let cmd = Command::UidFetch {
            sequence_set: "1:500".into(),
            items: "(FLAGS ENVELOPE)".into(),
            changed_since: Some(67890),
            vanished: false,
        };
        encode_command(&mut buf, "A016", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A016 UID FETCH 1:500 (FLAGS ENVELOPE) (CHANGEDSINCE 67890)\r\n"
        );
    }

    // L15: SETQUOTA command (RFC 2087 Section 4.1)

    #[test]
    fn encode_setquota_single_resource() {
        let mut buf = BytesMut::new();
        let cmd = Command::SetQuota {
            root: String::new(),
            resources: vec![("STORAGE".into(), 51200)],
        };
        encode_command(&mut buf, "A014", &cmd).unwrap();
        assert_eq!(&buf[..], b"A014 SETQUOTA \"\" (STORAGE 51200)\r\n");
    }

    #[test]
    fn encode_setquota_multiple_resources() {
        let mut buf = BytesMut::new();
        let cmd = Command::SetQuota {
            root: "user.alice".into(),
            resources: vec![("STORAGE".into(), 102_400), ("MESSAGE".into(), 5000)],
        };
        encode_command(&mut buf, "A015", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A015 SETQUOTA \"user.alice\" (STORAGE 102400 MESSAGE 5000)\r\n"
        );
    }

    #[test]
    fn encode_setquota_empty_resources() {
        let mut buf = BytesMut::new();
        let cmd = Command::SetQuota {
            root: String::new(),
            resources: vec![],
        };
        encode_command(&mut buf, "A016", &cmd).unwrap();
        // Empty resource list: SETQUOTA "" ()
        assert_eq!(&buf[..], b"A016 SETQUOTA \"\" ()\r\n");
    }

    // ===== Spec audit: failing tests for known deviations =====

    /// M4: NUL bytes in literal encoder.
    ///
    /// RFC 3501 Section 9 defines CHAR8 = %x01-ff, explicitly excluding NUL (%x00).
    /// Rule (3): "The ASCII NUL... MUST NOT be used at any time."
    /// The encoder strips NUL bytes before encoding.
    #[test]
    fn spec_audit_m4_nul_bytes_in_literal() {
        let mut buf = BytesMut::new();
        encode_quoted_or_literal(&mut buf, b"has\0nul");
        // RFC 3501 Section 9: NUL (%x00) MUST NOT appear in the output.
        // The output must not contain a NUL byte, regardless of encoding form.
        assert!(
            !buf.contains(&0x00),
            "encoder must reject or strip NUL bytes per RFC 3501 Section 9 (CHAR8 = %x01-ff), \
             but the output contains NUL: {:?}",
            &buf[..]
        );
    }

    /// L2: \\Recent in STORE command.
    ///
    /// RFC 3501 Section 9: the `flag` production excludes `\Recent`.
    /// STORE uses `flag` (not `flag-fetch`), so `\Recent` is not permitted.
    /// The encoder silently skips `\Recent` (and `\*`) in STORE and APPEND.
    #[test]
    fn spec_audit_l2_recent_in_store() {
        let mut buf = BytesMut::new();
        let cmd = Command::Store {
            sequence_set: "1:5".into(),
            operation: crate::types::StoreOperation::Add,
            flags: vec![crate::types::Flag::Seen, crate::types::Flag::Recent],
            unchanged_since: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        let output = std::str::from_utf8(&buf).unwrap();
        // RFC 3501 Section 9: \Recent must NOT appear in STORE output.
        assert!(
            !output.contains("\\Recent"),
            "encoder must skip \\Recent in STORE per RFC 3501 Section 9, \
             but output contains it: {output}"
        );
        // \Seen should still be present.
        assert!(
            output.contains("\\Seen"),
            "\\Seen should still be present in output: {output}"
        );
    }

    /// L14: Validate sequence set format.
    ///
    /// RFC 3501 Section 9: `sequence-set = (seq-number / seq-range) *("," sequence-set)`
    /// where `seq-number = nz-number / "*"` and `nz-number = digit-nz *DIGIT`.
    /// Invalid sequence sets like empty strings, alphabetic text, or space-separated
    /// numbers must be rejected. The encoder catches these via `debug_assert!` which
    /// fires in test/debug builds.
    #[test]
    #[should_panic(expected = "invalid sequence set")]
    fn spec_audit_l14_invalid_sequence_set() {
        let mut buf = BytesMut::new();
        let cmd = Command::Fetch {
            sequence_set: "abc".into(),
            items: "(UID)".into(),
            changed_since: None,
        };
        // This should panic via debug_assert! because "abc" is not a valid
        // sequence set per RFC 3501 Section 9.
        encode_command(&mut buf, "A001", &cmd).unwrap();
    }

    // ===== Audit finding #1: APPEND lacks RFC 6855 UTF8 data extension =====

    /// RFC 6855 Section 4: when UTF8=ACCEPT has been enabled, APPEND of a
    /// message with UTF-8 headers MUST use the `UTF8` APPEND data extension:
    /// `APPEND <mailbox> UTF8 (~{size[+]}\r\n<message>)`.
    #[test]
    fn audit_finding1_append_header_with_utf8_extension() {
        let mut buf = BytesMut::new();
        encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[],
            None,
            100,
            true,  // first message
            false, // no literal+
            true,  // utf8 mode
        )
        .unwrap();
        let output = std::str::from_utf8(&buf).unwrap();
        assert_eq!(
            output, "A001 APPEND \"INBOX\" UTF8 (~{100}\r\n",
            "RFC 6855 Section 4: UTF8 APPEND data extension"
        );
    }

    /// Without UTF8 mode, the classic form is used.
    #[test]
    fn audit_finding1_append_header_classic_without_utf8() {
        let mut buf = BytesMut::new();
        encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[],
            None,
            100,
            true,
            false,
            false, // no utf8
        )
        .unwrap();
        let output = std::str::from_utf8(&buf).unwrap();
        assert_eq!(output, "A001 APPEND \"INBOX\" {100}\r\n");
        assert!(!output.contains("UTF8"));
    }

    // ===== Audit finding #3: QRESYNC encoder fabricates known_uids =====

    /// RFC 7162 Section 3.2.5.2 ABNF:
    /// `"QRESYNC" SP "(" uidvalidity SP mod-sequence-value
    ///   [SP known-uids] [SP seq-match-data] ")"`
    ///
    /// `seq-match-data` is only valid after `known-uids`. The encoder must
    /// NOT silently inject `1:*` as a placeholder when `seq_match_data` is
    /// provided without `known_uids` — it must return an error.
    #[test]
    fn audit_finding3_qresync_rejects_seq_match_without_known_uids() {
        use crate::types::response::QresyncParams;

        let params = QresyncParams {
            uid_validity: 67890,
            mod_seq: 12345,
            known_uids: None,
            seq_match_data: Some(("1:100".into(), "1:100".into())),
        };
        let mut buf = BytesMut::new();
        // Must return Err because seq_match_data is present without known_uids.
        let result =
            encode_select_or_examine(&mut buf, "A001", "SELECT", "INBOX", false, Some(&params));
        assert!(
            result.is_err(),
            "seq-match-data without known-uids must return Err (RFC 7162 Section 3.2.5.2)"
        );
    }

    /// QRESYNC with valid `known_uids` + `seq_match_data` encodes correctly.
    #[test]
    fn audit_finding3_qresync_valid_known_uids_with_seq_match() {
        use crate::types::response::QresyncParams;

        let params = QresyncParams {
            uid_validity: 67890,
            mod_seq: 12345,
            known_uids: Some("1:500".into()),
            seq_match_data: Some(("1:100".into(), "1:100".into())),
        };
        let mut buf = BytesMut::new();
        encode_select_or_examine(&mut buf, "A001", "SELECT", "INBOX", false, Some(&params))
            .unwrap();
        let output = std::str::from_utf8(&buf).unwrap();

        // Valid case: known_uids is present, so seq_match_data is legal.
        assert!(
            output.contains("1:500"),
            "known_uids should appear in output: {output}"
        );
        assert!(
            output.contains("(1:100 1:100)"),
            "seq_match_data should appear in output: {output}"
        );
        assert!(
            !output.contains("1:*"),
            "should NOT contain fabricated 1:* when known_uids is provided: {output}"
        );
    }

    /// QRESYNC with `known_uids` but no `seq_match_data` encodes correctly.
    #[test]
    fn audit_finding3_qresync_known_uids_without_seq_match() {
        use crate::types::response::QresyncParams;

        let params = QresyncParams {
            uid_validity: 67890,
            mod_seq: 12345,
            known_uids: Some("1:500".into()),
            seq_match_data: None,
        };
        let mut buf = BytesMut::new();
        encode_select_or_examine(&mut buf, "A001", "SELECT", "INBOX", false, Some(&params))
            .unwrap();
        let output = std::str::from_utf8(&buf).unwrap();
        assert_eq!(
            output, "A001 SELECT \"INBOX\" (QRESYNC (67890 12345 1:500))\r\n",
            "QRESYNC with known_uids but no seq_match_data"
        );
    }

    // ===== Audit finding #7: METADATA encoding lacks MAXSIZE/DEPTH options =====

    /// RFC 5464 Section 4.2 allows GETMETADATA with options:
    /// `GETMETADATA [options] <mailbox> <entries>`
    /// where options include `MAXSIZE n` and `DEPTH ("0"|"1"|"infinity")`.
    ///
    /// The current `encode_getmetadata` does not accept or encode these options.
    /// GETMETADATA without options (backward compatible).
    #[test]
    fn audit_finding7_getmetadata_without_options() {
        let mut buf = BytesMut::new();
        encode_getmetadata(
            &mut buf,
            "A001",
            "INBOX",
            &["/private/comment".to_owned()],
            None,
            None,
        )
        .unwrap();
        let output = std::str::from_utf8(&buf).unwrap();
        assert_eq!(
            output,
            "A001 GETMETADATA \"INBOX\" \"/private/comment\"\r\n",
        );
    }

    /// GETMETADATA with MAXSIZE and DEPTH options (RFC 5464 Section 4.2.2).
    #[test]
    fn audit_finding7_getmetadata_with_maxsize_and_depth() {
        let mut buf = BytesMut::new();
        encode_getmetadata(
            &mut buf,
            "A001",
            "INBOX",
            &["/private/comment".to_owned()],
            Some(1024),
            Some("infinity"),
        )
        .unwrap();
        let output = std::str::from_utf8(&buf).unwrap();
        assert_eq!(
            output,
            "A001 GETMETADATA \"INBOX\" (MAXSIZE 1024 DEPTH infinity) \"/private/comment\"\r\n",
        );
    }

    /// GETMETADATA with only MAXSIZE option.
    #[test]
    fn audit_finding7_getmetadata_with_maxsize_only() {
        let mut buf = BytesMut::new();
        encode_getmetadata(
            &mut buf,
            "A001",
            "INBOX",
            &["/private/comment".to_owned()],
            Some(2048),
            None,
        )
        .unwrap();
        let output = std::str::from_utf8(&buf).unwrap();
        assert_eq!(
            output,
            "A001 GETMETADATA \"INBOX\" (MAXSIZE 2048) \"/private/comment\"\r\n",
        );
    }

    /// GETMETADATA with only DEPTH option.
    #[test]
    fn audit_finding7_getmetadata_with_depth_only() {
        let mut buf = BytesMut::new();
        encode_getmetadata(
            &mut buf,
            "A001",
            "INBOX",
            &["/private/comment".to_owned()],
            None,
            Some("1"),
        )
        .unwrap();
        let output = std::str::from_utf8(&buf).unwrap();
        assert_eq!(
            output,
            "A001 GETMETADATA \"INBOX\" (DEPTH 1) \"/private/comment\"\r\n",
        );
    }

    // ===== Audit finding #8: SORT/SETQUOTA commands encode correctly =====

    /// The SORT command encoder exists internally even though the public
    /// API does not expose it. Verify encoding is correct so that when
    /// finding #8 is fixed (public API exposure), the wire format is ready.
    ///
    /// Note: the encoder wraps the algorithm field in parentheses, so
    /// the `algorithm` field should contain just the sort keys (e.g. `"DATE"`),
    /// not the parens themselves.
    #[test]
    fn audit_finding8_sort_command_encodes_correctly() {
        let mut buf = BytesMut::new();
        let cmd = Command::Sort {
            algorithm: "DATE".into(),
            charset: "UTF-8".into(),
            criteria: "ALL".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        let output = std::str::from_utf8(&buf).unwrap();
        assert_eq!(
            output, "A001 SORT (DATE) UTF-8 ALL\r\n",
            "SORT command should encode correctly (RFC 5256 Section 2)"
        );
    }

    /// UID SORT command encoding.
    #[test]
    fn audit_finding8_uid_sort_command_encodes_correctly() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidSort {
            algorithm: "REVERSE DATE".into(),
            charset: "UTF-8".into(),
            criteria: "SINCE 1-Jan-2024".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        let output = std::str::from_utf8(&buf).unwrap();
        assert_eq!(
            output, "A001 UID SORT (REVERSE DATE) UTF-8 SINCE 1-Jan-2024\r\n",
            "UID SORT command should encode correctly (RFC 5256 Section 2)"
        );
    }

    /// SETQUOTA command encoding.
    #[test]
    fn audit_finding8_setquota_command_encodes_correctly() {
        let mut buf = BytesMut::new();
        let cmd = Command::SetQuota {
            root: String::new(),
            resources: vec![("STORAGE".into(), 51200)],
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        let output = std::str::from_utf8(&buf).unwrap();
        assert_eq!(
            output, "A001 SETQUOTA \"\" (STORAGE 51200)\r\n",
            "SETQUOTA command should encode correctly (RFC 2087 Section 4.1)"
        );
    }

    // =====================================================================
    // Audit tests (2026-03-16)
    // =====================================================================

    /// H3: Single-message APPEND must filter `\Recent` and `\*`.
    /// RFC 3501 Section 9: `flag` excludes `\Recent` and `\*`.
    #[test]
    fn audit_h3_single_append_filters_recent_and_wildcard() {
        let flags = vec![
            crate::types::Flag::Seen,
            crate::types::Flag::Recent,
            crate::types::Flag::Wildcard,
            crate::types::Flag::Flagged,
        ];
        let mut buf = BytesMut::new();
        encode_multi_append_header(
            &mut buf, "A001", "INBOX", &flags, None, 10, true, false, false,
        )
        .unwrap();
        let output = std::str::from_utf8(&buf).unwrap();
        assert!(
            !output.contains("\\Recent"),
            "must filter \\Recent: {output}"
        );
        assert!(!output.contains("\\*"), "must filter \\*: {output}");
        assert!(output.contains("\\Seen"), "must keep \\Seen");
        assert!(output.contains("\\Flagged"), "must keep \\Flagged");
    }

    /// L8: STORE with all flags filtered must produce a valid empty flag-list `()`.
    ///
    /// RFC 3501 Section 9 ABNF:
    /// `store-att-flags = (["+" / "-"] "FLAGS" [".SILENT"]) SP (flag-list / (flag *(SP flag)))`
    /// The SP and flag-list are mandatory; an empty flag-list is `()`.
    #[test]
    fn audit_l8_store_all_flags_filtered() {
        let mut buf = BytesMut::new();
        let cmd = Command::Store {
            sequence_set: "1:5".into(),
            operation: crate::types::StoreOperation::Add,
            flags: vec![crate::types::Flag::Recent, crate::types::Flag::Wildcard],
            unchanged_since: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        let output = std::str::from_utf8(&buf).unwrap();
        assert!(
            output.contains("+FLAGS ()"),
            "all-filtered STORE must produce empty flag-list '()' per RFC 3501 Section 9: '{output}'"
        );
    }

    /// L10: AUTHENTICATE with empty initial response must send `=`.
    /// RFC 4959 Section 3.
    #[test]
    fn audit_l10_authenticate_empty_initial_response() {
        let mut buf = BytesMut::new();
        let cmd = Command::Authenticate {
            mechanism: "PLAIN".into(),
            initial_response: Some(String::new()),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        let output = std::str::from_utf8(&buf).unwrap();
        assert!(
            output.contains(" =\r\n"),
            "empty initial response must be '=': '{output}'"
        );
    }

    /// L9: `validate_sequence_set` rejects invalid input.
    #[test]
    fn audit_l9_validate_sequence_set_rejects_invalid() {
        assert!(!validate_sequence_set("abc"));
        assert!(!validate_sequence_set("0"));
        assert!(!validate_sequence_set(""));
        assert!(!validate_sequence_set("1,,2"));
        assert!(validate_sequence_set("1:*"));
        assert!(validate_sequence_set("1,2,3"));
    }

    /// RFC 3501 Section 9: `nz-number` is a non-zero unsigned 32-bit integer
    /// (0 < n < 4,294,967,296). Values exceeding `u32::MAX` must be rejected.
    #[test]
    fn validate_sequence_set_rejects_overflow_u32() {
        // 99999999999 exceeds u32::MAX (4294967295)
        assert!(!validate_sequence_set("99999999999"));
        // u32::MAX itself is valid
        assert!(validate_sequence_set("4294967295"));
        // u32::MAX + 1 is invalid
        assert!(!validate_sequence_set("4294967296"));
        // Very large number in a range
        assert!(!validate_sequence_set("1:99999999999"));
        assert!(!validate_sequence_set("99999999999:1"));
    }

    /// RFC 3501 Section 9: encoding a command with an invalid sequence set
    /// (e.g. "0", "", "abc") must panic even in release builds, not silently
    /// send a protocol-violating command.
    #[test]
    #[should_panic(expected = "invalid sequence set per RFC 3501 Section 9")]
    fn encode_fetch_with_zero_sequence_set_panics() {
        let mut buf = BytesMut::new();
        let cmd = Command::Fetch {
            sequence_set: "0".into(),
            items: "(FLAGS)".into(),
            changed_since: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
    }

    /// RFC 3501 Section 9: encoding with empty sequence set must panic.
    #[test]
    #[should_panic(expected = "invalid sequence set per RFC 3501 Section 9")]
    fn encode_uid_store_with_empty_sequence_set_panics() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidStore {
            sequence_set: String::new(),
            operation: crate::types::StoreOperation::Add,
            flags: vec![crate::types::Flag::Seen],
            unchanged_since: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
    }

    /// RFC 3501 Section 9: encoding with non-numeric sequence set must panic.
    #[test]
    #[should_panic(expected = "invalid sequence set per RFC 3501 Section 9")]
    fn encode_copy_with_alphabetic_sequence_set_panics() {
        let mut buf = BytesMut::new();
        let cmd = Command::Copy {
            sequence_set: "abc".into(),
            mailbox: "Trash".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
    }

    /// RFC 3501 Section 9: encoding with u32-overflow sequence set must panic.
    #[test]
    #[should_panic(expected = "invalid sequence set per RFC 3501 Section 9")]
    fn encode_uid_fetch_with_overflow_sequence_set_panics() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidFetch {
            sequence_set: "99999999999".into(),
            items: "(UID)".into(),
            changed_since: None,
            vanished: false,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
    }

    /// Project rule: "Errors, not panics." `encode_command` must return
    /// an error for invalid sequence sets rather than panicking
    /// (RFC 3501 Section 9: sequence-set formal syntax).
    #[test]
    fn encode_command_rejects_invalid_sequence_set_without_panic() {
        let mut buf = BytesMut::new();
        let cmd = Command::Fetch {
            sequence_set: "0".into(), // Invalid: nz-number does not allow 0
            items: "(FLAGS)".into(),
            changed_since: None,
        };
        // Should return Err, not panic.
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "Invalid sequence set '0' should return Err"
        );
    }

    /// ID command values can be NIL per RFC 2971 Section 3.1.
    ///
    /// RFC 2971 Section 3.1: `id_params_list ::= "(" #(string SPACE nstring) ")" / nil`
    /// Values are `nstring` — `None` must encode as `NIL` on the wire.
    #[test]
    fn encode_id_nil_value() {
        let mut buf = BytesMut::new();
        let cmd = Command::Id(vec![
            ("name".into(), Some("myapp".into())),
            ("version".into(), None),
        ]);
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 ID (\"name\" \"myapp\" \"version\" NIL)\r\n",
            "None value must encode as NIL per RFC 2971 Section 3.1"
        );
    }

    /// SETQUOTA with limit at `u32::MAX` boundary must succeed (RFC 2087 Section 4.1).
    ///
    /// RFC 2087 Section 4.1 uses `number` for resource limits, which per
    /// RFC 3501 Section 9 is a 32-bit unsigned integer (0..4294967295).
    /// A limit of exactly `u32::MAX` must encode successfully.
    #[test]
    fn encode_setquota_limit_at_u32_max_succeeds() {
        let mut buf = BytesMut::new();
        let cmd = Command::SetQuota {
            root: String::new(),
            resources: vec![("STORAGE".into(), u64::from(u32::MAX))],
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_ok(),
            "SETQUOTA with limit = u32::MAX must succeed (RFC 2087 Section 4.1)"
        );
        assert_eq!(&buf[..], b"A001 SETQUOTA \"\" (STORAGE 4294967295)\r\n");
    }

    /// SETQUOTA with limit exceeding `u32::MAX` must return an error
    /// (RFC 2087 Section 4.1).
    ///
    /// RFC 2087 Section 4.1: `setquota_resource = atom SP number`.
    /// RFC 3501 Section 9: `number = 1*DIGIT` — constrained to u32.
    /// Values > 4294967295 are invalid on the wire.
    #[test]
    fn encode_setquota_limit_exceeding_u32_max_returns_error() {
        let mut buf = BytesMut::new();
        let cmd = Command::SetQuota {
            root: String::new(),
            resources: vec![("STORAGE".into(), u64::from(u32::MAX) + 1)],
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "SETQUOTA with limit > u32::MAX must fail (RFC 2087 Section 4.1)"
        );
    }

    /// SETMETADATA with empty entries must return an error (RFC 5464 Section 5).
    ///
    /// RFC 5464 Section 5 ABNF: `entry-values = "(" entry *(SP entry) ")"` — at
    /// least one entry is REQUIRED. An empty list produces the invalid `SETMETADATA "INBOX" ()\r\n`.
    #[test]
    fn encode_setmetadata_empty_entries_returns_error() {
        let mut buf = BytesMut::new();
        let cmd = Command::SetMetadata {
            mailbox: "INBOX".into(),
            entries: vec![],
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "SETMETADATA with empty entries must fail (RFC 5464 Section 5)"
        );
    }

    /// GETMETADATA with empty entries must return an error (RFC 5464 Section 4.2).
    ///
    /// RFC 5464 Section 4.2 ABNF: `entries = entry / "(" entry *(SP entry) ")"` — at
    /// least one entry is REQUIRED. An empty list produces the invalid `GETMETADATA "INBOX" ()\r\n`.
    #[test]
    fn encode_getmetadata_empty_entries_returns_error() {
        let mut buf = BytesMut::new();
        let cmd = Command::GetMetadata {
            mailbox: "INBOX".into(),
            entries: vec![],
            max_size: None,
            depth: None,
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "GETMETADATA with empty entries must fail (RFC 5464 Section 4.2)"
        );
    }

    /// GETMETADATA with invalid DEPTH must return an error (RFC 5464 Section 4.2.2).
    ///
    /// RFC 5464 Section 4.2.2: `scope-opt = "DEPTH" SP ("0" / "1" / "infinity")`
    /// Only "0", "1", and "infinity" are valid depth values.
    #[test]
    fn encode_getmetadata_invalid_depth_returns_error() {
        let mut buf = BytesMut::new();
        let cmd = Command::GetMetadata {
            mailbox: "INBOX".into(),
            entries: vec!["/private/comment".into()],
            max_size: None,
            depth: Some("2".into()),
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "GETMETADATA with invalid DEPTH \"2\" must fail (RFC 5464 Section 4.2.2)"
        );
    }

    /// GETMETADATA with valid DEPTH values should succeed.
    #[test]
    fn encode_getmetadata_valid_depth_values() {
        for depth in &["0", "1", "infinity"] {
            let mut buf = BytesMut::new();
            let cmd = Command::GetMetadata {
                mailbox: "INBOX".into(),
                entries: vec!["/private/comment".into()],
                max_size: None,
                depth: Some((*depth).to_string()),
            };
            let result = encode_command(&mut buf, "A001", &cmd);
            assert!(
                result.is_ok(),
                "GETMETADATA with valid DEPTH \"{depth}\" must succeed"
            );
        }
    }

    /// custom flag keywords containing atom-special characters must
    /// be rejected by the encoder (RFC 3501 Section 9: flag-keyword = atom).
    #[test]
    fn regression_custom_flag_with_spaces_rejected() {
        let mut buf = BytesMut::new();
        let cmd = Command::Store {
            sequence_set: "1".into(),
            operation: crate::types::StoreOperation::Add,
            flags: vec![crate::types::Flag::Custom("has space".into())],
            unchanged_since: None,
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "custom flag with space must be rejected (RFC 3501 Section 9: ATOM-CHAR)"
        );
    }

    /// custom flag keywords containing parentheses must be rejected.
    #[test]
    fn regression_custom_flag_with_parens_rejected() {
        let mut buf = BytesMut::new();
        let cmd = Command::Store {
            sequence_set: "1".into(),
            operation: crate::types::StoreOperation::Add,
            flags: vec![crate::types::Flag::Custom("bad(flag".into())],
            unchanged_since: None,
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "custom flag with parenthesis must be rejected (RFC 3501 Section 9: ATOM-CHAR)"
        );
    }

    /// empty custom flag keyword must be rejected.
    #[test]
    fn regression_empty_custom_flag_rejected() {
        let mut buf = BytesMut::new();
        let cmd = Command::Store {
            sequence_set: "1".into(),
            operation: crate::types::StoreOperation::Add,
            flags: vec![crate::types::Flag::Custom(String::new())],
            unchanged_since: None,
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "empty custom flag must be rejected (RFC 3501 Section 9: atom = 1*ATOM-CHAR)"
        );
    }

    /// Valid custom flag keywords must still be accepted.
    #[test]
    fn regression_valid_custom_flags_accepted() {
        let mut buf = BytesMut::new();
        let cmd = Command::Store {
            sequence_set: "1".into(),
            operation: crate::types::StoreOperation::Add,
            flags: vec![
                crate::types::Flag::Custom("$Important".into()),
                crate::types::Flag::Custom("$Junk".into()),
                crate::types::Flag::Custom("NonJunk".into()),
            ],
            unchanged_since: None,
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_ok(),
            "valid custom flags must be accepted; got: {result:?}"
        );
    }

    /// GETMETADATA with MAXSIZE option must place the option AFTER
    /// the mailbox, matching RFC 5464 Section 4.2.1 examples.
    ///
    /// The ABNF in RFC 5464 Section 5 places options before the mailbox, but
    /// every example in Sections 4.2.1 and 4.2.2 (and all real-world servers)
    /// place options between the mailbox and entries.
    #[test]
    fn regression_getmetadata_options_after_mailbox() {
        // RFC 5464 Section 4.2.1 example:
        //   C: a GETMETADATA "INBOX" (MAXSIZE 1024) (/shared/comment /private/comment)
        let mut buf = BytesMut::new();
        let cmd = Command::GetMetadata {
            mailbox: "INBOX".into(),
            entries: vec!["/shared/comment".into(), "/private/comment".into()],
            max_size: Some(1024),
            depth: None,
        };
        encode_command(&mut buf, "a", &cmd).unwrap();
        assert_eq!(
            std::str::from_utf8(&buf).unwrap(),
            "a GETMETADATA \"INBOX\" (MAXSIZE 1024) (\"/shared/comment\" \"/private/comment\")\r\n",
            "GETMETADATA options must come AFTER the mailbox (RFC 5464 Section 4.2.1 examples)"
        );
    }

    /// GETMETADATA with DEPTH option must place the option AFTER
    /// the mailbox (RFC 5464 Section 4.2.2 examples).
    #[test]
    fn regression_getmetadata_depth_after_mailbox() {
        // RFC 5464 Section 4.2.2 example:
        //   C: a GETMETADATA "INBOX" (DEPTH 1) (/private/filters/values)
        let mut buf = BytesMut::new();
        let cmd = Command::GetMetadata {
            mailbox: "INBOX".into(),
            entries: vec!["/private/filters/values".into()],
            max_size: None,
            depth: Some("1".into()),
        };
        encode_command(&mut buf, "a", &cmd).unwrap();
        assert_eq!(
            std::str::from_utf8(&buf).unwrap(),
            "a GETMETADATA \"INBOX\" (DEPTH 1) \"/private/filters/values\"\r\n",
            "GETMETADATA DEPTH must come AFTER the mailbox (RFC 5464 Section 4.2.2 examples)"
        );
    }

    /// GETMETADATA with both MAXSIZE and DEPTH options
    /// must place them AFTER the mailbox (RFC 5464 Section 4.2).
    #[test]
    fn regression_getmetadata_both_options_after_mailbox() {
        let mut buf = BytesMut::new();
        let cmd = Command::GetMetadata {
            mailbox: "INBOX".into(),
            entries: vec!["/private/comment".into()],
            max_size: Some(2048),
            depth: Some("infinity".into()),
        };
        encode_command(&mut buf, "a", &cmd).unwrap();
        assert_eq!(
            std::str::from_utf8(&buf).unwrap(),
            "a GETMETADATA \"INBOX\" (MAXSIZE 2048 DEPTH infinity) \"/private/comment\"\r\n",
            "GETMETADATA MAXSIZE + DEPTH must come AFTER the mailbox (RFC 5464 Section 4.2)"
        );
    }

    /// ENABLE with empty capabilities must return an error (RFC 5161).
    ///
    /// RFC 5161 ABNF: `"ENABLE" 1*(SP capability)` — at least one capability
    /// is REQUIRED. An empty list produces the invalid `ENABLE\r\n` on the wire.
    #[test]
    fn encode_enable_empty_caps_returns_error() {
        let mut buf = BytesMut::new();
        let cmd = Command::Enable(vec![]);
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "ENABLE with empty capabilities must fail (RFC 5161)"
        );
    }

    /// QRESYNC seq-match-data without known-uids must return Err,
    /// not silently produce malformed output (RFC 7162 Section 3.2.5.2).
    ///
    /// The ABNF nests `[SP seq-match-data]` inside `[SP known-uids]`, meaning
    /// seq-match-data can only appear when known-uids is present. The encoder
    /// must return a proper error rather than relying on `debug_assert`.
    #[test]
    fn regression_qresync_seq_match_without_known_uids_returns_err() {
        let mut buf = BytesMut::new();
        let cmd = Command::Select {
            mailbox: "INBOX".into(),
            condstore: false,
            qresync: Some(QresyncParams {
                uid_validity: 67890,
                mod_seq: 12345,
                known_uids: None,
                seq_match_data: Some(("1:100".into(), "1:100".into())),
            }),
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "seq-match-data without known-uids must return Err (RFC 7162 Section 3.2.5.2)"
        );
    }

    /// `$` must be valid as a component in comma-separated
    /// sequence sets (RFC 5182 Section 5).
    ///
    /// RFC 5182 Section 5 extends the grammar: `sequence-set =/ seq-last-command`
    /// where `seq-last-command = "$"`. Since the original `sequence-set` includes
    /// `*("," sequence-set)` recursion, `$` is valid in comma-separated lists.
    #[test]
    fn regression_validate_sequence_set_dollar_in_comma_list() {
        // RFC 5182 Section 5: $ as component in comma-separated lists
        assert!(
            validate_sequence_set("1:5,$"),
            "\"1:5,$\" must be valid per RFC 5182 Section 5"
        );
        assert!(
            validate_sequence_set("$,1:*"),
            "\"$,1:*\" must be valid per RFC 5182 Section 5"
        );
        assert!(
            validate_sequence_set("42,$"),
            "\"42,$\" must be valid per RFC 5182 Section 5"
        );
        // Bare $ must still work
        assert!(
            validate_sequence_set("$"),
            "bare \"$\" must still be valid per RFC 5182 Section 2"
        );
        // $ cannot be part of a range (it's not a seq-number)
        assert!(
            !validate_sequence_set("$:5"),
            "\"$:5\" must be rejected ($ is not a seq-number, cannot form a range)"
        );
    }

    /// QRESYNC known-uids must reject `*` (RFC 7162 Section 3.2.5.2).
    ///
    /// RFC 7162 Section 3.2.5.2 states that `*` is not allowed in
    /// known-uids, known-sequence-set, and known-uid-set. The encoder
    /// must return an error rather than silently producing invalid output.
    #[test]
    fn regression_qresync_known_uids_rejects_wildcard() {
        let mut buf = BytesMut::new();
        let cmd = Command::Select {
            mailbox: "INBOX".into(),
            condstore: false,
            qresync: Some(QresyncParams {
                uid_validity: 67890,
                mod_seq: 12345,
                known_uids: Some("1:*".into()),
                seq_match_data: None,
            }),
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "known-uids containing '*' must return Err (RFC 7162 Section 3.2.5.2)"
        );
    }

    /// QRESYNC seq-match-data known-sequence-set must reject `*`.
    #[test]
    fn regression_qresync_seq_match_data_rejects_wildcard_in_seq_set() {
        let mut buf = BytesMut::new();
        let cmd = Command::Select {
            mailbox: "INBOX".into(),
            condstore: false,
            qresync: Some(QresyncParams {
                uid_validity: 67890,
                mod_seq: 12345,
                known_uids: Some("1:500".into()),
                seq_match_data: Some(("1:*".into(), "1:100".into())),
            }),
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "known-sequence-set containing '*' must return Err (RFC 7162 Section 3.2.5.2)"
        );
    }

    /// QRESYNC seq-match-data known-uid-set must reject `*`.
    #[test]
    fn regression_qresync_seq_match_data_rejects_wildcard_in_uid_set() {
        let mut buf = BytesMut::new();
        let cmd = Command::Select {
            mailbox: "INBOX".into(),
            condstore: false,
            qresync: Some(QresyncParams {
                uid_validity: 67890,
                mod_seq: 12345,
                known_uids: Some("1:500".into()),
                seq_match_data: Some(("1:100".into(), "1:*".into())),
            }),
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "known-uid-set containing '*' must return Err (RFC 7162 Section 3.2.5.2)"
        );
    }

    /// STORE with all flags filtered must produce `+FLAGS ()\r\n`,
    /// not `+FLAGS\r\n`.
    ///
    /// RFC 3501 Section 9 ABNF:
    /// `store-att-flags = (["+" / "-"] "FLAGS" [".SILENT"]) SP (flag-list / (flag *(SP flag)))`
    /// The SP and flag-list are mandatory; an empty flag-list is `()`.
    #[test]
    fn store_all_flags_filtered_produces_empty_flag_list() {
        let mut buf = BytesMut::new();
        let cmd = Command::Store {
            sequence_set: "1:5".into(),
            operation: crate::types::StoreOperation::Add,
            flags: vec![crate::types::Flag::Recent],
            unchanged_since: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        let output = std::str::from_utf8(&buf).unwrap();
        assert!(
            output.contains("+FLAGS ()"),
            "all-filtered STORE must produce empty flag-list '()' per RFC 3501 Section 9, got: '{output}'"
        );
        assert!(
            output.ends_with("+FLAGS ()\r\n"),
            "must end with valid CRLF after empty flag-list, got: '{output}'"
        );
    }

    // --- Flag validation and filtering tests (STORE / APPEND) ---
    // These lock down the behavior of the shared flag-filter + validate logic
    // in encode_store_flags and encode_multi_append_header before refactoring.

    /// RFC 3501 Section 9: `\*` (Wildcard) is not valid in the `flag`
    /// production used by STORE; it must be silently filtered.
    #[test]
    fn store_filters_wildcard_flag() {
        let mut buf = BytesMut::new();
        let cmd = Command::Store {
            sequence_set: "1".into(),
            operation: crate::types::StoreOperation::Add,
            flags: vec![
                crate::types::Flag::Seen,
                crate::types::Flag::Wildcard,
                crate::types::Flag::Flagged,
            ],
            unchanged_since: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 STORE 1 +FLAGS (\\Seen \\Flagged)\r\n",
            "Wildcard must be filtered from STORE flags"
        );
    }

    /// RFC 3501 Section 9: `\Recent` is not valid in the `flag` production
    /// used by STORE; it must be silently filtered.
    #[test]
    fn store_filters_recent_flag() {
        let mut buf = BytesMut::new();
        let cmd = Command::Store {
            sequence_set: "2".into(),
            operation: crate::types::StoreOperation::Add,
            flags: vec![
                crate::types::Flag::Seen,
                crate::types::Flag::Recent,
                crate::types::Flag::Flagged,
            ],
            unchanged_since: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 STORE 2 +FLAGS (\\Seen \\Flagged)\r\n",
            "Recent must be filtered from STORE flags"
        );
    }

    /// STORE accepts valid custom flag keywords (RFC 3501 Section 9: `flag-keyword`).
    #[test]
    fn store_accepts_valid_custom_flag() {
        let mut buf = BytesMut::new();
        let cmd = Command::Store {
            sequence_set: "1".into(),
            operation: crate::types::StoreOperation::Add,
            flags: vec![
                crate::types::Flag::Seen,
                crate::types::Flag::Custom("$Important".into()),
            ],
            unchanged_since: None,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 STORE 1 +FLAGS (\\Seen $Important)\r\n");
    }

    /// STORE rejects custom flags containing characters outside ATOM-CHAR
    /// (RFC 3501 Section 9).
    #[test]
    fn store_rejects_invalid_custom_flag() {
        let mut buf = BytesMut::new();
        let cmd = Command::Store {
            sequence_set: "1".into(),
            operation: crate::types::StoreOperation::Add,
            flags: vec![crate::types::Flag::Custom("bad flag".into())],
            unchanged_since: None,
        };
        assert!(
            encode_command(&mut buf, "A001", &cmd).is_err(),
            "custom flag with space must be rejected"
        );
    }

    /// RFC 3501 Section 9: APPEND must filter `\Recent` and `\*` from flags.
    #[test]
    fn append_filters_recent_and_wildcard_flags() {
        let mut buf = BytesMut::new();
        encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[
                crate::types::Flag::Seen,
                crate::types::Flag::Recent,
                crate::types::Flag::Wildcard,
                crate::types::Flag::Flagged,
            ],
            None,
            42,
            true,
            false,
            false,
        )
        .unwrap();
        assert_eq!(
            &buf[..],
            b"A001 APPEND \"INBOX\" (\\Seen \\Flagged) {42}\r\n",
            "Recent and Wildcard must be filtered from APPEND flags"
        );
    }

    /// APPEND accepts valid custom flag keywords (RFC 3501 Section 9).
    #[test]
    fn append_accepts_valid_custom_flag() {
        let mut buf = BytesMut::new();
        encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[crate::types::Flag::Custom("$MailFlagBit0".into())],
            None,
            10,
            true,
            false,
            false,
        )
        .unwrap();
        assert_eq!(&buf[..], b"A001 APPEND \"INBOX\" ($MailFlagBit0) {10}\r\n");
    }

    /// APPEND rejects custom flags containing invalid characters (RFC 3501 Section 9).
    #[test]
    fn append_rejects_invalid_custom_flag() {
        let mut buf = BytesMut::new();
        let result = encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[crate::types::Flag::Custom("bad{flag}".into())],
            None,
            10,
            true,
            false,
            false,
        );
        assert!(result.is_err(), "custom flag with braces must be rejected");
    }

    // --- CHANGEDSINCE modifier boundary tests ---

    /// RFC 7162 Section 7: minimum valid mod-sequence-value is 1.
    #[test]
    fn encode_fetch_changedsince_minimum_valid() {
        let mut buf = BytesMut::new();
        let cmd = Command::Fetch {
            sequence_set: "1:*".into(),
            items: "(FLAGS)".into(),
            changed_since: Some(1),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 FETCH 1:* (FLAGS) (CHANGEDSINCE 1)\r\n");
    }

    /// RFC 7162 Section 7: minimum valid mod-sequence-value is 1 (UID FETCH variant).
    #[test]
    fn encode_uid_fetch_changedsince_minimum_valid() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidFetch {
            sequence_set: "1:*".into(),
            items: "(FLAGS)".into(),
            changed_since: Some(1),
            vanished: false,
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 UID FETCH 1:* (FLAGS) (CHANGEDSINCE 1)\r\n");
    }

    // --- RFC 6855 UTF8=ACCEPT quoted string encoding tests ---

    /// RFC 6855 Section 3: ASCII-only input should produce quoted form regardless of `utf8_mode`.
    #[test]
    fn spec_audit_utf8_mode_ascii_produces_quoted() {
        let mut buf = BytesMut::new();
        encode_quoted_or_literal_utf8(&mut buf, b"Brouillons", true);
        assert_eq!(
            &buf[..],
            b"\"Brouillons\"",
            "ASCII mailbox must be quoted in UTF-8 mode per RFC 6855 Section 3"
        );
    }

    /// RFC 6855 Section 3 / RFC 9051 Section 9: when UTF8=ACCEPT is active,
    /// valid UTF-8 non-ASCII data must use quoted form, not literal.
    #[test]
    fn spec_audit_utf8_mode_non_ascii_produces_quoted() {
        let mut buf = BytesMut::new();
        // "日本語" = 9 bytes in UTF-8: e6 97 a5 e6 9c ac e8 aa 9e
        encode_quoted_or_literal_utf8(&mut buf, "日本語".as_bytes(), true);
        assert!(
            buf.starts_with(b"\""),
            "UTF-8 mailbox name must be quoted when UTF8=ACCEPT is active \
             per RFC 6855 Section 3, got literal form instead"
        );
        // Verify the full output: quoted "日本語"
        let expected_bytes = b"\"\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e\"";
        assert_eq!(
            &buf[..],
            &expected_bytes[..],
            "UTF-8 mailbox name must be quoted per RFC 6855 Section 3"
        );
    }

    /// RFC 3501 Section 9: without UTF8=ACCEPT, non-ASCII bytes must use literal form.
    #[test]
    fn spec_audit_no_utf8_mode_non_ascii_produces_literal() {
        let mut buf = BytesMut::new();
        // "日本語" = 9 bytes in UTF-8
        encode_quoted_or_literal_utf8(&mut buf, "日本語".as_bytes(), false);
        assert!(
            buf.starts_with(b"{"),
            "Non-ASCII mailbox name must use literal form when UTF8=ACCEPT is not active \
             per RFC 3501 Section 9, got quoted form instead"
        );
        assert_eq!(
            &buf[..],
            b"{9}\r\n\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e",
            "Non-ASCII mailbox name must use literal form per RFC 3501 Section 9"
        );
    }

    /// RFC 9051 Section 9: CR and LF are never quotable, even in UTF-8 mode.
    /// TEXT-CHAR excludes CR (%x0D) and LF (%x0A).
    #[test]
    fn spec_audit_utf8_mode_crlf_produces_literal() {
        let mut buf = BytesMut::new();
        encode_quoted_or_literal_utf8(&mut buf, b"line1\r\nline2", true);
        assert!(
            buf.starts_with(b"{"),
            "Data with CR/LF must use literal form even when UTF8=ACCEPT is active \
             per RFC 9051 Section 9 TEXT-CHAR definition"
        );
        assert_eq!(
            &buf[..],
            b"{12}\r\nline1\r\nline2",
            "CR/LF data must produce literal form per RFC 9051 Section 9"
        );
    }

    /// RFC 6855 Section 3: invalid UTF-8 sequences must fall back to literal even
    /// when `utf8_mode` is true, since they cannot be represented in quoted strings.
    #[test]
    fn spec_audit_utf8_mode_invalid_utf8_produces_literal() {
        let mut buf = BytesMut::new();
        // Invalid UTF-8: lone continuation byte
        let invalid = &[0x80, 0x81, 0x82];
        encode_quoted_or_literal_utf8(&mut buf, invalid, true);
        assert!(
            buf.starts_with(b"{"),
            "Invalid UTF-8 must use literal form even when UTF8=ACCEPT is active \
             per RFC 6855 Section 3 (only valid UTF-8 is allowed in quoted strings)"
        );
    }

    // --- encode_quoted_or_literal: backslash and double-quote escaping ---

    /// RFC 3501 Section 9: quoted-specials = DQUOTE / "\"
    /// Both backslash and double-quote must be escaped in quoted strings.
    #[test]
    fn encode_quoted_escapes_backslash_and_dquote() {
        let mut buf = BytesMut::new();
        encode_quoted_or_literal(&mut buf, b"a\\b\"c");
        // Expected: "a\\b\"c"
        assert_eq!(&buf[..], b"\"a\\\\b\\\"c\"");
    }

    // --- encode_quoted_or_literal_utf8: NUL stripping in UTF-8 mode ---

    /// RFC 3501 Section 9: NUL (%x00) is forbidden and must be stripped
    /// even when UTF8=ACCEPT is active (RFC 6855 Section 3).
    #[test]
    fn encode_utf8_mode_strips_nul_bytes() {
        let mut buf = BytesMut::new();
        encode_quoted_or_literal_utf8(&mut buf, b"hello\x00world", true);
        assert_eq!(
            &buf[..],
            b"\"helloworld\"",
            "NUL bytes must be stripped in UTF-8 mode per RFC 3501 Section 9"
        );
        assert!(!buf.contains(&0x00), "output must not contain NUL bytes");
    }

    /// RFC 3501 Section 9 / RFC 6855 Section 3: backslash and double-quote
    /// must be escaped in quoted strings even in UTF-8 mode.
    #[test]
    fn encode_utf8_mode_escapes_backslash_and_dquote() {
        let mut buf = BytesMut::new();
        encode_quoted_or_literal_utf8(&mut buf, b"a\\b\"c", true);
        assert_eq!(
            &buf[..],
            b"\"a\\\\b\\\"c\"",
            "backslash and double-quote must be escaped in UTF-8 mode"
        );
    }

    // --- APPEND date-time validation (RFC 3501 Section 9) ---

    /// RFC 3501 Section 9: `date-day-fixed = (SP DIGIT) / 2DIGIT`.
    /// The `2DIGIT` alternative matches any two ASCII digits, so zero-padded
    /// single-digit days like `07` are syntactically valid and semantically
    /// correct (day 7 of the month). The validator must accept them.
    #[test]
    fn test_append_accepts_zero_padded_day() {
        let mut buf = BytesMut::new();
        let result = encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[],
            Some("07-Jul-1996 02:44:25 -0700"),
            100,
            true,
            false,
            false,
        );
        assert!(
            result.is_ok(),
            "zero-padded day '07' is valid per RFC 3501 Section 9 \
             (date-day-fixed = (SP DIGIT) / 2DIGIT): {result:?}"
        );
    }

    /// Zero-padded days 01 through 09 must all be accepted per RFC 3501 Section 9.
    #[test]
    fn test_append_accepts_all_zero_padded_days() {
        for day in 1..=9u8 {
            let date = format!("0{day}-Jan-2024 12:00:00 +0000");
            let result = validate_append_datetime(&date);
            assert!(
                result.is_ok(),
                "zero-padded day '0{day}' must be accepted per RFC 3501 Section 9 \
                 date-day-fixed 2DIGIT: {result:?}"
            );
        }
    }

    /// Day `00` must be rejected — it matches `2DIGIT` syntactically but is
    /// not a valid calendar day.
    #[test]
    fn test_append_rejects_day_zero() {
        let result = validate_append_datetime("00-Jan-2024 12:00:00 +0000");
        assert!(
            result.is_err(),
            "day '00' is not a valid calendar day and must be rejected"
        );
    }

    /// invalid month name must be rejected (RFC 3501 Section 9).
    #[test]
    fn test_append_rejects_invalid_month() {
        let mut buf = BytesMut::new();
        let result = encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[],
            Some("31-Foo-2024 12:00:00 +0000"),
            100,
            true,
            false,
            false,
        );
        assert!(
            result.is_err(),
            "invalid month name should be rejected per RFC 3501 Section 9 date-month"
        );
    }

    /// completely malformed date string must be rejected.
    #[test]
    fn test_append_rejects_garbage_date() {
        let mut buf = BytesMut::new();
        let result = encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[],
            Some("not-a-date"),
            100,
            true,
            false,
            false,
        );
        assert!(
            result.is_err(),
            "garbage date string should be rejected per RFC 3501 Section 9"
        );
    }

    /// RFC 3501 Section 9 paragraph (1): "all alphabetic characters are
    /// case-insensitive … Implementations MUST accept these strings in a
    /// case-insensitive fashion." Month names like "JAN", "jan", "jAn" are
    /// valid per RFC 5234 Section 2.3 (ABNF strings are case-insensitive).
    #[test]
    fn test_append_accepts_case_insensitive_month() {
        // Uppercase month
        let mut buf = BytesMut::new();
        let result = encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[],
            Some(" 7-JAN-2024 12:00:00 +0000"),
            100,
            true,
            false,
            false,
        );
        assert!(
            result.is_ok(),
            "uppercase month must be accepted per RFC 3501 Section 9 paragraph (1): {result:?}"
        );

        // Lowercase month
        let mut buf2 = BytesMut::new();
        let result2 = encode_multi_append_header(
            &mut buf2,
            "A001",
            "INBOX",
            &[],
            Some("15-jul-2024 12:00:00 +0000"),
            100,
            true,
            false,
            false,
        );
        assert!(
            result2.is_ok(),
            "lowercase month must be accepted per RFC 3501 Section 9 paragraph (1): {result2:?}"
        );

        // Mixed case month
        let mut buf3 = BytesMut::new();
        let result3 = encode_multi_append_header(
            &mut buf3,
            "A001",
            "INBOX",
            &[],
            Some("20-sEp-2024 12:00:00 +0000"),
            100,
            true,
            false,
            false,
        );
        assert!(
            result3.is_ok(),
            "mixed-case month must be accepted per RFC 3501 Section 9 paragraph (1): {result3:?}"
        );
    }

    /// Valid date-time strings per RFC 3501 Section 9 must be accepted.
    #[test]
    fn test_append_accepts_valid_datetime() {
        // Space-padded single-digit day.
        let mut buf = BytesMut::new();
        let result = encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[],
            Some(" 7-Jul-1996 02:44:25 -0700"),
            100,
            true,
            false,
            false,
        );
        assert!(
            result.is_ok(),
            "valid space-padded day should be accepted: {result:?}"
        );

        // Two-digit day.
        let mut buf2 = BytesMut::new();
        let result2 = encode_multi_append_header(
            &mut buf2,
            "A001",
            "INBOX",
            &[],
            Some("17-Jul-1996 02:44:25 -0700"),
            100,
            true,
            false,
            false,
        );
        assert!(
            result2.is_ok(),
            "valid two-digit day should be accepted: {result2:?}"
        );
    }

    /// RFC 3501 Section 9: the validator must reject semantically invalid time
    /// components (hours > 23, minutes > 59, seconds > 60) and accept valid
    /// boundary values including leap seconds (60) per RFC 5322 Section 3.3.
    #[test]
    fn spec_audit_time_range_validation() {
        // Invalid hour: 25 exceeds 00-23 range.
        assert!(
            validate_append_datetime("01-Jan-2024 25:00:00 +0000").is_err(),
            "hour 25 must be rejected — valid range is 00-23 (RFC 3501 Section 9)"
        );

        // Invalid minute: 61 exceeds 00-59 range.
        assert!(
            validate_append_datetime("01-Jan-2024 12:61:00 +0000").is_err(),
            "minute 61 must be rejected — valid range is 00-59 (RFC 3501 Section 9)"
        );

        // Invalid second: 61 exceeds 00-60 range.
        assert!(
            validate_append_datetime("01-Jan-2024 12:00:61 +0000").is_err(),
            "second 61 must be rejected — valid range is 00-60 (RFC 3501 Section 9)"
        );

        // Valid leap second: 60 is permitted per RFC 5322 Section 3.3.
        assert!(
            validate_append_datetime("01-Jan-2024 12:00:60 +0000").is_ok(),
            "second 60 (leap second) must be accepted per RFC 5322 Section 3.3"
        );

        // Maximum valid time: 23:59:59.
        assert!(
            validate_append_datetime("01-Jan-2024 23:59:59 +0000").is_ok(),
            "23:59:59 is the maximum valid non-leap-second time"
        );

        // Minimum valid time: 00:00:00.
        assert!(
            validate_append_datetime("01-Jan-2024 00:00:00 +0000").is_ok(),
            "00:00:00 is the minimum valid time"
        );
    }

    /// RFC 3501 Section 9: the validator must reject impossible calendar dates
    /// where the day exceeds the maximum for the given month.  February is
    /// capped at 29 (we accept Feb 29 universally since a full leap-year check
    /// would require parsing the 4-digit year; this is a practical compromise).
    /// 30-day months (Apr, Jun, Sep, Nov) must reject day 31.
    #[test]
    fn spec_audit_day_month_cross_check() {
        // Feb 31 — impossible, must be rejected.
        assert!(
            validate_append_datetime("31-Feb-2024 00:00:00 +0000").is_err(),
            "31-Feb must be rejected — February has at most 29 days (RFC 3501 Section 9)"
        );

        // Feb 30 — impossible, must be rejected.
        assert!(
            validate_append_datetime("30-Feb-2024 00:00:00 +0000").is_err(),
            "30-Feb must be rejected — February has at most 29 days (RFC 3501 Section 9)"
        );

        // Feb 29 — accepted universally (leap-year check omitted).
        assert!(
            validate_append_datetime("29-Feb-2024 00:00:00 +0000").is_ok(),
            "29-Feb must be accepted — we allow Feb 29 for all years (RFC 3501 Section 9)"
        );

        // Apr 31 — impossible, must be rejected (April has 30 days).
        assert!(
            validate_append_datetime("31-Apr-2024 00:00:00 +0000").is_err(),
            "31-Apr must be rejected — April has at most 30 days (RFC 3501 Section 9)"
        );

        // Jun 31 — impossible, must be rejected (June has 30 days).
        assert!(
            validate_append_datetime("31-Jun-2024 00:00:00 +0000").is_err(),
            "31-Jun must be rejected — June has at most 30 days (RFC 3501 Section 9)"
        );

        // Apr 30 — valid, must be accepted.
        assert!(
            validate_append_datetime("30-Apr-2024 00:00:00 +0000").is_ok(),
            "30-Apr must be accepted — April has 30 days (RFC 3501 Section 9)"
        );

        // Jan 31 — valid, must be accepted.
        assert!(
            validate_append_datetime("31-Jan-2024 00:00:00 +0000").is_ok(),
            "31-Jan must be accepted — January has 31 days (RFC 3501 Section 9)"
        );
    }

    /// RFC 6855 Section 3: verify `encode_multi_append_header` uses quoted form
    /// for a UTF-8 mailbox name when `utf8` is true.
    #[test]
    fn spec_audit_multi_append_utf8_mailbox_quoted() {
        let mut buf = BytesMut::new();
        encode_multi_append_header(
            &mut buf,
            "A001",
            "日本語",
            &[],
            None,
            42,
            true,
            false,
            true, // utf8 = true
        )
        .unwrap();
        let output = std::str::from_utf8(&buf[..]).unwrap_or("");
        // The mailbox should be quoted, not a literal.
        assert!(
            output.contains("APPEND \""),
            "UTF-8 mailbox in MULTIAPPEND must be quoted when UTF8=ACCEPT is active \
             per RFC 6855 Section 3, got: '{output}'"
        );
    }

    // -----------------------------------------------------------------------
    // RFC 7162 Section 7: mod-sequence-value / mod-sequence-valzer validation
    // -----------------------------------------------------------------------

    /// RFC 7162 Section 7: CHANGEDSINCE uses mod-sequence-value (>= 1).
    #[test]
    fn encode_fetch_changedsince_rejects_zero() {
        let cmd = Command::Fetch {
            sequence_set: "1:*".into(),
            items: "FLAGS".into(),
            changed_since: Some(0),
        };
        let mut buf = BytesMut::new();
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "CHANGEDSINCE 0 must be rejected per RFC 7162 Section 7"
        );
    }

    /// RFC 7162 Section 7: mod-sequence-value must be <= 2^63-1.
    #[test]
    fn encode_fetch_changedsince_rejects_overflow() {
        let cmd = Command::Fetch {
            sequence_set: "1:*".into(),
            items: "FLAGS".into(),
            changed_since: Some(u64::MAX),
        };
        let mut buf = BytesMut::new();
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "CHANGEDSINCE > i64::MAX must be rejected per RFC 7162 Section 7"
        );
    }

    /// RFC 7162 Section 7: UNCHANGEDSINCE uses mod-sequence-valzer (allows 0).
    #[test]
    fn encode_store_unchangedsince_allows_zero() {
        let cmd = Command::Store {
            sequence_set: "1".into(),
            operation: crate::types::StoreOperation::Add,
            flags: vec![crate::types::Flag::Seen],
            unchanged_since: Some(0),
        };
        let mut buf = BytesMut::new();
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_ok(),
            "UNCHANGEDSINCE 0 must be allowed per RFC 7162 Section 7"
        );
    }

    /// RFC 7162 Section 7: mod-sequence-valzer must be <= 2^63-1.
    #[test]
    fn encode_store_unchangedsince_rejects_overflow() {
        let cmd = Command::Store {
            sequence_set: "1".into(),
            operation: crate::types::StoreOperation::Add,
            flags: vec![crate::types::Flag::Seen],
            unchanged_since: Some(u64::MAX),
        };
        let mut buf = BytesMut::new();
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "UNCHANGEDSINCE > i64::MAX must be rejected per RFC 7162 Section 7"
        );
    }

    /// RFC 7162 Section 7: UID FETCH CHANGEDSINCE also uses mod-sequence-value.
    #[test]
    fn encode_uid_fetch_changedsince_rejects_zero() {
        let cmd = Command::UidFetch {
            sequence_set: "1:*".into(),
            items: "FLAGS".into(),
            changed_since: Some(0),
            vanished: false,
        };
        let mut buf = BytesMut::new();
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "UID FETCH CHANGEDSINCE 0 must be rejected per RFC 7162 Section 7"
        );
    }

    /// RFC 7162 Section 7: UID STORE UNCHANGEDSINCE must reject > `i64::MAX`.
    #[test]
    fn encode_uid_store_unchangedsince_rejects_overflow() {
        let cmd = Command::UidStore {
            sequence_set: "1".into(),
            operation: crate::types::StoreOperation::Add,
            flags: vec![crate::types::Flag::Seen],
            unchanged_since: Some(u64::MAX),
        };
        let mut buf = BytesMut::new();
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "UID STORE UNCHANGEDSINCE > i64::MAX must be rejected per RFC 7162 Section 7"
        );
    }

    /// RFC 7162 Section 7: known-uids / known-sequence-set / known-uid-set
    /// must be syntactically valid `sequence-set` (with `*` and `$` disallowed).
    #[test]
    fn validate_known_sequence_set_accepts_valid() {
        // Simple nz-numbers and ranges
        assert!(validate_known_sequence_set("1").is_ok());
        assert!(validate_known_sequence_set("1:100").is_ok());
        assert!(validate_known_sequence_set("1,2,3").is_ok());
        assert!(validate_known_sequence_set("1:5,10:20").is_ok());
        assert!(validate_known_sequence_set("4294967295").is_ok()); // u32::MAX
    }

    /// RFC 7162 Section 7: known-uids / known-sequence-set / known-uid-set
    /// must reject values that are not syntactically valid `sequence-set`
    /// or that contain `*` or `$`.
    #[test]
    fn validate_known_sequence_set_rejects_invalid() {
        // Empty string — not a valid sequence-set
        assert!(validate_known_sequence_set("").is_err());
        // Non-numeric content — not valid nz-number
        assert!(validate_known_sequence_set("abc").is_err());
        // Contains spaces — not valid sequence-set syntax
        assert!(validate_known_sequence_set("1 2").is_err());
        // Contains wildcard — disallowed per RFC 7162 Section 3.2.5.2
        assert!(validate_known_sequence_set("1:*").is_err());
        assert!(validate_known_sequence_set("*").is_err());
        // Contains $ (RFC 5182 search result reference) — not meaningful in QRESYNC
        assert!(validate_known_sequence_set("$").is_err());
        assert!(validate_known_sequence_set("1,$").is_err());
        // Standalone zero — not a valid nz-number
        assert!(validate_known_sequence_set("0").is_err());
        // Leading zeros — not a valid nz-number (digit-nz *DIGIT)
        assert!(validate_known_sequence_set("01").is_err());
        // Overflow — exceeds u32::MAX
        assert!(validate_known_sequence_set("4294967296").is_err());
        // Trailing comma — produces empty part
        assert!(validate_known_sequence_set("1,").is_err());
        // Double colon — produces empty range element
        assert!(validate_known_sequence_set("1::2").is_err());
    }

    /// RFC 5464 Section 5 / RFC 3501 Section 9: MAXSIZE must fit in `number` (u32).
    /// A `max_size` of 0 is valid (edge case but syntactically legal).
    #[test]
    fn getmetadata_maxsize_zero_accepted() {
        let mut buf = BytesMut::new();
        let result = encode_getmetadata(
            &mut buf,
            "A001",
            "INBOX",
            &["/private/comment".to_owned()],
            Some(0),
            None,
        );
        assert!(result.is_ok(), "max_size 0 should be accepted");
    }

    /// RFC 5464 Section 5 / RFC 3501 Section 9: `u32::MAX` is the largest valid `number`.
    #[test]
    fn getmetadata_maxsize_u32_max_accepted() {
        let mut buf = BytesMut::new();
        let result = encode_getmetadata(
            &mut buf,
            "A001",
            "INBOX",
            &["/private/comment".to_owned()],
            Some(u64::from(u32::MAX)),
            None,
        );
        assert!(result.is_ok(), "max_size u32::MAX should be accepted");
        let output = std::str::from_utf8(&buf).unwrap();
        assert!(
            output.contains("MAXSIZE 4294967295"),
            "should contain u32::MAX value, got: {output}"
        );
    }

    /// RFC 5464 Section 5 / RFC 3501 Section 9: `u32::MAX` + 1 exceeds `number` range.
    #[test]
    fn getmetadata_maxsize_u32_max_plus_one_rejected() {
        let mut buf = BytesMut::new();
        let result = encode_getmetadata(
            &mut buf,
            "A001",
            "INBOX",
            &["/private/comment".to_owned()],
            Some(u64::from(u32::MAX) + 1),
            None,
        );
        assert!(
            result.is_err(),
            "max_size u32::MAX + 1 must be rejected per RFC 5464 Section 5 / RFC 3501 Section 9"
        );
    }

    /// RFC 5464 Section 5 / RFC 3501 Section 9: `u64::MAX` far exceeds `number` range.
    #[test]
    fn getmetadata_maxsize_u64_max_rejected() {
        let mut buf = BytesMut::new();
        let result = encode_getmetadata(
            &mut buf,
            "A001",
            "INBOX",
            &["/private/comment".to_owned()],
            Some(u64::MAX),
            None,
        );
        assert!(
            result.is_err(),
            "max_size u64::MAX must be rejected per RFC 5464 Section 5 / RFC 3501 Section 9"
        );
    }

    /// RFC 7162 Section 3.2.5.2: QRESYNC `mod_seq` is mod-sequence-value (>= 1).
    #[test]
    fn encode_select_qresync_rejects_zero_modseq() {
        let cmd = Command::Select {
            mailbox: "INBOX".into(),
            condstore: false,
            qresync: Some(crate::types::QresyncParams {
                uid_validity: 1,
                mod_seq: 0,
                known_uids: None,
                seq_match_data: None,
            }),
        };
        let mut buf = BytesMut::new();
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "QRESYNC mod_seq 0 must be rejected per RFC 7162 Section 7"
        );
    }

    /// SETQUOTA resource name containing a space must be rejected.
    ///
    /// RFC 2087 Section 4.1: `setquota_resource = atom SP number`.
    /// RFC 3501 Section 9: `atom = 1*ATOM-CHAR`, and SP is an atom-special.
    /// A resource name with a space would produce malformed wire format.
    #[test]
    fn encode_setquota_rejects_resource_name_with_space() {
        let mut buf = BytesMut::new();
        let cmd = Command::SetQuota {
            root: String::new(),
            resources: vec![("BAD RESOURCE".into(), 1024)],
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "SETQUOTA resource name with space must be rejected \
             (RFC 2087 Section 4.1: resource is atom; RFC 3501 Section 9: SP is atom-special)"
        );
    }

    /// ENABLE with capability containing spaces must be rejected.
    ///
    /// RFC 5161 Section 4: `capability = ("AUTH=" auth-type) / atom`.
    /// RFC 3501 Section 9: `atom = 1*ATOM-CHAR` — no spaces, CTLs, or atom-specials.
    #[test]
    fn encode_enable_rejects_invalid_capability_name() {
        let mut buf = BytesMut::new();
        let cmd = Command::Enable(vec!["BAD NAME".into()]);
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "ENABLE with space in capability name must be rejected \
             (RFC 5161 Section 4: capability = atom)"
        );
    }

    /// ENABLE with valid capability names (including `=`) must succeed.
    #[test]
    fn encode_enable_accepts_valid_capabilities() {
        let mut buf = BytesMut::new();
        let cmd = Command::Enable(vec!["UTF8=ACCEPT".into(), "CONDSTORE".into()]);
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_ok(),
            "ENABLE with valid atom capabilities must succeed, got: {result:?}"
        );
        let s = String::from_utf8_lossy(&buf);
        assert!(s.contains("ENABLE UTF8=ACCEPT CONDSTORE"));
    }

    /// SETQUOTA with an empty resource name must be rejected.
    ///
    /// RFC 2087 Section 4.1: `setquota_resource = atom SP number`.
    /// RFC 3501 Section 9: `atom = 1*ATOM-CHAR` — at least one character is required.
    #[test]
    fn encode_setquota_rejects_empty_resource_name() {
        let mut buf = BytesMut::new();
        let cmd = Command::SetQuota {
            root: String::new(),
            resources: vec![(String::new(), 1024)],
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "SETQUOTA with empty resource name must be rejected \
             (RFC 2087 Section 4.1: resource is atom; RFC 3501 Section 9: atom = 1*ATOM-CHAR)"
        );
    }

    // ── Pre-refactor lock-down: LIST/LSUB/RENAME with non-ASCII names ──

    #[test]
    fn encode_list_non_ascii_reference() {
        // RFC 6855 Section 3: UTF8=ACCEPT permits UTF-8 in mailbox names.
        // Literal encoding is required for non-ASCII bytes.
        let mut buf = BytesMut::new();
        let cmd = Command::List {
            reference: "café".into(),
            pattern: "*".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        // "café" is 5 bytes in UTF-8 → must use literal {5}
        assert_eq!(&buf[..], b"A001 LIST {5}\r\ncaf\xc3\xa9 \"*\"\r\n");
    }

    #[test]
    fn encode_lsub_non_ascii_pattern() {
        // RFC 3501 Section 6.3.9 / RFC 6855: non-ASCII in pattern.
        let mut buf = BytesMut::new();
        let cmd = Command::Lsub {
            reference: String::new(),
            pattern: "日本語".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        // "日本語" is 9 bytes in UTF-8 → literal {9}
        assert_eq!(
            &buf[..],
            b"A001 LSUB \"\" {9}\r\n\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e\r\n"
        );
    }

    #[test]
    fn encode_rename_non_ascii_both_args() {
        // RFC 3501 Section 6.3.5 / RFC 6855: both old and new names non-ASCII.
        let mut buf = BytesMut::new();
        let cmd = Command::Rename {
            mailbox: "Ünread".into(),
            new_name: "Gelöscht".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        let expected_old = "Ünread".as_bytes(); // 7 bytes
        let expected_new = "Gelöscht".as_bytes(); // 9 bytes
        let expected = format!(
            "A001 RENAME {{{}}}\r\n{} {{{}}}\r\n{}\r\n",
            expected_old.len(),
            "Ünread",
            expected_new.len(),
            "Gelöscht",
        );
        assert_eq!(&buf[..], expected.as_bytes());
    }

    #[test]
    fn encode_list_empty_reference_percent_pattern() {
        // RFC 3501 Section 6.3.8: % matches one level of hierarchy.
        let mut buf = BytesMut::new();
        let cmd = Command::List {
            reference: String::new(),
            pattern: "%".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 LIST \"\" \"%\"\r\n");
    }

    #[test]
    fn encode_lsub_with_reference_and_pattern() {
        // RFC 3501 Section 6.3.9: LSUB with non-empty reference.
        let mut buf = BytesMut::new();
        let cmd = Command::Lsub {
            reference: "INBOX.".into(),
            pattern: "*".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 LSUB \"INBOX.\" \"*\"\r\n");
    }

    // ---------------------------------------------------------------
    // Pre-refactor coverage: sequence-set validation gaps
    // RFC 3501 Section 9: sequence-set = (seq-number / seq-range) *("," …)
    // where seq-number = nz-number / "*", nz-number = digit-nz *DIGIT.
    // "0", "abc", and "" are all invalid per the ABNF.
    // ---------------------------------------------------------------

    /// RFC 3501 Section 6.4.6 / Section 9: STORE must reject invalid
    /// sequence-set "0" (nz-number does not allow zero).
    #[test]
    fn encode_store_rejects_invalid_sequence_set() {
        let mut buf = BytesMut::new();
        let cmd = Command::Store {
            sequence_set: "0".into(),
            operation: crate::types::StoreOperation::Add,
            flags: vec![crate::types::Flag::Seen],
            unchanged_since: None,
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "expected error for invalid sequence set '0' in STORE"
        );
    }

    /// RFC 6851 / RFC 3501 Section 9: MOVE must reject invalid
    /// sequence-set "abc" (not a valid nz-number or seq-range).
    #[test]
    fn encode_move_rejects_invalid_sequence_set() {
        let mut buf = BytesMut::new();
        let cmd = Command::Move {
            sequence_set: "abc".into(),
            mailbox: "Trash".into(),
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "expected error for invalid sequence set 'abc' in MOVE"
        );
    }

    /// RFC 6851 / RFC 3501 Section 9: UID MOVE must reject an empty
    /// sequence-set (empty string is not a valid sequence-set).
    #[test]
    fn encode_uid_move_rejects_invalid_sequence_set() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidMove {
            sequence_set: String::new(),
            mailbox: "Archive".into(),
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "expected error for empty sequence set in UID MOVE"
        );
    }

    /// RFC 3501 Section 6.4.7 / Section 9: UID COPY must reject invalid
    /// sequence-set "0" (nz-number does not allow zero).
    #[test]
    fn encode_uid_copy_rejects_invalid_sequence_set() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidCopy {
            sequence_set: "0".into(),
            mailbox: "INBOX".into(),
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "expected error for invalid sequence set '0' in UID COPY"
        );
    }

    /// RFC 4315 Section 2.1 / RFC 3501 Section 9: UID EXPUNGE must reject
    /// invalid sequence-set "abc" (not a valid uid-set).
    #[test]
    fn encode_uid_expunge_rejects_invalid_sequence_set() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidExpunge {
            sequence_set: "abc".into(),
        };
        let result = encode_command(&mut buf, "A001", &cmd);
        assert!(
            result.is_err(),
            "expected error for invalid sequence set 'abc' in UID EXPUNGE"
        );
    }

    // ---------------------------------------------------------------
    // Pre-refactor coverage: STORE with CONDSTORE (typical value)
    // RFC 7162 Section 3.1.3: UNCHANGEDSINCE mod-sequence-valzer
    // Existing tests cover edge cases (0, u64::MAX); this covers a
    // representative mid-range value.
    // ---------------------------------------------------------------

    /// RFC 7162 Section 3.1.3: non-UID STORE with CONDSTORE modifier at a
    /// typical mod-sequence-valzer value (12345). The existing test covers
    /// UID STORE; this covers the non-UID variant.
    #[test]
    fn encode_non_uid_store_with_condstore_typical_value() {
        let mut buf = BytesMut::new();
        let cmd = Command::Store {
            sequence_set: "1:3".into(),
            operation: crate::types::StoreOperation::Remove,
            flags: vec![crate::types::Flag::Seen],
            unchanged_since: Some(12345),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 STORE 1:3 (UNCHANGEDSINCE 12345) -FLAGS (\\Seen)\r\n"
        );
    }

    // ---------------------------------------------------------------
    // Pre-refactor coverage: COPY/MOVE with special mailbox names
    // RFC 3501 Section 9: quoted strings that contain characters
    // requiring escaping, or non-ASCII bytes that force literal form.
    // ---------------------------------------------------------------

    /// RFC 3501 Section 6.4.7 / Section 9: COPY with a mailbox name
    /// containing a double-quote, which must be escaped in the quoted
    /// string form (backslash-quote per quoted-specials).
    #[test]
    fn encode_copy_with_special_char_mailbox() {
        let mut buf = BytesMut::new();
        let cmd = Command::Copy {
            sequence_set: "1:5".into(),
            mailbox: "folder\"name".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        // Double-quote is ASCII and quotable, so it gets backslash-escaped
        // in quoted form per RFC 3501 Section 9 (quoted-specials).
        assert_eq!(
            &buf[..],
            b"A001 COPY 1:5 \"folder\\\"name\"\r\n",
            "mailbox with double-quote should use quoted form with escaping"
        );
    }

    /// RFC 6851 / RFC 3501 Section 9: UID MOVE with a non-ASCII mailbox
    /// name forces literal encoding (bytes > 0x7F are not TEXT-CHAR per
    /// RFC 3501 Section 9, so they cannot appear in a quoted string).
    #[test]
    fn encode_uid_move_with_non_ascii_mailbox() {
        let mut buf = BytesMut::new();
        let cmd = Command::UidMove {
            sequence_set: "1:5".into(),
            mailbox: "caf\u{00E9}".into(), // "café" — 5 bytes in UTF-8
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        // Non-ASCII forces literal encoding: {5}\r\ncafé
        assert!(
            buf.starts_with(b"A001 UID MOVE 1:5 "),
            "command prefix mismatch"
        );
        let s = String::from_utf8_lossy(&buf);
        assert!(
            s.contains("{5}\r\n"),
            "should use literal for non-ASCII mailbox, got: {s}"
        );
    }

    // ── Pre-refactor lock-down: DELETEACL / LISTRIGHTS edge cases ──

    /// RFC 4314 Section 3.2: DELETEACL with a mailbox containing spaces.
    #[test]
    fn encode_deleteacl_mailbox_with_spaces() {
        let mut buf = BytesMut::new();
        let cmd = Command::DeleteAcl {
            mailbox: "Shared Folders".into(),
            identifier: "user@example.com".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 DELETEACL \"Shared Folders\" \"user@example.com\"\r\n"
        );
    }

    /// RFC 4314 Section 3.2: DELETEACL with non-ASCII mailbox
    /// forces literal encoding.
    #[test]
    fn encode_deleteacl_non_ascii_mailbox() {
        let mut buf = BytesMut::new();
        let cmd = Command::DeleteAcl {
            mailbox: "café".into(),
            identifier: "fred".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        // "café" is 5 bytes → literal {5}
        assert_eq!(&buf[..], b"A001 DELETEACL {5}\r\ncaf\xc3\xa9 \"fred\"\r\n");
    }

    /// RFC 4314 Section 3.4: LISTRIGHTS with a mailbox containing spaces.
    #[test]
    fn encode_listrights_mailbox_with_spaces() {
        let mut buf = BytesMut::new();
        let cmd = Command::ListRights {
            mailbox: "Shared Folders".into(),
            identifier: "user@example.com".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 LISTRIGHTS \"Shared Folders\" \"user@example.com\"\r\n"
        );
    }

    /// RFC 4314 Section 3.4: LISTRIGHTS with non-ASCII mailbox.
    #[test]
    fn encode_listrights_non_ascii_mailbox() {
        let mut buf = BytesMut::new();
        let cmd = Command::ListRights {
            mailbox: "café".into(),
            identifier: "fred".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 LISTRIGHTS {5}\r\ncaf\xc3\xa9 \"fred\"\r\n");
    }

    // ── Pre-refactor lock-down: GETQUOTA / GETQUOTAROOT non-ASCII ──

    /// RFC 2087 Section 4.2: GETQUOTA with non-ASCII root.
    #[test]
    fn encode_get_quota_non_ascii_root() {
        let mut buf = BytesMut::new();
        let cmd = Command::GetQuota {
            root: "café".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 GETQUOTA {5}\r\ncaf\xc3\xa9\r\n");
    }

    /// RFC 2087 Section 4.3: GETQUOTAROOT with non-ASCII mailbox.
    #[test]
    fn encode_get_quota_root_non_ascii() {
        let mut buf = BytesMut::new();
        let cmd = Command::GetQuotaRoot {
            mailbox: "café".into(),
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(&buf[..], b"A001 GETQUOTAROOT {5}\r\ncaf\xc3\xa9\r\n");
    }

    // ── RFC 9051 Section 9: literal8 must not use non-synchronizing `+` suffix ──

    /// RFC 9051 Section 9: `literal8 = "~{" number64 "}" CRLF *OCTET` — no `["+"]`.
    /// When UTF8=ACCEPT is active, the encoder must produce `~{N}\r\n`,
    /// never `~{N+}\r\n`. The decoder at decode.rs:377-383 already rejects
    /// `~{N+}` — the encoder must match.
    #[test]
    fn literal8_must_not_use_non_sync_plus() {
        let mut buf = BytesMut::new();
        encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[],  // no flags
            None, // no date
            100,  // message length
            true, // first_message
            true, // literal_plus = true (LITERAL+ is negotiated)
            true, // utf8 = true (UTF8=ACCEPT is active)
        )
        .unwrap();
        let output = std::str::from_utf8(&buf).unwrap();
        // Must NOT contain `+}` — literal8 doesn't allow non-synchronizing form.
        assert!(
            !output.contains("+}"),
            "literal8 must not contain non-synchronizing '+' suffix per RFC 9051 Section 9; got: {output}"
        );
        // Must contain the synchronizing literal8 form `~{100}\r\n`.
        assert!(
            output.contains("~{100}\r\n"),
            "literal8 must use synchronizing form ~{{100}} per RFC 9051 Section 9; got: {output}"
        );
    }

    /// RFC 9051 Section 9: when UTF8=ACCEPT is NOT active, LITERAL+ `{N+}` is fine.
    /// This test ensures we don't regress the normal LITERAL+ path.
    #[test]
    fn regular_literal_plus_still_works_without_utf8() {
        let mut buf = BytesMut::new();
        encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[],   // no flags
            None,  // no date
            200,   // message length
            true,  // first_message
            true,  // literal_plus = true (LITERAL+ is negotiated)
            false, // utf8 = false (no UTF8=ACCEPT)
        )
        .unwrap();
        let output = std::str::from_utf8(&buf).unwrap();
        // Regular literal with LITERAL+ must contain `{200+}\r\n`.
        assert!(
            output.contains("{200+}\r\n"),
            "regular literal with LITERAL+ must use non-synchronizing form {{200+}}; got: {output}"
        );
    }

    /// RFC 9051 Section 9: when neither LITERAL+ nor UTF8=ACCEPT, produce `{N}\r\n`.
    #[test]
    fn synchronizing_literal_without_utf8() {
        let mut buf = BytesMut::new();
        encode_multi_append_header(
            &mut buf,
            "A001",
            "INBOX",
            &[],   // no flags
            None,  // no date
            300,   // message length
            true,  // first_message
            false, // literal_plus = false
            false, // utf8 = false
        )
        .unwrap();
        let output = std::str::from_utf8(&buf).unwrap();
        // Must contain synchronizing literal `{300}\r\n`, no `+` or `~`.
        assert!(
            output.contains("{300}\r\n"),
            "synchronizing literal must use {{300}}; got: {output}"
        );
        assert!(
            !output.contains('~'),
            "non-UTF8 literal must not contain literal8 prefix '~'; got: {output}"
        );
    }

    // -----------------------------------------------------------------------
    // UNAUTHENTICATE command encoding (RFC 8437 Section 2)
    // -----------------------------------------------------------------------

    /// RFC 8437 Section 2: UNAUTHENTICATE takes no arguments and is encoded as
    /// `tag UNAUTHENTICATE\r\n`.
    #[test]
    fn encode_unauthenticate_command() {
        let mut buf = BytesMut::new();
        let cmd = Command::Unauthenticate;
        encode_command(&mut buf, "A001", &cmd).unwrap();
        assert_eq!(
            &buf[..],
            b"A001 UNAUTHENTICATE\r\n",
            "UNAUTHENTICATE must encode as 'tag UNAUTHENTICATE\\r\\n' per RFC 8437 Section 2"
        );
    }

    // -----------------------------------------------------------------------
    // date-day-fixed fallthrough (RFC 3501 Section 9)
    // -----------------------------------------------------------------------

    /// RFC 3501 Section 9: date-day-fixed = (SP DIGIT) / 2DIGIT.
    /// A day whose first byte is outside ' ', '0'-'3' must be rejected
    /// (the `_ => false` fallthrough in the day validator).
    #[test]
    fn validate_datetime_rejects_invalid_day_high_digit() {
        // Day "40" — first byte '4' falls into the _ => false branch.
        let result = validate_append_datetime("40-Jan-2024 12:00:00 +0000");
        assert!(
            result.is_err(),
            "day '40' must be rejected — first byte '4' is not in SP/'0'-'3' \
             per RFC 3501 Section 9 date-day-fixed"
        );
    }

    /// RFC 3501 Section 9: date-day-fixed rejects a first byte that is a
    /// non-digit, non-space character (e.g., 'X').
    #[test]
    fn validate_datetime_rejects_non_digit_day() {
        let result = validate_append_datetime("X1-Jan-2024 12:00:00 +0000");
        assert!(
            result.is_err(),
            "day 'X1' must be rejected — first byte 'X' is not valid \
             per RFC 3501 Section 9 date-day-fixed"
        );
    }

    /// Day starting with '9' also hits the fallthrough branch.
    #[test]
    fn validate_datetime_rejects_day_starting_with_nine() {
        let result = validate_append_datetime("91-Jan-2024 12:00:00 +0000");
        assert!(
            result.is_err(),
            "day '91' must be rejected — first byte '9' falls through \
             per RFC 3501 Section 9 date-day-fixed"
        );
    }

    // -----------------------------------------------------------------------
    // Date separator and field error paths (RFC 3501 Section 9)
    // -----------------------------------------------------------------------

    /// RFC 3501 Section 9: the first separator at position 2 must be '-'.
    #[test]
    fn validate_datetime_bad_separator_at_position_2() {
        // Replace '-' at position 2 with '/'.
        let result = validate_append_datetime("01/Jan-2024 12:00:00 +0000");
        assert!(
            result.is_err(),
            "non '-' at position 2 must be rejected per RFC 3501 Section 9"
        );
        let err_msg = result.unwrap_err().to_string();
        assert!(
            err_msg.contains("position 2"),
            "error should mention position 2, got: {err_msg}"
        );
    }

    /// RFC 3501 Section 9: the second separator at position 6 must be '-'.
    #[test]
    fn validate_datetime_bad_separator_at_position_6() {
        // Replace '-' at position 6 with '/'.
        let result = validate_append_datetime("01-Jan/2024 12:00:00 +0000");
        assert!(
            result.is_err(),
            "non '-' at position 6 must be rejected per RFC 3501 Section 9"
        );
        let err_msg = result.unwrap_err().to_string();
        assert!(
            err_msg.contains("position 6"),
            "error should mention position 6, got: {err_msg}"
        );
    }

    /// RFC 3501 Section 9: date-year must be 4DIGIT.
    #[test]
    fn validate_datetime_invalid_year() {
        // Replace year digits with non-digits.
        let result = validate_append_datetime("01-Jan-ABCD 12:00:00 +0000");
        assert!(
            result.is_err(),
            "non-digit year 'ABCD' must be rejected per RFC 3501 Section 9 date-year = 4DIGIT"
        );
        let err_msg = result.unwrap_err().to_string();
        assert!(
            err_msg.contains("year"),
            "error should mention year, got: {err_msg}"
        );
    }

    /// RFC 3501 Section 9: there must be a SP at position 11 (between date and time).
    #[test]
    fn validate_datetime_bad_separator_at_position_11() {
        // Replace SP at position 11 with 'X'.
        let result = validate_append_datetime("01-Jan-2024X12:00:00 +0000");
        assert!(
            result.is_err(),
            "non SP at position 11 must be rejected per RFC 3501 Section 9"
        );
        let err_msg = result.unwrap_err().to_string();
        assert!(
            err_msg.contains("position 11"),
            "error should mention position 11, got: {err_msg}"
        );
    }

    /// RFC 3501 Section 9: time must be 2DIGIT ":" 2DIGIT ":" 2DIGIT.
    #[test]
    fn validate_datetime_invalid_time_format() {
        // Replace colons in time with dashes.
        let result = validate_append_datetime("01-Jan-2024 12-00-00 +0000");
        assert!(
            result.is_err(),
            "time 'HH-MM-SS' must be rejected — colons are required per RFC 3501 Section 9"
        );
        let err_msg = result.unwrap_err().to_string();
        assert!(
            err_msg.contains("time"),
            "error should mention time, got: {err_msg}"
        );
    }

    /// RFC 3501 Section 9: time with non-digit characters must be rejected.
    #[test]
    fn validate_datetime_invalid_time_non_digit() {
        let result = validate_append_datetime("01-Jan-2024 AB:CD:EF +0000");
        assert!(
            result.is_err(),
            "non-digit time must be rejected per RFC 3501 Section 9 time = 2DIGIT \":\" 2DIGIT \":\" 2DIGIT"
        );
    }

    /// RFC 3501 Section 9: there must be a SP at position 20 (between time and zone).
    #[test]
    fn validate_datetime_bad_separator_at_position_20() {
        // Replace SP at position 20 with 'X'.
        let result = validate_append_datetime("01-Jan-2024 12:00:00X+0000");
        assert!(
            result.is_err(),
            "non SP at position 20 must be rejected per RFC 3501 Section 9"
        );
        let err_msg = result.unwrap_err().to_string();
        assert!(
            err_msg.contains("position 20"),
            "error should mention position 20, got: {err_msg}"
        );
    }

    /// RFC 3501 Section 9: zone must be ("+" / "-") 4DIGIT.
    #[test]
    fn validate_datetime_invalid_timezone_format() {
        // Zone without +/- prefix.
        let result = validate_append_datetime("01-Jan-2024 12:00:00 X0000");
        assert!(
            result.is_err(),
            "zone without +/- prefix must be rejected per RFC 3501 Section 9 zone format"
        );
        let err_msg = result.unwrap_err().to_string();
        assert!(
            err_msg.contains("zone"),
            "error should mention zone, got: {err_msg}"
        );
    }

    /// RFC 3501 Section 9: zone with non-digit HHMM must be rejected.
    #[test]
    fn validate_datetime_invalid_timezone_non_digit() {
        let result = validate_append_datetime("01-Jan-2024 12:00:00 +ABCD");
        assert!(
            result.is_err(),
            "zone with non-digit HHMM must be rejected per RFC 3501 Section 9"
        );
    }

    /// RFC 3501 Section 9 / RFC 5322 Section 4.3: timezone hour > 14 must be
    /// rejected (maximum real UTC offset is +14:00).
    #[test]
    fn validate_datetime_timezone_hour_exceeds_14() {
        let result = validate_append_datetime("01-Jan-2024 12:00:00 +1500");
        assert!(
            result.is_err(),
            "timezone hour 15 must be rejected — maximum is 14 (RFC 3501 Section 9)"
        );
        let err_msg = result.unwrap_err().to_string();
        assert!(
            err_msg.contains("zone hour"),
            "error should mention zone hour, got: {err_msg}"
        );
    }

    /// Boundary: timezone hour 14 is the maximum valid value and must be accepted.
    #[test]
    fn validate_datetime_timezone_hour_14_is_valid() {
        let result = validate_append_datetime("01-Jan-2024 12:00:00 +1400");
        assert!(
            result.is_ok(),
            "timezone hour 14 must be accepted — it is the maximum valid offset: {result:?}"
        );
    }

    /// RFC 3501 Section 9: timezone minute > 59 must be rejected.
    #[test]
    fn validate_datetime_timezone_minute_exceeds_59() {
        let result = validate_append_datetime("01-Jan-2024 12:00:00 +0060");
        assert!(
            result.is_err(),
            "timezone minute 60 must be rejected — maximum is 59 (RFC 3501 Section 9)"
        );
        let err_msg = result.unwrap_err().to_string();
        assert!(
            err_msg.contains("zone minute"),
            "error should mention zone minute, got: {err_msg}"
        );
    }

    /// Boundary: timezone minute 59 is the maximum valid value and must be accepted.
    #[test]
    fn validate_datetime_timezone_minute_59_is_valid() {
        let result = validate_append_datetime("01-Jan-2024 12:00:00 +0059");
        assert!(
            result.is_ok(),
            "timezone minute 59 must be accepted — it is the maximum valid value: {result:?}"
        );
    }

    // -----------------------------------------------------------------------
    // Non-UTF8 output formatting via from_utf8_lossy
    // -----------------------------------------------------------------------

    /// Verify that `String::from_utf8_lossy` correctly handles encoded output
    /// containing non-UTF8 bytes (e.g., high bytes in literal8 values).
    /// This exercises the lossy conversion path used in debug/display formatting.
    ///
    /// RFC 5464 Section 5 / RFC 3516: literal8 values can contain arbitrary
    /// octets that are not valid UTF-8.
    #[test]
    fn from_utf8_lossy_handles_non_utf8_encoded_output() {
        let mut buf = BytesMut::new();
        // Encode a SETMETADATA command with high-byte (non-UTF8) value.
        let value = b"\x80\x81\xfe\xff".to_vec();
        let cmd = Command::SetMetadata {
            mailbox: "INBOX".into(),
            entries: vec![("/private/binary".into(), Some(value))],
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        let output = &buf[..];

        // The output contains non-UTF8 bytes; from_utf8_lossy must produce
        // a valid string with U+FFFD replacement characters.
        let lossy = String::from_utf8_lossy(output);
        assert!(
            lossy.contains('\u{FFFD}'),
            "from_utf8_lossy must replace non-UTF8 bytes with U+FFFD; got: {lossy}"
        );
        // The lossy string must still contain the recognizable ASCII parts.
        assert!(
            lossy.contains("SETMETADATA"),
            "lossy output must preserve ASCII command keyword; got: {lossy}"
        );
        assert!(
            lossy.contains("INBOX"),
            "lossy output must preserve ASCII mailbox name; got: {lossy}"
        );
    }

    /// Verify `from_utf8_lossy` with NUL bytes in encoded output.
    /// NUL bytes (0x00) are valid UTF-8 but exercise the binary path in
    /// `encode_nstring_or_literal8` (literal8 syntax).
    ///
    /// RFC 3516: literal8 = "~{" number "}" CRLF *OCTET
    #[test]
    fn from_utf8_lossy_with_nul_bytes_in_output() {
        let mut buf = BytesMut::new();
        let value = b"\x00\x00".to_vec();
        let cmd = Command::SetMetadata {
            mailbox: "INBOX".into(),
            entries: vec![("/private/binary".into(), Some(value))],
        };
        encode_command(&mut buf, "A001", &cmd).unwrap();
        let output = &buf[..];

        // NUL bytes are valid UTF-8, so from_utf8_lossy should not replace them.
        let lossy = String::from_utf8_lossy(output);
        assert!(
            lossy.contains("SETMETADATA"),
            "lossy output must preserve command keyword even with NUL bytes; got: {lossy}"
        );
        // NUL bytes are preserved (they are valid single-byte UTF-8 codepoints).
        let nul_count = output
            .iter()
            .fold(0usize, |acc, &b| acc + usize::from(b == 0x00));
        assert_eq!(
            nul_count, 2,
            "both NUL bytes must be preserved in the encoded output"
        );
    }
}