omni_dev/drive/sheets/

structure.rs

//! Structural and destructive spreadsheet edits via `spreadsheets.batchUpdate`.
//!
//! The `drive sheets add-sheet`/`rename-sheet`/`insert-rows`/`insert-columns`
//! (additive, issue #1613, [ADR-0075](../../../docs/adrs/adr-0075.md)),
//! `insert-range` (additive, issue #1838),
//! `duplicate-sheet`/`reorder-sheet`/`hide-sheet`/`show-sheet` (also
//! additive, issue #1643, [ADR-0078](../../../docs/adrs/adr-0078.md)),
//! `move-rows`/`move-columns` (also additive — nothing is discarded, issue
//! #1834, [ADR-0083](../../../docs/adrs/adr-0083.md)),
//! `delete-sheet`/`delete-rows`/`delete-columns`/`delete-range` (destructive,
//! issue #1623,
//! [ADR-0077](../../../docs/adrs/adr-0077-sheets-deletion-via-batchupdate.md)),
//! and `update-workbook-properties` (also additive, issue #1836,
//! [ADR-0086](../../../docs/adrs/adr-0086-workbook-properties.md)) engines,
//! gated by the ADR-0071 folder write-permission rules.
//!
//! `update-workbook-properties` is the one verb here with no sheet target:
//! every other verb acts on a tab within the workbook, this one acts on the
//! workbook itself (locale, time zone, auto-recalc, iterative calculation —
//! deliberately not `spreadsheetTheme`, a large nested type left for a
//! future issue). [`StructureVerb::sheet_title`] returns `Option<&str>`
//! rather than `&str` for exactly this reason, and [`resolve_sheet`] returns
//! `Ok(None)` for it without consulting the sheet list at all. Turning
//! iterative calculation on is a value effect reached indirectly — it
//! changes what a circular-reference formula elsewhere *evaluates to*
//! without changing that formula itself, the same shape of concern
//! ADR-0081 raised for named-range deletion — so it stays gated as
//! `sheets-structure` rather than treated as a data mutation; see
//! [`crate::drive::sheets::types::IterativeCalculationSettings`]'s doc
//! comment.
//!
//! [ADR-0073](../../../docs/adrs/adr-0073.md) §12 deferred this surface
//! because `batchUpdate` is where "one call destroys far more than its
//! arguments suggest". Two properties answer that, and each is structural
//! rather than a matter of care:
//!
//! - **Typed verbs, no raw request passthrough.** Every verb builds its own
//!   [`BatchUpdateRequestItem`], so the gate and `--dry-run` can describe the
//!   exact effect. There is no `--requests file.json` and deliberately no
//!   escape hatch, following [ADR-0061](../../../docs/adrs/adr-0061.md)'s
//!   handling of force-push: the dangerous form must be unreachable, not
//!   merely discouraged. This still holds for the destructive verbs added by
//!   ADR-0077 — they gained typed variants, not a passthrough.
//! - **A distinct gate operation per risk class.** Additive verbs check
//!   [`DriveOperation::SheetsStructure`]; the four destructive verbs check
//!   [`DriveOperation::SheetsDelete`] instead — never folded together, and
//!   never reusing `SheetsWrite` either. See each variant's doc comment for
//!   why reuse would be silent privilege widening. [`StructureVerb::gate_operation`]
//!   is the single place this split is decided.
//!
//! ADR-0075 §3/§4 originally kept `deleteSheet`/`deleteDimension`/
//! `deleteRange` unreachable at the type level, pinned by a
//! `no_destructive_request_is_reachable` grep-guard test. ADR-0077
//! supersedes that: those requests are now reachable, but only through this
//! module's gated, validated path — never through a raw passthrough, and
//! never under the `sheets-structure` operation an existing `allow` rule may
//! already grant.
//!
//! Shape follows `write.rs` exactly: a public wrapper that logs, an `_inner`
//! that classifies then mutates, and `--dry-run` as an early return *after*
//! the gate so a preview and a real run share one classification by
//! construction. One difference is deliberate and tested: a dry run here does
//! issue a single `spreadsheets.get`, because describing a structural effect
//! honestly requires the sheet's real current dimensions. It still issues no
//! `batchUpdate`, and a gate-blocked attempt still issues no Sheets call at
//! all. `--dry-run` for a destructive verb stays structural-only — no
//! `values.get` read and no cell content in its output or the request log —
//! and instead states a fixed caveat that formulas elsewhere in the workbook
//! may reference what would be deleted, which cannot be checked from the
//! sheet's own dimensions (ADR-0077).

use std::path::PathBuf;
use std::time::{Duration, Instant};

use serde::Serialize;

use crate::cli::drive::format::{write_scalar_jsonl, JsonlSerialize};
use crate::drive::client::DriveClient;
use crate::drive::files_api::FilesApi;
use crate::drive::lease::check::{
    conclude_native_leased_write, gate_optional_leased_write, recovery_note, FromLeaseRefusal,
    LeaseGateRefusal, LeasedWrite,
};
use crate::drive::lease::ledger::LeaseBackup;
use crate::drive::sheets::api::SheetsApi;
use crate::drive::sheets::client::SheetsClient;
use crate::drive::sheets::format::{normalize_hex_for_display, parse_hex_color};
use crate::drive::sheets::grid_range;
use crate::drive::sheets::target_gate;
use crate::drive::sheets::types::{
    AddSheetRequest, BatchUpdateRequestItem, BatchUpdateResponse, ColorStyle,
    DeleteDimensionRequest, DeleteRangeRequest, DeleteSheetRequest, Dimension, DimensionRange,
    DuplicateSheetRequest, GridProperties, GridPropertiesUpdate, GridRange, InsertDimensionRequest,
    InsertRangeRequest, IterativeCalculationSettings, MoveDimensionRequest, NewSheetProperties,
    RecalculationInterval, SheetProperties, SheetPropertiesUpdate, ShiftDimension, Spreadsheet,
    SpreadsheetPropertiesUpdate, UpdateSheetPropertiesRequest, UpdateSpreadsheetPropertiesRequest,
};
use crate::drive::types::SheetTargetRefusal;
use crate::drive::write_gate::{self, DecidingRule, DriveOperation, FolderPermissionRule};
use crate::request_log::{self, DriveMutationOutcome};

/// Which structural mutation to perform.
///
/// Unlike `write.rs`'s [`WriteVerb`](crate::drive::sheets::write::WriteVerb),
/// which is fieldless with its arguments in the options struct, these verbs
/// take disjoint arguments, so the enum carries them. That also means an
/// impossible combination — a `--title` on an insert, say — is not
/// representable.
// `PartialEq`-only, not `Eq` (issue #1836):
// `UpdateWorkbookProperties::iterative_calculation_convergence_threshold`
// carries an `f64`, which has no meaningful `Eq` — see `Spreadsheet`'s own
// doc comment (`types.rs`) for the same reasoning applied to `Color`.
#[derive(Debug, Clone, PartialEq)]
pub enum StructureVerb {
    /// Add a new sheet to the workbook.
    AddSheet {
        /// Title for the new sheet.
        title: String,
        /// Zero-based position; `None` appends.
        index: Option<i64>,
        /// Initial row count; `None` takes Sheets' default.
        rows: Option<i64>,
        /// Initial column count; `None` takes Sheets' default.
        columns: Option<i64>,
    },
    /// Rename an existing sheet.
    RenameSheet {
        /// Current title of the sheet to rename.
        sheet: String,
        /// The new title.
        new_title: String,
    },
    /// Insert empty rows, shifting existing ones down.
    InsertRows {
        /// Title of the sheet to modify.
        sheet: String,
        /// 1-based row to insert before.
        at: i64,
        /// How many rows to insert.
        count: i64,
    },
    /// Insert empty columns, shifting existing ones right.
    InsertColumns {
        /// Title of the sheet to modify.
        sheet: String,
        /// 1-based column to insert before.
        at: i64,
        /// How many columns to insert.
        count: i64,
    },
    /// Insert empty cells into a rectangular range, shifting existing cells
    /// down or right within the same grid (issue #1838).
    ///
    /// All four bounds are required together: this crate only ever sends a
    /// fully-bounded [`GridRange`]. Whole rows and columns belong to
    /// [`Self::InsertRows`] and [`Self::InsertColumns`].
    InsertRange {
        /// Title of the sheet to modify.
        sheet: String,
        /// 1-based first row, inclusive.
        start_row: i64,
        /// 1-based last row, inclusive.
        end_row: i64,
        /// 1-based first column, inclusive.
        start_column: i64,
        /// 1-based last column, inclusive.
        end_column: i64,
        /// Which way existing cells shift to make room.
        shift: ShiftDimension,
    },
    /// Move a contiguous block of rows to a new position within the same
    /// sheet, shifting the rows in between to close the gap (issue #1834).
    MoveRows {
        /// Title of the sheet to modify.
        sheet: String,
        /// 1-based first row of the block to move, inclusive.
        at: i64,
        /// How many rows the block spans.
        count: i64,
        /// 1-based row the block moves in front of, numbered as the sheet
        /// stands *before* the move (the API's own `destinationIndex`
        /// convention, translated by `move_destination_index`).
        before: i64,
    },
    /// Move a contiguous block of columns to a new position within the same
    /// sheet, shifting the columns in between to close the gap (issue
    /// #1834).
    MoveColumns {
        /// Title of the sheet to modify.
        sheet: String,
        /// 1-based first column of the block to move, inclusive.
        at: i64,
        /// How many columns the block spans.
        count: i64,
        /// 1-based column the block moves in front of, numbered as the
        /// sheet stands *before* the move.
        before: i64,
    },
    /// Delete an entire sheet from the workbook.
    DeleteSheet {
        /// Title of the sheet to delete.
        sheet: String,
    },
    /// Delete whole rows, shifting the remainder up to close the gap.
    DeleteRows {
        /// Title of the sheet to modify.
        sheet: String,
        /// 1-based first row to delete, inclusive.
        at: i64,
        /// How many rows to delete.
        count: i64,
    },
    /// Delete whole columns, shifting the remainder left to close the gap.
    DeleteColumns {
        /// Title of the sheet to modify.
        sheet: String,
        /// 1-based first column to delete, inclusive.
        at: i64,
        /// How many columns to delete.
        count: i64,
    },
    /// Delete a rectangular cell range, shifting the remainder along one
    /// axis to close the gap.
    ///
    /// All four bounds are required together: this crate only ever sends a
    /// fully-bounded [`GridRange`]. An open-ended range on one axis would
    /// degenerate into [`Self::DeleteRows`]/[`Self::DeleteColumns`]
    /// semantics and is out of scope here.
    DeleteRange {
        /// Title of the sheet to modify.
        sheet: String,
        /// 1-based first row, inclusive.
        start_row: i64,
        /// 1-based last row, inclusive.
        end_row: i64,
        /// 1-based first column, inclusive.
        start_column: i64,
        /// 1-based last column, inclusive.
        end_column: i64,
        /// Which way to shift the remaining cells afterward.
        shift: ShiftDimension,
    },
    /// Copy an existing sheet within the same workbook.
    DuplicateSheet {
        /// Title of the sheet to copy.
        sheet: String,
        /// Title for the copy; `None` takes Sheets' own "Copy of X" default.
        title: Option<String>,
        /// Zero-based position for the copy; `None` appends.
        index: Option<i64>,
    },
    /// Move an existing sheet to a new position among its siblings.
    ReorderSheet {
        /// Title of the sheet to move.
        sheet: String,
        /// The new zero-based position.
        index: i64,
    },
    /// Hide or show an existing sheet.
    SetSheetVisibility {
        /// Title of the sheet to modify.
        sheet: String,
        /// `true` hides it, `false` shows it.
        hidden: bool,
    },
    /// Change a sheet's view properties — frozen rows/columns, tab color,
    /// right-to-left layout, and whether gridlines are hidden (issue #1835).
    /// Every field is independently optional; the caller sets whichever it
    /// passed, and `build_request`'s `fields` mask names exactly those.
    UpdateSheetProperties {
        /// Title of the sheet to modify.
        sheet: String,
        /// Rows to freeze at the top, when changing it.
        freeze_rows: Option<i64>,
        /// Columns to freeze at the left, when changing it.
        freeze_columns: Option<i64>,
        /// The new tab color, `#RRGGBB`, when setting it.
        tab_color: Option<String>,
        /// Clear the tab color back to none. Mutually exclusive with
        /// `tab_color` (the CLI's `clap::ArgGroup` conflict enforces this;
        /// `validate_verb_args` refuses the combination defensively too).
        clear_tab_color: bool,
        /// The new right-to-left flag, when changing it.
        right_to_left: Option<bool>,
        /// The new hide-gridlines flag, when changing it.
        hide_gridlines: Option<bool>,
    },
    /// Change workbook-level properties: locale, time zone, auto-recalc
    /// and/or iterative calculation (issue #1836). The one verb in this
    /// enum with no sheet target — see the module doc comment.
    UpdateWorkbookProperties {
        /// The new locale, e.g. `"en_US"`. `None` leaves it unchanged.
        locale: Option<String>,
        /// The new IANA time zone, e.g. `"America/New_York"`. `None` leaves
        /// it unchanged.
        time_zone: Option<String>,
        /// The new auto-recalculation interval. `None` leaves it unchanged.
        auto_recalc: Option<RecalculationInterval>,
        /// Turns iterative calculation on or off. `None` leaves it
        /// unchanged; the two sub-fields below are only meaningful
        /// alongside `Some(IterativeCalculationToggle::On)` —
        /// `validate_verb_args` refuses every other combination.
        iterative_calculation: Option<IterativeCalculationToggle>,
        /// Maximum calculation rounds, for `iterative_calculation ==
        /// Some(On)`. `None` takes Sheets' own default.
        iterative_calculation_max_iterations: Option<i64>,
        /// Convergence threshold, for `iterative_calculation ==
        /// Some(On)`. `None` takes Sheets' own default.
        iterative_calculation_convergence_threshold: Option<f64>,
    },
}

/// Which way `update-workbook-properties --iterative-calculation` sets
/// iterative calculation.
///
/// Not [`RecalculationInterval`]-style wire vocabulary: the API has no
/// boolean or enum field for this (see
/// [`IterativeCalculationSettings`]'s doc comment) — this type exists purely
/// to carry the caller's on/off *intent* through to `build_request`, which
/// turns it into the right combination of
/// [`SpreadsheetPropertiesUpdate::iterative_calculation_settings`] and
/// `fields`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum IterativeCalculationToggle {
    /// Turn iterative calculation on (or update its settings; it is
    /// already on).
    On,
    /// Turn iterative calculation off.
    Off,
}

impl StructureVerb {
    /// The `operation` this verb records in the request log.
    ///
    /// `build_drive_mutation_record` shapes `command` as `["drive",
    /// <operation>]`, so these read as `drive sheets-add-sheet` in the log
    /// even though the CLI spells them `drive sheets add-sheet`.
    const fn log_operation(&self) -> &'static str {
        match self {
            Self::AddSheet { .. } => "sheets-add-sheet",
            Self::RenameSheet { .. } => "sheets-rename-sheet",
            Self::InsertRows { .. } => "sheets-insert-rows",
            Self::InsertColumns { .. } => "sheets-insert-columns",
            Self::InsertRange { .. } => "sheets-insert-range",
            Self::MoveRows { .. } => "sheets-move-rows",
            Self::MoveColumns { .. } => "sheets-move-columns",
            Self::DeleteSheet { .. } => "sheets-delete-sheet",
            Self::DeleteRows { .. } => "sheets-delete-rows",
            Self::DeleteColumns { .. } => "sheets-delete-columns",
            Self::DeleteRange { .. } => "sheets-delete-range",
            Self::DuplicateSheet { .. } => "sheets-duplicate-sheet",
            Self::ReorderSheet { .. } => "sheets-reorder-sheet",
            Self::SetSheetVisibility { hidden: true, .. } => "sheets-hide-sheet",
            Self::SetSheetVisibility { hidden: false, .. } => "sheets-show-sheet",
            Self::UpdateSheetProperties { .. } => "sheets-update-sheet-properties",
            Self::UpdateWorkbookProperties { .. } => "sheets-update-workbook-properties",
        }
    }

    /// Which [`DriveOperation`] gates this verb.
    ///
    /// The single place the additive/destructive split is decided — see the
    /// module doc comment and [`DriveOperation::SheetsDelete`]'s doc comment
    /// for why the two must never share an operation.
    const fn gate_operation(&self) -> DriveOperation {
        match self {
            Self::AddSheet { .. }
            | Self::RenameSheet { .. }
            | Self::InsertRows { .. }
            | Self::InsertColumns { .. }
            | Self::InsertRange { .. }
            | Self::MoveRows { .. }
            | Self::MoveColumns { .. }
            | Self::DuplicateSheet { .. }
            | Self::ReorderSheet { .. }
            | Self::SetSheetVisibility { .. }
            | Self::UpdateSheetProperties { .. }
            | Self::UpdateWorkbookProperties { .. } => DriveOperation::SheetsStructure,
            Self::DeleteSheet { .. }
            | Self::DeleteRows { .. }
            | Self::DeleteColumns { .. }
            | Self::DeleteRange { .. } => DriveOperation::SheetsDelete,
        }
    }

    /// The CLI subcommand that spells this verb, for error messages that
    /// name the command the user actually typed — `write.rs::describe`'s
    /// convention.
    const fn label(&self) -> &'static str {
        match self {
            Self::AddSheet { .. } => "add-sheet",
            Self::RenameSheet { .. } => "rename-sheet",
            Self::InsertRows { .. } => "insert-rows",
            Self::InsertColumns { .. } => "insert-columns",
            Self::InsertRange { .. } => "insert-range",
            Self::MoveRows { .. } => "move-rows",
            Self::MoveColumns { .. } => "move-columns",
            Self::DeleteSheet { .. } => "delete-sheet",
            Self::DeleteRows { .. } => "delete-rows",
            Self::DeleteColumns { .. } => "delete-columns",
            Self::DeleteRange { .. } => "delete-range",
            Self::DuplicateSheet { .. } => "duplicate-sheet",
            Self::ReorderSheet { .. } => "reorder-sheet",
            Self::SetSheetVisibility { hidden: true, .. } => "hide-sheet",
            Self::SetSheetVisibility { hidden: false, .. } => "show-sheet",
            Self::UpdateSheetProperties { .. } => "update-sheet-properties",
            Self::UpdateWorkbookProperties { .. } => "update-workbook-properties",
        }
    }

    /// The title of the sheet this verb acts on: the one being created for
    /// `AddSheet`, the existing target otherwise; `None` for
    /// `UpdateWorkbookProperties`, which acts on the workbook itself and
    /// resolves no sheet at all (see the module doc comment).
    fn sheet_title(&self) -> Option<&str> {
        match self {
            Self::AddSheet { title, .. } => Some(title),
            Self::RenameSheet { sheet, .. }
            | Self::InsertRows { sheet, .. }
            | Self::InsertColumns { sheet, .. }
            | Self::InsertRange { sheet, .. }
            | Self::MoveRows { sheet, .. }
            | Self::MoveColumns { sheet, .. }
            | Self::DeleteSheet { sheet }
            | Self::DeleteRows { sheet, .. }
            | Self::DeleteColumns { sheet, .. }
            | Self::DeleteRange { sheet, .. }
            | Self::DuplicateSheet { sheet, .. }
            | Self::ReorderSheet { sheet, .. }
            | Self::SetSheetVisibility { sheet, .. }
            | Self::UpdateSheetProperties { sheet, .. } => Some(sheet),
            Self::UpdateWorkbookProperties { .. } => None,
        }
    }

    /// The title this verb moves the sheet *to*, or `None` for every verb
    /// that renames nothing.
    ///
    /// The companion to [`Self::sheet_title`], which necessarily reports the
    /// title a rename started from — without this the request log could say
    /// which tab was renamed but not to what, the one structural effect a
    /// record could not otherwise reconstruct. `DuplicateSheet`'s explicit
    /// `--title`, when given, is the same kind of fact for the same reason:
    /// the copy's name is not recoverable from `sheet_title` alone, which
    /// necessarily names the *source*.
    fn new_sheet_title(&self) -> Option<&String> {
        match self {
            Self::RenameSheet { new_title, .. } => Some(new_title),
            Self::DuplicateSheet { title, .. } => title.as_ref(),
            Self::AddSheet { .. }
            | Self::InsertRows { .. }
            | Self::InsertColumns { .. }
            | Self::InsertRange { .. }
            | Self::MoveRows { .. }
            | Self::MoveColumns { .. }
            | Self::DeleteSheet { .. }
            | Self::DeleteRows { .. }
            | Self::DeleteColumns { .. }
            | Self::DeleteRange { .. }
            | Self::ReorderSheet { .. }
            | Self::SetSheetVisibility { .. }
            | Self::UpdateSheetProperties { .. }
            | Self::UpdateWorkbookProperties { .. } => None,
        }
    }

    /// The axis an insert, a row/column delete or a row/column move runs
    /// along, or `None` for the verbs with no single axis (`add-sheet`,
    /// `rename-sheet`, `delete-sheet`, `delete-range`).
    const fn dimension(&self) -> Option<Dimension> {
        match self {
            Self::InsertRows { .. } | Self::DeleteRows { .. } | Self::MoveRows { .. } => {
                Some(Dimension::Rows)
            }
            Self::InsertColumns { .. } | Self::DeleteColumns { .. } | Self::MoveColumns { .. } => {
                Some(Dimension::Columns)
            }
            Self::AddSheet { .. }
            | Self::RenameSheet { .. }
            | Self::DeleteSheet { .. }
            | Self::InsertRange { .. }
            | Self::DeleteRange { .. }
            | Self::DuplicateSheet { .. }
            | Self::ReorderSheet { .. }
            | Self::SetSheetVisibility { .. }
            | Self::UpdateSheetProperties { .. }
            | Self::UpdateWorkbookProperties { .. } => None,
        }
    }
}

/// Per-call options.
#[derive(Debug, Clone)]
pub struct StructureOptions {
    /// Spreadsheet id.
    pub spreadsheet_id: String,
    /// Which mutation to perform.
    pub verb: StructureVerb,
    /// Classify and describe only; never call `batchUpdate`.
    pub dry_run: bool,
    /// The lease token presented via `--lease`. Checked only when the
    /// deciding rule requires one
    /// ([`write_gate::decided_rule_requires_lease`], ADR-0080 §1/§9);
    /// `None` is only ever valid when it does not.
    pub lease_token: Option<String>,
    /// Path to the lease ledger the token is checked against. Production
    /// callers pass `crate::drive::lease::ledger::ledger_path`'s own
    /// result; tests pass a path under a `tempdir`.
    pub ledger_path: PathBuf,
}

/// The sheet a verb resolved to, plus its dimensions at that moment.
///
/// Captured before the mutation so [`describe`] can state the *change*
/// ("1000 rows -> 1003") rather than only the request, which is the whole
/// point of a structural dry run.
#[derive(Debug, Clone, Default, Serialize, PartialEq, Eq)]
pub struct SheetSnapshot {
    /// The sheet's stable numeric id.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sheet_id: Option<i64>,
    /// Its title at the time of the attempt.
    pub title: String,
    /// Allocated rows, when the API reported them.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub row_count: Option<i64>,
    /// Allocated columns, when the API reported them.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub column_count: Option<i64>,
    /// Rows frozen at the top, when the API reported them (issue #1835).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub frozen_row_count: Option<i64>,
    /// Columns frozen at the left, when the API reported them (issue #1835).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub frozen_column_count: Option<i64>,
    /// Whether the sheet is right-to-left, when the API reported it (issue
    /// #1835).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub right_to_left: Option<bool>,
    /// Whether gridlines are hidden, when the API reported it (issue #1835).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub hide_gridlines: Option<bool>,
}

impl SheetSnapshot {
    fn from_properties(props: &SheetProperties) -> Self {
        let grid = props.grid_properties.as_ref();
        Self {
            sheet_id: props.sheet_id,
            title: props.title.clone(),
            row_count: grid.and_then(|g| g.row_count),
            column_count: grid.and_then(|g| g.column_count),
            frozen_row_count: grid.and_then(|g| g.frozen_row_count),
            frozen_column_count: grid.and_then(|g| g.frozen_column_count),
            right_to_left: props.right_to_left,
            hide_gridlines: grid.and_then(|g| g.hide_gridlines),
        }
    }
}

/// What happened (or, under `--dry-run`, would happen).
#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
#[serde(tag = "status", rename_all = "kebab-case")]
pub enum StructureResult {
    /// `--dry-run`, and the gate would allow it.
    WouldChange {
        /// The target sheet as it stands now. `None` for an `add-sheet`,
        /// which has no existing sheet to snapshot.
        ///
        /// Boxed (issue #1835): `SheetSnapshot` grew enough with
        /// `update-sheet-properties`'s frozen-row/column and layout fields
        /// that this enum otherwise trips `clippy::result_large_err`, the
        /// same reasoning `Changed`'s own `backup` field is already boxed
        /// for.
        #[serde(skip_serializing_if = "Option::is_none")]
        sheet: Option<Box<SheetSnapshot>>,
        /// How many sheets the workbook currently has.
        sheet_count: usize,
    },
    /// The target is not a Google Sheet. Checked client-side before the
    /// gate: restructuring a PDF isn't disallowed, it's meaningless.
    RefusedNotASpreadsheet {
        /// The target's actual MIME type.
        mime_type: String,
    },
    /// The target is a shortcut, which we do not follow.
    RefusedShortcut,
    /// The target has no parents this account can see, so the folder gate
    /// has no ancestor chain to evaluate. Distinct from `Blocked`; see
    /// `write.rs`'s variant of the same name.
    RefusedNoVisibleParents,
    /// The named sheet does not exist in this workbook.
    ///
    /// Not the client-side validation ADR-0073 §7 rejects: §7 is about A1
    /// *grammar*, where a naive validator rejects legal forms. Here the
    /// server's own authoritative sheet list is already in hand, and without
    /// this check a `--dry-run` would promise a change the real run fails.
    RefusedSheetNotFound {
        /// The title that was not found.
        title: String,
        /// The titles that do exist, so the message can be actionable.
        available: Vec<String>,
    },
    /// `add-sheet` was given a title the workbook already uses, or
    /// `rename-sheet`'s new title collides with a *different* existing
    /// sheet. Sheets rejects a duplicate title, and catching it here keeps
    /// the dry run truthful.
    RefusedSheetExists {
        /// The colliding title.
        title: String,
    },
    /// A numeric argument (`--at`, `--count`, `--rows`, `--columns`,
    /// `--index`) is out of range for what the workbook actually contains —
    /// checked against the same `spreadsheets.get` response already fetched
    /// for the dry run, so this costs nothing extra and is exactly as
    /// correct as the server's own eventual rejection would be (ADR-0075
    /// §6's reasoning for the sheet-existence/duplicate-title checks,
    /// applied to a numeric bound instead of a title). Also reused for
    /// `update-workbook-properties`' argument-combination checks (issue
    /// #1836, e.g. "needs at least one property to set"), which need no
    /// workbook state at all — `format.rs::FormatResult::RefusedInvalidRange`
    /// is the same broadening for `format-cells`' "at least one property"
    /// check.
    RefusedInvalidRange {
        /// What was wrong and why.
        detail: String,
    },
    /// The folder write-permission gate refused it.
    Blocked {
        /// The rule that decided the refusal, if any (`None` means the bare
        /// default policy — every write defaults deny).
        decided_by: Option<DecidingRule>,
    },
    /// No `--lease` was presented, and the deciding rule requires one
    /// (ADR-0080 §9).
    RefusedNoLease,
    /// The presented lease has expired, or was never a token this ledger
    /// knows about.
    RefusedLeaseExpired,
    /// The presented lease is bound to a different file id.
    RefusedLeaseWrongFile,
    /// The file has moved since the lease's recorded `version` — the
    /// staleness check (ADR-0080 §6).
    RefusedLeaseStale,
    /// The workbook is already in the requested state (`hide-sheet` on a
    /// hidden sheet, `show-sheet` on a visible one), so no request is
    /// sent. Reported identically by a dry run and a real run, and
    /// distinct from `Changed` so a script can tell a no-op from a change.
    Unchanged {
        /// Why nothing needed to change.
        detail: String,
    },
    /// The mutation succeeded.
    Changed {
        /// The sheet acted on, as it stood *before* the change.
        ///
        /// Boxed for the same `clippy::result_large_err` reason as
        /// `WouldChange`'s own `sheet` field (issue #1835).
        #[serde(skip_serializing_if = "Option::is_none")]
        sheet: Option<Box<SheetSnapshot>>,
        /// The sheet id, which for `add-sheet` the server assigns and is
        /// only knowable from the reply.
        #[serde(skip_serializing_if = "Option::is_none")]
        sheet_id: Option<i64>,
        /// Where the lease this write presented backed the file up at
        /// `drive lease acquire` time — the copy to restore from after a
        /// destructive verb. `None` when the deciding write-permission
        /// rule set `require_lease: false`, in which case no backup was
        /// taken (ADR-0080 §13) and the outcome must not claim one.
        ///
        /// Read straight off the ledger record the write was checked
        /// against (`drive::lease::check::LeaseGrant`), never
        /// assumed, so the recovery message a real-run delete prints is
        /// only ever true. Boxed only to keep the enum under clippy's
        /// `result_large_err` threshold — `LeaseBackup::Bytes` carries a
        /// path plus a hash, and this enum is a `Result` error type inside
        /// the engine.
        #[serde(skip_serializing_if = "Option::is_none")]
        backup: Option<Box<LeaseBackup>>,
    },
    /// An API or validation error.
    Failed {
        /// A human-readable summary of what failed.
        detail: String,
    },
}

impl FromLeaseRefusal for StructureResult {
    fn from_no_lease() -> Self {
        Self::RefusedNoLease
    }
    fn from_lease_expired() -> Self {
        Self::RefusedLeaseExpired
    }
    fn from_lease_wrong_file() -> Self {
        Self::RefusedLeaseWrongFile
    }
    fn from_lease_stale() -> Self {
        Self::RefusedLeaseStale
    }
    fn from_lease_failed(detail: String) -> Self {
        Self::Failed { detail }
    }
}

impl StructureResult {
    /// The `status` string the request log records.
    ///
    /// Hand-written rather than derived from the `#[serde(tag)]` shape,
    /// matching `WriteResult`/`MoveResult`'s precedent of keeping the log's
    /// vocabulary decoupled from the wire format.
    fn log_status(&self) -> &'static str {
        match self {
            Self::WouldChange { .. } => "would-change",
            Self::RefusedNotASpreadsheet { .. } => "refused-not-a-spreadsheet",
            Self::RefusedShortcut => "refused-shortcut",
            Self::RefusedNoVisibleParents => "refused-no-visible-parents",
            Self::RefusedSheetNotFound { .. } => "refused-sheet-not-found",
            Self::RefusedSheetExists { .. } => "refused-sheet-exists",
            Self::RefusedInvalidRange { .. } => "refused-invalid-range",
            Self::Blocked { .. } => "blocked",
            Self::RefusedNoLease => LeaseGateRefusal::NoLease.log_status(),
            Self::RefusedLeaseExpired => LeaseGateRefusal::Expired.log_status(),
            Self::RefusedLeaseWrongFile => LeaseGateRefusal::WrongFile.log_status(),
            Self::RefusedLeaseStale => LeaseGateRefusal::Stale.log_status(),
            Self::Unchanged { .. } => "unchanged",
            Self::Changed { .. } => "changed",
            Self::Failed { .. } => "failed",
        }
    }
}

/// The full outcome of one attempt.
///
/// `PartialEq`-only, not `Eq` (issue #1836) — it embeds [`StructureVerb`],
/// which is `PartialEq`-only for the same reason.
#[derive(Debug, Clone, Serialize, PartialEq)]
pub struct StructureOutcome {
    /// The spreadsheet acted on.
    pub spreadsheet_id: String,
    /// Its Drive file name, when the metadata fetch got that far.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub file_name: Option<String>,
    /// The folder the gate evaluated against, when exactly one parent
    /// resolved it.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub resolved_folder_id: Option<String>,
    /// Which mutation was attempted.
    ///
    /// Not serialised: the caller already knows which verb it invoked, and
    /// the JSON shape is a stable output contract. It is carried so
    /// [`describe`] can render an outcome from the outcome alone, rather
    /// than taking a verb a caller could mismatch against it.
    #[serde(skip)]
    pub verb: StructureVerb,
    /// What happened.
    pub result: StructureResult,
}

impl JsonlSerialize for StructureOutcome {
    fn write_jsonl(&self, out: &mut dyn std::io::Write) -> anyhow::Result<()> {
        write_scalar_jsonl(self, out)
    }
}

/// Converts a 1-based inclusive `--at` into the API's zero-based half-open
/// [`DimensionRange`].
///
/// The single conversion site, on purpose. `--at` is 1-based because that is
/// what A1 and the spreadsheet UI show the user; `DimensionRange` is
/// 0-based half-open because that is the API. Inlining this at a call site
/// is how the obvious off-by-one in this feature would get in.
fn dimension_range(sheet_id: i64, dimension: Dimension, at: i64, count: i64) -> DimensionRange {
    let start = at - 1;
    DimensionRange {
        sheet_id,
        dimension,
        start_index: start,
        end_index: start + count,
    }
}

/// Converts a 1-based `--before` into the API's zero-based, pre-move
/// `destinationIndex`.
///
/// The single conversion site, on purpose — see [`dimension_range`]'s doc
/// comment for why inlining this at a call site is how an off-by-one gets
/// in. `moveDimension` numbers its destination in the sheet's coordinates
/// *before* the source is lifted out, which is exactly what `--before`
/// means, so the conversion is the 1-based/0-based shift and nothing else.
const fn move_destination_index(before: i64) -> i64 {
    before - 1
}

/// The block's landing span after a move, given `--before`'s pre-move
/// numbering, the block's `count`, and its inclusive pre-move last index.
///
/// The single computation site, on purpose — [`describe_would_move`] (the
/// dry-run preview) and [`describe_moved`] (the real-run message) both need
/// it, and a formula duplicated between them could drift so the preview and
/// the confirmation disagree about where the block ended up.
/// `validate_move_bounds` refuses every `before` in `at..=at + count`, so
/// callers may assume exactly one of the two branches applies.
const fn move_landing_span(before: i64, count: i64, last: i64) -> (i64, i64) {
    if before > last {
        // Downward: the block lands immediately before where `before` used
        // to sit — `count` short of the number typed, since the rows/
        // columns between the block and the destination slide back to
        // close the gap.
        (before - count, before - 1)
    } else {
        // Upward (`before < at`): the block lands exactly on the number
        // typed.
        (before, before + count - 1)
    }
}

/// Runs one structural mutation, logging every attempt that isn't a dry run.
///
/// Never returns `Err`: every failure is a [`StructureResult`] variant, so
/// the caller renders one shape and the log records one shape. Exit code
/// stays 0 regardless, matching ADR-0073 §13.
pub async fn structure(
    drive: &DriveClient,
    sheets: &SheetsClient,
    opts: &StructureOptions,
    rules: &[FolderPermissionRule],
) -> StructureOutcome {
    let started = Instant::now();
    let outcome = structure_inner(drive, sheets, opts, rules).await;
    // The single logging site, and the only reason a dry run leaves no
    // record — `structure_inner` never logs.
    if !opts.dry_run {
        record_attempt(&outcome, opts, started.elapsed());
    }
    outcome
}

async fn structure_inner(
    drive: &DriveClient,
    sheets: &SheetsClient,
    opts: &StructureOptions,
    rules: &[FolderPermissionRule],
) -> StructureOutcome {
    let bare = |result| StructureOutcome {
        spreadsheet_id: opts.spreadsheet_id.clone(),
        file_name: None,
        resolved_folder_id: None,
        verb: opts.verb.clone(),
        result,
    };

    // ── Target resolution, pre-gate refusals, and the gate itself ──────
    // Shared with `write.rs` via `target_gate::resolve`, so this whole
    // shape — the metadata fetch, the shortcut/non-spreadsheet checks, and
    // the file-id-then-ancestor-chain gate lookup — can't quietly drift
    // between the two engines.
    let (target, decision, resolved_folder_id, requires_lease) = match target_gate::resolve(
        drive,
        &opts.spreadsheet_id,
        opts.verb.gate_operation(),
        rules,
    )
    .await
    {
        target_gate::TargetGateOutcome::MetadataFetchFailed { detail } => {
            return bare(StructureResult::Failed { detail })
        }
        target_gate::TargetGateOutcome::Refused { target, refusal } => {
            let result = match refusal {
                SheetTargetRefusal::Shortcut => StructureResult::RefusedShortcut,
                SheetTargetRefusal::NotASpreadsheet { mime_type } => {
                    StructureResult::RefusedNotASpreadsheet { mime_type }
                }
                SheetTargetRefusal::NoVisibleParents => StructureResult::RefusedNoVisibleParents,
            };
            return StructureOutcome {
                spreadsheet_id: opts.spreadsheet_id.clone(),
                file_name: Some(target.name),
                resolved_folder_id: None,
                verb: opts.verb.clone(),
                result,
            };
        }
        // A chain that could not be resolved is a refusal, never a silent
        // allow — ADR-0071 §3's highest-priority invariant.
        target_gate::TargetGateOutcome::GateFetchFailed { target, detail } => {
            return StructureOutcome {
                spreadsheet_id: opts.spreadsheet_id.clone(),
                file_name: Some(target.name),
                resolved_folder_id: None,
                verb: opts.verb.clone(),
                result: StructureResult::Failed { detail },
            };
        }
        target_gate::TargetGateOutcome::Gated {
            target,
            decision,
            resolved_folder_id,
            requires_lease,
        } => (target, decision, resolved_folder_id, requires_lease),
    };

    let gated = |result| StructureOutcome {
        spreadsheet_id: opts.spreadsheet_id.clone(),
        file_name: Some(target.name.clone()),
        resolved_folder_id: resolved_folder_id.clone(),
        verb: opts.verb.clone(),
        result,
    };

    if decision.verdict == write_gate::Verdict::Deny {
        return gated(StructureResult::Blocked {
            decided_by: decision.decided_by,
        });
    }

    // ── Resolve the workbook ───────────────────────────────────────────
    // After the gate on purpose: a blocked attempt makes zero Sheets calls,
    // preserving ADR-0073's "a refusal is exactly as auditable as a success"
    // consequence. This *is* a read, so a dry run reaches it — that is what
    // lets `describe` state real dimensions rather than guess.
    let api = SheetsApi::new(sheets);
    let workbook = match api.get_spreadsheet(&opts.spreadsheet_id).await {
        Ok(workbook) => workbook,
        Err(err) => {
            return gated(StructureResult::Failed {
                detail: format!("{err:#}"),
            })
        }
    };

    let sheet = match resolve_sheet(&workbook, &opts.verb) {
        Ok(sheet) => sheet,
        Err(result) => return gated(result),
    };
    let sheet_count = workbook.sheets.len();

    if let Err(result) = validate_verb_args(&workbook, &opts.verb, sheet.as_ref()) {
        return gated(result);
    }

    // Before the dry-run branch, so a dry run reports the no-op the real
    // run would, and before the lease check, since nothing is written.
    if let Some(detail) = already_applied(&workbook, &opts.verb, sheet.as_ref()) {
        return gated(StructureResult::Unchanged { detail });
    }

    if opts.dry_run {
        // A move, not a clone: this branch always returns, so `sheet` is
        // never read again on it — the later uses below are only reachable
        // on the disjoint non-dry-run path.
        return gated(StructureResult::WouldChange {
            sheet: sheet.map(Box::new),
            sheet_count,
        });
    }

    // ── The request ────────────────────────────────────────────────────
    // Built before the gate, not after: a sheet that resolved by title but
    // reported no `sheetId` (a server contract violation `build_request`
    // refuses on) is the one fallible step between here and the mutating
    // call, and the gate must be the *last* fallible step before it (see
    // `gate_leased_write`'s doc comment) — otherwise a request that was
    // always going to fail to build would still fsync a `pending` audit
    // record for a write that never happens (#1688).
    let request = match build_request(&opts.verb, sheet.as_ref()) {
        Ok(request) => request,
        Err(detail) => return gated(StructureResult::Failed { detail }),
    };

    // The lease check (ADR-0080 §9) sits here: after the permission gate
    // and the `--dry-run` branch, before the mutating call — see
    // `content_edit.rs::edit_inner`'s doc comment for the full reasoning,
    // shared verbatim by every leased engine. Sheets has no revision field
    // of any kind (§6), so the staleness check is a fresh `files.get`
    // immediately before `batchUpdate`, not a reuse of the metadata
    // `target_gate::resolve` fetched before the (potentially slow)
    // ancestor-chain walk and workbook fetch above.
    let files_api = FilesApi::new(drive);
    let leased = LeasedWrite {
        log_prefix: "drive sheets structure",
        operation: opts.verb.log_operation(),
        ledger_path: &opts.ledger_path,
        file_id: &opts.spreadsheet_id,
    };
    let lease_grant = match gate_optional_leased_write(
        leased,
        &files_api,
        requires_lease,
        opts.lease_token.as_deref(),
    )
    .await
    {
        Ok(grant) => grant,
        Err(err) => return gated(err.into_result()),
    };

    let result = match conclude_native_leased_write(
        leased,
        &lease_grant,
        &files_api,
        api.batch_update(&opts.spreadsheet_id, vec![request]).await,
        |err| format!("{err:#}"),
    )
    .await
    {
        Ok(response) => StructureResult::Changed {
            sheet_id: added_sheet_id(&response).or_else(|| sheet.as_ref().and_then(|s| s.sheet_id)),
            sheet: sheet.map(Box::new),
            backup: lease_grant
                .as_ref()
                .map(|grant| Box::new(grant.backup.clone())),
        },
        Err(err) => StructureResult::Failed {
            detail: format!("{err:#}"),
        },
    };
    drop(lease_grant);
    gated(result)
}

/// Finds the sheet a verb targets, or classifies why it cannot.
///
/// `add-sheet` inverts the check: it needs the title *not* to exist, and
/// returns `Ok(None)` because there is no existing sheet to snapshot.
/// `rename-sheet` checks both directions: the *current* title must exist,
/// and the *new* title must not already belong to some other sheet — the
/// same duplicate-title refusal `add-sheet` gets, since Sheets rejects a
/// duplicate title regardless of which verb produced it. Renaming a sheet
/// to the title it already has is not a collision (it names itself, not a
/// different sheet) and is allowed through as a no-op mutation.
///
/// `update-workbook-properties` returns `Ok(None)` immediately, before even
/// looking at the sheet list — [`StructureVerb::sheet_title`] returns `None`
/// for it, since it names no sheet at all.
fn resolve_sheet(
    workbook: &Spreadsheet,
    verb: &StructureVerb,
) -> Result<Option<SheetSnapshot>, StructureResult> {
    let Some(wanted) = verb.sheet_title() else {
        return Ok(None);
    };
    let found = workbook
        .sheets
        .iter()
        .filter_map(|sheet| sheet.properties.as_ref())
        .find(|props| props.title == wanted);

    match verb {
        StructureVerb::AddSheet { .. } => match found {
            Some(_) => Err(StructureResult::RefusedSheetExists {
                title: wanted.to_string(),
            }),
            None => Ok(None),
        },
        StructureVerb::RenameSheet { new_title, .. } => match found {
            Some(props) => {
                let collides = new_title != wanted && workbook.has_sheet_titled(new_title);
                if collides {
                    return Err(StructureResult::RefusedSheetExists {
                        title: new_title.clone(),
                    });
                }
                Ok(Some(SheetSnapshot::from_properties(props)))
            }
            None => Err(StructureResult::RefusedSheetNotFound {
                title: wanted.to_string(),
                available: workbook.sheet_titles(),
            }),
        },
        // Like `add-sheet`, a given `--title` must not already be in use —
        // and unlike `rename-sheet`, colliding with the *source's own*
        // title is still a collision: the source keeps its name, so a copy
        // asking for that same name would land on an existing sheet either
        // way.
        StructureVerb::DuplicateSheet { title, .. } => match found {
            Some(props) => {
                if let Some(new_title) = title {
                    let collides = workbook.has_sheet_titled(new_title);
                    if collides {
                        return Err(StructureResult::RefusedSheetExists {
                            title: new_title.clone(),
                        });
                    }
                }
                Ok(Some(SheetSnapshot::from_properties(props)))
            }
            None => Err(StructureResult::RefusedSheetNotFound {
                title: wanted.to_string(),
                available: workbook.sheet_titles(),
            }),
        },
        _ => match found {
            Some(props) => Ok(Some(SheetSnapshot::from_properties(props))),
            None => Err(StructureResult::RefusedSheetNotFound {
                title: wanted.to_string(),
                available: workbook.sheet_titles(),
            }),
        },
    }
}

/// Why `verb` would change nothing, when the workbook is already in the
/// state it asks for. Only `hide-sheet`/`show-sheet` can tell: their whole
/// effect is one flag the fetched workbook already reports.
fn already_applied(
    workbook: &Spreadsheet,
    verb: &StructureVerb,
    sheet: Option<&SheetSnapshot>,
) -> Option<String> {
    let StructureVerb::SetSheetVisibility {
        sheet: title,
        hidden,
    } = verb
    else {
        return None;
    };
    let target_id = sheet.and_then(|s| s.sheet_id)?;
    let currently_hidden = workbook
        .sheets
        .iter()
        .filter_map(|s| s.properties.as_ref())
        .find(|props| props.sheet_id == Some(target_id))?
        .hidden
        .unwrap_or(false);
    (currently_hidden == *hidden).then(|| {
        let state = if *hidden { "hidden" } else { "shown" };
        format!("sheet '{title}' is already {state}")
    })
}

/// Validates the numeric arguments a verb carries against the workbook's
/// actual state, so a dry run can never promise a change the real run then
/// rejects. Runs after [`resolve_sheet`] (which is why it can read the
/// target sheet's real dimensions) and before the `--dry-run` early return,
/// so both share this classification exactly like the gate above it.
fn validate_verb_args(
    workbook: &Spreadsheet,
    verb: &StructureVerb,
    sheet: Option<&SheetSnapshot>,
) -> Result<(), StructureResult> {
    let invalid = |detail: String| Err(StructureResult::RefusedInvalidRange { detail });

    match verb {
        StructureVerb::AddSheet {
            index,
            rows,
            columns,
            ..
        } => {
            if let Some(rows) = rows {
                if *rows < 1 {
                    return invalid(format!("--rows must be at least 1, got {rows}"));
                }
            }
            if let Some(columns) = columns {
                if *columns < 1 {
                    return invalid(format!("--columns must be at least 1, got {columns}"));
                }
            }
            if let Some(index) = index {
                let max = workbook.sheets.len() as i64;
                if *index < 0 || *index > max {
                    return invalid(format!(
                        "--index must be between 0 and {max} inclusive (the workbook has \
                         {max} sheet(s)), got {index}"
                    ));
                }
            }
            Ok(())
        }
        StructureVerb::RenameSheet { .. }
        | StructureVerb::DeleteSheet { .. }
        | StructureVerb::DuplicateSheet { index: None, .. }
        | StructureVerb::SetSheetVisibility { hidden: false, .. } => Ok(()),
        StructureVerb::InsertRows { at, count, .. } => {
            validate_insert_bounds(Dimension::Rows, *at, *count, sheet)
        }
        StructureVerb::InsertColumns { at, count, .. } => {
            validate_insert_bounds(Dimension::Columns, *at, *count, sheet)
        }
        StructureVerb::MoveRows {
            at, count, before, ..
        } => validate_move_bounds(Dimension::Rows, *at, *count, *before, sheet),
        StructureVerb::MoveColumns {
            at, count, before, ..
        } => validate_move_bounds(Dimension::Columns, *at, *count, *before, sheet),
        StructureVerb::DeleteRows { at, count, .. } => {
            validate_delete_dimension_bounds(Dimension::Rows, *at, *count, sheet)
        }
        StructureVerb::DeleteColumns { at, count, .. } => {
            validate_delete_dimension_bounds(Dimension::Columns, *at, *count, sheet)
        }
        StructureVerb::InsertRange {
            start_row,
            end_row,
            start_column,
            end_column,
            ..
        }
        | StructureVerb::DeleteRange {
            start_row,
            end_row,
            start_column,
            end_column,
            ..
        } => validate_range_bounds(*start_row, *end_row, *start_column, *end_column, sheet),
        StructureVerb::DuplicateSheet {
            index: Some(index), ..
        } => {
            // Same bound as `add-sheet`'s `--index`: a duplicate also adds
            // one sheet, so the valid positions are identical.
            let max = workbook.sheets.len() as i64;
            if *index < 0 || *index > max {
                return invalid(format!(
                    "--index must be between 0 and {max} inclusive (the workbook has \
                     {max} sheet(s)), got {index}"
                ));
            }
            Ok(())
        }
        StructureVerb::ReorderSheet { index, .. } => {
            // Unlike `add-sheet`/`duplicate-sheet`, this repositions an
            // *existing* sheet rather than adding one, so the top of the
            // valid range is one less.
            let len = workbook.sheets.len() as i64;
            let max = len - 1;
            if *index < 0 || *index > max {
                return invalid(format!(
                    "--index must be between 0 and {max} inclusive (the workbook has \
                     {len} sheet(s)), got {index}"
                ));
            }
            Ok(())
        }
        StructureVerb::SetSheetVisibility {
            sheet: title,
            hidden: true,
        } => {
            let target_id = sheet.and_then(|s| s.sheet_id);
            let another_stays_visible = workbook
                .sheets
                .iter()
                .filter_map(|s| s.properties.as_ref())
                .filter(|props| props.sheet_id != target_id)
                .any(|props| !props.hidden.unwrap_or(false));
            if !another_stays_visible {
                return invalid(format!(
                    "hiding '{title}' would leave the workbook with no visible sheets; \
                     Sheets requires at least one"
                ));
            }
            Ok(())
        }
        StructureVerb::UpdateSheetProperties {
            sheet: _title,
            freeze_rows,
            freeze_columns,
            tab_color,
            clear_tab_color,
            right_to_left,
            hide_gridlines,
        } => {
            if freeze_rows.is_none()
                && freeze_columns.is_none()
                && tab_color.is_none()
                && !clear_tab_color
                && right_to_left.is_none()
                && hide_gridlines.is_none()
            {
                return invalid(
                    "update-sheet-properties requires at least one property to change".to_string(),
                );
            }
            if tab_color.is_some() && *clear_tab_color {
                return invalid(
                    "--tab-color and --clear-tab-color are mutually exclusive".to_string(),
                );
            }
            if let Some(hex) = tab_color {
                if let Err(detail) = parse_hex_color(hex) {
                    return invalid(detail);
                }
            }
            if let Some(rows) = freeze_rows {
                check_freeze_bound(
                    "--freeze-rows",
                    "row",
                    *rows,
                    sheet.and_then(|s| s.row_count),
                )?;
            }
            if let Some(columns) = freeze_columns {
                check_freeze_bound(
                    "--freeze-columns",
                    "column",
                    *columns,
                    sheet.and_then(|s| s.column_count),
                )?;
            }
            Ok(())
        }
        StructureVerb::UpdateWorkbookProperties {
            locale,
            time_zone,
            auto_recalc,
            iterative_calculation,
            iterative_calculation_max_iterations,
            iterative_calculation_convergence_threshold,
        } => {
            let touches_iterative_settings = iterative_calculation_max_iterations.is_some()
                || iterative_calculation_convergence_threshold.is_some();
            if touches_iterative_settings
                && *iterative_calculation != Some(IterativeCalculationToggle::On)
            {
                return invalid(
                    "--iterative-calculation-max-iterations/\
                     --iterative-calculation-convergence-threshold require \
                     --iterative-calculation on"
                        .to_string(),
                );
            }
            if let Some(max_iterations) = iterative_calculation_max_iterations {
                if *max_iterations < 1 {
                    return invalid(format!(
                        "--iterative-calculation-max-iterations must be at least 1, got \
                         {max_iterations}"
                    ));
                }
            }
            if let Some(threshold) = iterative_calculation_convergence_threshold {
                if !threshold.is_finite() || *threshold <= 0.0 {
                    return invalid(format!(
                        "--iterative-calculation-convergence-threshold must be a positive, \
                         finite number, got {threshold}"
                    ));
                }
            }
            // Checked locally because the API will not: an unrecognised zone
            // is accepted with a 200 and the workbook is silently reset to
            // `Etc/GMT`, discarding its previous zone (issue #1938). An
            // unknown `--locale`, by contrast, is a 400 from the API.
            if let Some(tz) = time_zone {
                if tz.parse::<chrono_tz::Tz>().is_err() {
                    return invalid(format!(
                        "--time-zone '{tz}' is not a recognised IANA time zone name \
                         (for example 'America/New_York' or 'Europe/London'); the \
                         Sheets API would silently reset the workbook to 'Etc/GMT' \
                         instead of rejecting it"
                    ));
                }
            }
            if locale.is_none()
                && time_zone.is_none()
                && auto_recalc.is_none()
                && iterative_calculation.is_none()
            {
                return invalid(
                    "update-workbook-properties needs at least one property to set \
                     (--locale, --time-zone, --auto-recalc, --iterative-calculation)"
                        .to_string(),
                );
            }
            Ok(())
        }
    }
}

/// The `--count >= 1` / `--at >= 1` / overflow checks shared by
/// [`validate_insert_bounds`], [`validate_move_bounds`] and
/// [`validate_delete_dimension_bounds`] — every span-based verb needs them
/// verbatim, so they live in one place rather than three, and returns the
/// inclusive last index (`at - 1 + count`) so callers that need it (move,
/// delete) don't recompute it.
///
/// Keeps `dimension_range`'s `at - 1 + count` total, so the one pure
/// conversion stays infallible and every value that reaches it is already
/// known to fit. Deliberately an *arithmetic* bound and not a ceiling on how
/// many rows may be added: the workbook's own state implies no upper bound
/// on `--count`, so inventing one would be the client-side validation
/// ADR-0073 §7 rejects, with Sheets the authority on how large a sheet may
/// actually get.
fn validate_span_start(dimension: Dimension, at: i64, count: i64) -> Result<i64, StructureResult> {
    let invalid = |detail: String| StructureResult::RefusedInvalidRange { detail };

    if count < 1 {
        return Err(invalid(format!("--count must be at least 1, got {count}")));
    }
    if at < 1 {
        return Err(invalid(format!("--at must be at least 1, got {at}")));
    }
    at.checked_sub(1)
        .and_then(|start| start.checked_add(count))
        .ok_or_else(|| {
            invalid(format!(
                "--at {at} with --count {count} overflows the {noun} index space",
                noun = dimension.noun(),
            ))
        })
}

/// Validates a `--freeze-rows`/`--freeze-columns` value: non-negative, and,
/// when the sheet's current count is known, strictly less than it — Sheets
/// requires at least one row/column to stay unfrozen and rejects a request
/// that would freeze the whole grid. Shared by both flags in
/// [`validate_verb_args`]'s `UpdateSheetProperties` arm (issue #1835) so the
/// bound and its wording can't drift between them.
fn check_freeze_bound(
    flag: &str,
    noun: &str,
    value: i64,
    current: Option<i64>,
) -> Result<(), StructureResult> {
    if value < 0 {
        return Err(StructureResult::RefusedInvalidRange {
            detail: format!("{flag} must be at least 0, got {value}"),
        });
    }
    if let Some(current) = current {
        if value >= current {
            return Err(StructureResult::RefusedInvalidRange {
                detail: format!(
                    "{flag} {value} would freeze every {noun}; the sheet has {current} \
                     {noun}(s), so the most that can be frozen is {}",
                    current - 1
                ),
            });
        }
    }
    Ok(())
}

/// The `InsertRows`/`InsertColumns` half of [`validate_verb_args`], split
/// out so each caller supplies its own [`Dimension`] directly rather than
/// recovering it from the verb.
fn validate_insert_bounds(
    dimension: Dimension,
    at: i64,
    count: i64,
    sheet: Option<&SheetSnapshot>,
) -> Result<(), StructureResult> {
    let invalid = |detail: String| Err(StructureResult::RefusedInvalidRange { detail });

    validate_span_start(dimension, at, count)?;
    let current = match dimension {
        Dimension::Rows => sheet.and_then(|s| s.row_count),
        Dimension::Columns => sheet.and_then(|s| s.column_count),
    };
    if let Some(current) = current {
        // `at == current + 1` is a legal append (insert after the last
        // row/column); anything past that names a position that does not
        // exist and is not immediately after one that does.
        let max_at = current + 1;
        if at > max_at {
            return invalid(format!(
                "--at {at} is past the end of the sheet, which has {current} {noun}(s); \
                 the furthest valid position is {max_at}",
                noun = dimension.noun(),
            ));
        }
    }
    Ok(())
}

/// The `MoveRows`/`MoveColumns` half of [`validate_verb_args`].
///
/// Three bounds, and the third is the one a move adds. The source block must
/// already exist in full (delete's rule), and `--before` may name the
/// append boundary one past the last row/column (insert's rule) — but a
/// destination *inside* the block, or immediately after it, describes a
/// position the block already occupies. `moveDimension` accepts those
/// happily and changes nothing, so refusing them is the same "never promise
/// a change the real run then rejects" rule read the other way round: never
/// report having moved something that did not move. That check needs no
/// sheet size, only the relationship between `--at`, `--count` and
/// `--before`, so it runs whether or not the sheet's dimensions are known.
fn validate_move_bounds(
    dimension: Dimension,
    at: i64,
    count: i64,
    before: i64,
    sheet: Option<&SheetSnapshot>,
) -> Result<(), StructureResult> {
    let invalid = |detail: String| Err(StructureResult::RefusedInvalidRange { detail });

    let last = validate_span_start(dimension, at, count)?;
    if before < 1 {
        return invalid(format!("--before must be at least 1, got {before}"));
    }
    // `before == at + count` is the no-op boundary: the block already sits
    // immediately before that row/column, so lifting it out and putting it
    // back lands it exactly where it was. `before == at - 1` is one further
    // out and is a real move.
    // `before - 1 <= last` rather than `before <= last + 1`: `last` is only
    // known not to overflow `at - 1 + count`, so adding to it could, while
    // `before` is already known to be at least 1.
    if before >= at && before - 1 <= last {
        return invalid(format!(
            "--before {before} is inside or immediately after the block being moved \
             ({noun}s {at}-{last}), so nothing would move",
            noun = dimension.noun(),
        ));
    }
    let current = match dimension {
        Dimension::Rows => sheet.and_then(|s| s.row_count),
        Dimension::Columns => sheet.and_then(|s| s.column_count),
    };
    if let Some(current) = current {
        if last > current {
            return invalid(format!(
                "--at {at} with --count {count} reaches {noun} {last}, past the end of the \
                 sheet, which has {current} {noun}(s)",
                noun = dimension.noun(),
            ));
        }
        // The same append boundary insert allows: `before == current + 1`
        // moves the block to the very end.
        let max_before = current + 1;
        if before > max_before {
            return invalid(format!(
                "--before {before} is past the end of the sheet, which has {current} \
                 {noun}(s); the furthest valid position is {max_before}",
                noun = dimension.noun(),
            ));
        }
    }
    Ok(())
}

/// The `DeleteRows`/`DeleteColumns` half of [`validate_verb_args`].
///
/// Mirrors [`validate_insert_bounds`], but deletion has no append-boundary
/// case: every row/column named must already exist, so the exclusive end
/// index may never exceed the sheet's current size.
fn validate_delete_dimension_bounds(
    dimension: Dimension,
    at: i64,
    count: i64,
    sheet: Option<&SheetSnapshot>,
) -> Result<(), StructureResult> {
    let invalid = |detail: String| Err(StructureResult::RefusedInvalidRange { detail });

    let last = validate_span_start(dimension, at, count)?;
    let current = match dimension {
        Dimension::Rows => sheet.and_then(|s| s.row_count),
        Dimension::Columns => sheet.and_then(|s| s.column_count),
    };
    if let Some(current) = current {
        if last > current {
            return invalid(format!(
                "--at {at} with --count {count} reaches {noun} {last}, past the end of the \
                 sheet, which has {current} {noun}(s)",
                noun = dimension.noun(),
            ));
        }
    }
    Ok(())
}

/// The `InsertRange`/`DeleteRange` half of [`validate_verb_args`].
///
/// Checks both axes are well-ordered and within the sheet's current bounds —
/// the same "never promise a change the real run then rejects" reasoning as
/// [`validate_insert_bounds`], applied to a rectangle instead of a span.
fn validate_range_bounds(
    start_row: i64,
    end_row: i64,
    start_column: i64,
    end_column: i64,
    sheet: Option<&SheetSnapshot>,
) -> Result<(), StructureResult> {
    let invalid = |detail: String| Err(StructureResult::RefusedInvalidRange { detail });

    if start_row < 1 {
        return invalid(format!("--start-row must be at least 1, got {start_row}"));
    }
    if start_column < 1 {
        return invalid(format!(
            "--start-column must be at least 1, got {start_column}"
        ));
    }
    if end_row < start_row {
        return invalid(format!(
            "--end-row ({end_row}) must be at or after --start-row ({start_row})"
        ));
    }
    if end_column < start_column {
        return invalid(format!(
            "--end-column ({end_column}) must be at or after --start-column ({start_column})"
        ));
    }
    if let Some(current) = sheet.and_then(|s| s.row_count) {
        if end_row > current {
            return invalid(format!(
                "--end-row {end_row} is past the end of the sheet, which has {current} row(s)"
            ));
        }
    }
    if let Some(current) = sheet.and_then(|s| s.column_count) {
        if end_column > current {
            return invalid(format!(
                "--end-column {end_column} is past the end of the sheet, which has {current} \
                 column(s)"
            ));
        }
    }
    Ok(())
}

/// Builds the single `batchUpdate` request a verb sends.
///
/// Every verb produces exactly one request, which is why partial application
/// is not observable here and why one log record per verb is also one record
/// per request.
fn build_request(
    verb: &StructureVerb,
    sheet: Option<&SheetSnapshot>,
) -> Result<BatchUpdateRequestItem, String> {
    // Every verb but `add-sheet` addresses a sheet by its numeric id, and
    // the `fields` mask on `spreadsheets.get` always requests it. A sheet
    // that resolved by title but reported no id is a server contract
    // violation, not a user error — fail rather than guess at 0, which is a
    // real sheet id.
    let sheet_id = |verb_name: &str| -> Result<i64, String> {
        sheet.and_then(|s| s.sheet_id).ok_or_else(|| {
            format!("Sheets did not report a sheetId for the target sheet, so {verb_name} cannot address it")
        })
    };

    match verb {
        StructureVerb::AddSheet {
            title,
            index,
            rows,
            columns,
        } => {
            let grid_properties = (rows.is_some() || columns.is_some()).then_some(GridProperties {
                row_count: *rows,
                column_count: *columns,
                ..Default::default()
            });
            Ok(BatchUpdateRequestItem::AddSheet(AddSheetRequest {
                properties: NewSheetProperties {
                    title: title.clone(),
                    index: *index,
                    grid_properties,
                },
            }))
        }
        StructureVerb::RenameSheet { new_title, .. } => Ok(
            BatchUpdateRequestItem::UpdateSheetProperties(UpdateSheetPropertiesRequest {
                properties: SheetPropertiesUpdate {
                    sheet_id: sheet_id("rename-sheet")?,
                    title: Some(new_title.clone()),
                    ..Default::default()
                },
                // Exactly the one field we set. A wider mask would blank
                // every property it named but we left unpopulated.
                fields: "title".to_string(),
            }),
        ),
        StructureVerb::InsertRows { at, count, .. } => Ok(BatchUpdateRequestItem::InsertDimension(
            InsertDimensionRequest {
                range: dimension_range(sheet_id("insert-rows")?, Dimension::Rows, *at, *count),
                inherit_from_before: false,
            },
        )),
        StructureVerb::InsertColumns { at, count, .. } => Ok(
            BatchUpdateRequestItem::InsertDimension(InsertDimensionRequest {
                range: dimension_range(
                    sheet_id("insert-columns")?,
                    Dimension::Columns,
                    *at,
                    *count,
                ),
                inherit_from_before: false,
            }),
        ),
        StructureVerb::InsertRange {
            start_row,
            end_row,
            start_column,
            end_column,
            shift,
            ..
        } => Ok(BatchUpdateRequestItem::InsertRange(InsertRangeRequest {
            range: grid_range(
                sheet_id("insert-range")?,
                *start_row,
                *end_row,
                *start_column,
                *end_column,
            ),
            shift_dimension: *shift,
        })),
        StructureVerb::MoveRows {
            at, count, before, ..
        } => Ok(BatchUpdateRequestItem::MoveDimension(
            MoveDimensionRequest {
                source: dimension_range(sheet_id("move-rows")?, Dimension::Rows, *at, *count),
                destination_index: move_destination_index(*before),
            },
        )),
        StructureVerb::MoveColumns {
            at, count, before, ..
        } => Ok(BatchUpdateRequestItem::MoveDimension(
            MoveDimensionRequest {
                source: dimension_range(sheet_id("move-columns")?, Dimension::Columns, *at, *count),
                destination_index: move_destination_index(*before),
            },
        )),
        StructureVerb::DeleteSheet { .. } => {
            Ok(BatchUpdateRequestItem::DeleteSheet(DeleteSheetRequest {
                sheet_id: sheet_id("delete-sheet")?,
            }))
        }
        StructureVerb::DeleteRows { at, count, .. } => Ok(BatchUpdateRequestItem::DeleteDimension(
            DeleteDimensionRequest {
                range: dimension_range(sheet_id("delete-rows")?, Dimension::Rows, *at, *count),
            },
        )),
        StructureVerb::DeleteColumns { at, count, .. } => Ok(
            BatchUpdateRequestItem::DeleteDimension(DeleteDimensionRequest {
                range: dimension_range(
                    sheet_id("delete-columns")?,
                    Dimension::Columns,
                    *at,
                    *count,
                ),
            }),
        ),
        StructureVerb::DeleteRange {
            start_row,
            end_row,
            start_column,
            end_column,
            shift,
            ..
        } => Ok(BatchUpdateRequestItem::DeleteRange(DeleteRangeRequest {
            range: grid_range(
                sheet_id("delete-range")?,
                *start_row,
                *end_row,
                *start_column,
                *end_column,
            ),
            shift_dimension: *shift,
        })),
        StructureVerb::DuplicateSheet { title, index, .. } => Ok(
            BatchUpdateRequestItem::DuplicateSheet(DuplicateSheetRequest {
                source_sheet_id: sheet_id("duplicate-sheet")?,
                insert_sheet_index: *index,
                new_sheet_name: title.clone(),
            }),
        ),
        StructureVerb::ReorderSheet { index, .. } => Ok(
            BatchUpdateRequestItem::UpdateSheetProperties(UpdateSheetPropertiesRequest {
                properties: SheetPropertiesUpdate {
                    sheet_id: sheet_id("reorder-sheet")?,
                    index: Some(*index),
                    ..Default::default()
                },
                fields: "index".to_string(),
            }),
        ),
        StructureVerb::SetSheetVisibility { hidden, .. } => Ok(
            BatchUpdateRequestItem::UpdateSheetProperties(UpdateSheetPropertiesRequest {
                properties: SheetPropertiesUpdate {
                    sheet_id: sheet_id(if *hidden { "hide-sheet" } else { "show-sheet" })?,
                    hidden: Some(*hidden),
                    ..Default::default()
                },
                fields: "hidden".to_string(),
            }),
        ),
        StructureVerb::UpdateSheetProperties {
            freeze_rows,
            freeze_columns,
            tab_color,
            clear_tab_color,
            right_to_left,
            hide_gridlines,
            ..
        } => {
            let mut fields = Vec::new();
            let mut grid = GridPropertiesUpdate::default();
            if let Some(rows) = freeze_rows {
                grid.frozen_row_count = Some(*rows);
                fields.push("gridProperties.frozenRowCount");
            }
            if let Some(columns) = freeze_columns {
                grid.frozen_column_count = Some(*columns);
                fields.push("gridProperties.frozenColumnCount");
            }
            if let Some(hide) = hide_gridlines {
                grid.hide_gridlines = Some(*hide);
                fields.push("gridProperties.hideGridlines");
            }
            let mut tab_color_style = None;
            if let Some(hex) = tab_color {
                // Already validated in `validate_verb_args`; re-parsing here
                // rather than threading the parsed `Color` through keeps this
                // function the sole place a request is assembled from a
                // verb, matching every sibling arm's shape.
                let color = parse_hex_color(hex)
                    .map_err(|detail| format!("update-sheet-properties: {detail}"))?;
                tab_color_style = Some(ColorStyle::rgb(color));
                fields.push("tabColorStyle");
            } else if *clear_tab_color {
                fields.push("tabColorStyle");
            }
            if right_to_left.is_some() {
                fields.push("rightToLeft");
            }
            if fields.is_empty() {
                // `validate_verb_args` already refuses this before
                // `build_request` is ever reached; this is an unreachable
                // defensive fallback, not a real path.
                // omni-dev: coverage ignore reason="validate_verb_args refuses an UpdateSheetProperties verb that set none of its six properties before structure_inner ever reaches build_request, and every one of those six pushes a fields entry, so fields is never empty here"
                return Err("update-sheet-properties: no property was set".to_string());
                // omni-dev: coverage end
            }
            Ok(BatchUpdateRequestItem::UpdateSheetProperties(
                UpdateSheetPropertiesRequest {
                    properties: SheetPropertiesUpdate {
                        sheet_id: sheet_id("update-sheet-properties")?,
                        grid_properties: (grid != GridPropertiesUpdate::default()).then_some(grid),
                        tab_color_style,
                        right_to_left: *right_to_left,
                        ..Default::default()
                    },
                    fields: fields.join(","),
                },
            ))
        }
        StructureVerb::UpdateWorkbookProperties {
            locale,
            time_zone,
            auto_recalc,
            iterative_calculation,
            iterative_calculation_max_iterations,
            iterative_calculation_convergence_threshold,
        } => {
            // `validate_verb_args` already refused an empty field set and
            // every invalid iterative-calculation combination, so every
            // branch below is infallible and `fields` is guaranteed
            // non-empty.
            let mut properties = SpreadsheetPropertiesUpdate::default();
            let mut fields = Vec::new();
            if let Some(locale) = locale {
                properties.locale = Some(locale.clone());
                fields.push("locale");
            }
            if let Some(time_zone) = time_zone {
                properties.time_zone = Some(time_zone.clone());
                fields.push("timeZone");
            }
            if let Some(auto_recalc) = auto_recalc {
                properties.auto_recalc = Some(*auto_recalc);
                fields.push("autoRecalc");
            }
            match iterative_calculation {
                Some(IterativeCalculationToggle::On) => {
                    properties.iterative_calculation_settings =
                        Some(IterativeCalculationSettings {
                            max_iterations: *iterative_calculation_max_iterations,
                            convergence_threshold: *iterative_calculation_convergence_threshold,
                        });
                    fields.push("iterativeCalculationSettings");
                }
                // `properties.iterative_calculation_settings` stays `None`
                // here, and `fields` still names the property — an absent
                // key on a masked field clears it, which is how "off" is
                // spelled (see `IterativeCalculationSettings`'s doc
                // comment).
                Some(IterativeCalculationToggle::Off) => {
                    fields.push("iterativeCalculationSettings");
                }
                None => {}
            }
            Ok(BatchUpdateRequestItem::UpdateSpreadsheetProperties(
                UpdateSpreadsheetPropertiesRequest {
                    properties,
                    fields: fields.join(","),
                },
            ))
        }
    }
}

/// A human-readable summary of the fields an `update-workbook-properties`
/// verb sets, e.g. `"locale -> 'en_US', auto-recalc -> ON_CHANGE"`.
///
/// Shared by the dry-run preview ([`describe_would_change`]), the real-run
/// confirmation ([`describe_changed`]) and the request log's
/// `fields_changed` (`record_attempt`), so the three can never describe a
/// different set of fields than the request actually carries — the same
/// "describe from one source of truth" discipline `dimension_range_label`/
/// `grid_range_label` use for the other structural verbs.
///
/// Panics if `verb` is not [`StructureVerb::UpdateWorkbookProperties`];
/// every call site matches on the verb first, so this is never reached
/// otherwise.
fn workbook_properties_summary(verb: &StructureVerb) -> String {
    let StructureVerb::UpdateWorkbookProperties {
        locale,
        time_zone,
        auto_recalc,
        iterative_calculation,
        iterative_calculation_max_iterations,
        iterative_calculation_convergence_threshold,
    } = verb
    // omni-dev: coverage ignore reason="every call site matches on the verb as UpdateWorkbookProperties before calling workbook_properties_summary, so this else-arm exists only to destructure the already-known variant"
    else {
        unreachable!("workbook_properties_summary called on a non-UpdateWorkbookProperties verb")
    };
    // omni-dev: coverage end

    let mut parts = Vec::new();
    if let Some(locale) = locale {
        parts.push(format!("locale -> '{locale}'"));
    }
    if let Some(time_zone) = time_zone {
        parts.push(format!("time zone -> '{time_zone}'"));
    }
    if let Some(auto_recalc) = auto_recalc {
        parts.push(format!("auto-recalc -> {}", auto_recalc.as_str()));
    }
    match iterative_calculation {
        Some(IterativeCalculationToggle::On) => {
            let bounds = IterativeCalculationSettings {
                max_iterations: *iterative_calculation_max_iterations,
                convergence_threshold: *iterative_calculation_convergence_threshold,
            }
            .describe_bounds();
            parts.push(format!("iterative calculation -> on{bounds}"));
        }
        Some(IterativeCalculationToggle::Off) => {
            parts.push("iterative calculation -> off".to_string());
        }
        None => {}
    }
    parts.join(", ")
}

/// Converts 1-based inclusive row/column bounds into the API's zero-based
/// half-open [`GridRange`]. The [`dimension_range`] of `DeleteRange`: the
/// single conversion site for the same reason.
fn grid_range(
    sheet_id: i64,
    start_row: i64,
    end_row: i64,
    start_column: i64,
    end_column: i64,
) -> GridRange {
    GridRange {
        sheet_id,
        start_row_index: Some(start_row - 1),
        end_row_index: Some(end_row),
        start_column_index: Some(start_column - 1),
        end_column_index: Some(end_column),
    }
}

/// The `sheetId` the server assigned to a newly added sheet, if this reply
/// carries one — via `addSheet` or `duplicateSheet`, whichever this batch
/// happened to contain (`structure.rs` never sends both in one request, so
/// there is no ambiguity to resolve between them).
fn added_sheet_id(response: &BatchUpdateResponse) -> Option<i64> {
    response
        .replies
        .iter()
        .find_map(|reply| reply.add_sheet.as_ref().or(reply.duplicate_sheet.as_ref()))
        .and_then(|added| added.properties.as_ref())
        .and_then(|props| props.sheet_id)
}

/// The `dimension_range` context value the request log records, e.g.
/// `"ROWS 5:7"` — the structural analogue of a cell verb's A1 `range`, for
/// effects A1 cannot express. 1-based inclusive, matching the CLI's `--at`.
///
/// Total over every `--at`/`--count` the CLI can parse, which is load-bearing
/// rather than defensive: [`record_attempt`] logs *attempts*, so this runs on
/// the refusal path too — with exactly the values
/// [`validate_insert_bounds`] just rejected. Arithmetic that only holds for
/// validated input would panic while recording the refusal of the input that
/// broke it. A span that cannot be computed is omitted (the log key is
/// omit-if-absent) rather than recorded inverted; the `refused-invalid-range`
/// status and its `detail` already carry the numbers the user typed.
fn dimension_range_label(verb: &StructureVerb) -> Option<String> {
    let dimension = verb.dimension()?;
    let (at, count) = match verb {
        StructureVerb::InsertRows { at, count, .. }
        | StructureVerb::InsertColumns { at, count, .. }
        | StructureVerb::DeleteRows { at, count, .. }
        | StructureVerb::DeleteColumns { at, count, .. }
        | StructureVerb::MoveRows { at, count, .. }
        | StructureVerb::MoveColumns { at, count, .. } => (*at, *count),
        _ => return None,
    };
    // A span is only meaningful for a positive count. `count < 1` is a
    // refusal `validate_insert_bounds` has already classified, and
    // `at + count - 1` computes cleanly for it while meaning nothing — an
    // *inverted* span, which is the misleading answer rather than the
    // missing one.
    if count < 1 {
        return None;
    }
    let end = at.checked_add(count).and_then(|end| end.checked_sub(1))?;
    Some(dimension.span_label(at, end))
}

/// The `grid_range` context value the request log records for a
/// `insert-range` or `delete-range` verb, e.g. `"rows 2-10, columns 2-4"` — 1-based inclusive,
/// matching the CLI's `--start-row`/`--end-row`/`--start-column`/
/// `--end-column`. `None` for every other verb.
fn grid_range_label(verb: &StructureVerb) -> Option<String> {
    match verb {
        StructureVerb::InsertRange {
            start_row,
            end_row,
            start_column,
            end_column,
            ..
        }
        | StructureVerb::DeleteRange {
            start_row,
            end_row,
            start_column,
            end_column,
            ..
        } => Some(format!(
            "rows {start_row}-{end_row}, columns {start_column}-{end_column}"
        )),
        _ => None,
    }
}

/// Emits the `kind: "drivemutation"` record.
///
/// Inside the engine, never the CLI layer, so a future MCP caller cannot
/// bypass it — and so a `Blocked` outcome, which makes zero Sheets calls,
/// still leaves a trace. Same reasoning as `write.rs::record_attempt`.
fn record_attempt(outcome: &StructureOutcome, opts: &StructureOptions, duration: Duration) {
    let error = match &outcome.result {
        StructureResult::Failed { detail } => Some(detail.clone()),
        _ => None,
    };
    let decided_by = match &outcome.result {
        StructureResult::Blocked { decided_by } => decided_by.as_ref(),
        _ => None,
    };
    let decided_by = write_gate::decided_by_log_fields(decided_by);
    let sheet_id = match &outcome.result {
        StructureResult::Changed { sheet_id, .. } => *sheet_id,
        StructureResult::WouldChange { sheet, .. } => sheet.as_ref().and_then(|s| s.sheet_id),
        _ => None,
    };
    // The destination `dimension_range` cannot carry: it names the span that
    // moved, not where it went.
    let move_to = match &opts.verb {
        StructureVerb::MoveRows { before, .. } | StructureVerb::MoveColumns { before, .. } => {
            Some(*before)
        }
        _ => None,
    };
    // `format.rs`'s field, reused here rather than duplicated: the only
    // structural verbs (issues #1835/#1836) that can set more than one
    // field in a single request, so `sheet_title`/`dimension_range`/
    // `grid_range` alone can't name the effect.
    let fields_changed = match &opts.verb {
        StructureVerb::UpdateWorkbookProperties { .. } => {
            Some(workbook_properties_summary(&opts.verb))
        }
        _ => fields_changed_label(&opts.verb),
    };

    request_log::record_drive_mutation(DriveMutationOutcome {
        operation: opts.verb.log_operation(),
        file_id: outcome.spreadsheet_id.clone(),
        file_name: outcome.file_name.clone().unwrap_or_default(),
        status: outcome.result.log_status().to_string(),
        resolved_folder_id: outcome.resolved_folder_id.clone(),
        decided_by_folder_id: decided_by.folder_id,
        decided_by_depth: decided_by.depth,
        decided_by_file_id: decided_by.file_id,
        sheet_id,
        sheet_title: opts.verb.sheet_title().map(ToString::to_string),
        sheet_new_title: opts.verb.new_sheet_title().map(ToString::to_string),
        dimension_range: dimension_range_label(&opts.verb),
        move_to,
        grid_range: grid_range_label(&opts.verb),
        fields_changed,
        error,
        duration,
        ..Default::default()
    });
}

/// The `fields_changed` context value the request log records for an
/// `update-sheet-properties` verb, e.g. `"frozenRowCount=2,
/// tabColorStyle=#FF8800"` — a comma-joined list of the properties this verb
/// set, reusing the `fields_changed` context key `format.rs` already writes
/// for `format-cells`/`update-borders`/etc. rather than adding a new one
/// (docs/log.md). `None` for every other verb.
///
/// Runs on the refusal path too, like [`dimension_range_label`]/
/// [`grid_range_label`]: `record_attempt` logs attempts, not only successes,
/// so this reports what the verb *asked* to change even when the request was
/// never built.
fn fields_changed_label(verb: &StructureVerb) -> Option<String> {
    let StructureVerb::UpdateSheetProperties {
        freeze_rows,
        freeze_columns,
        tab_color,
        clear_tab_color,
        right_to_left,
        hide_gridlines,
        ..
    } = verb
    else {
        return None;
    };
    let mut parts = Vec::new();
    if let Some(rows) = freeze_rows {
        parts.push(format!("frozenRowCount={rows}"));
    }
    if let Some(columns) = freeze_columns {
        parts.push(format!("frozenColumnCount={columns}"));
    }
    if let Some(hide) = hide_gridlines {
        parts.push(format!("hideGridlines={hide}"));
    }
    if let Some(hex) = tab_color {
        parts.push(format!("tabColorStyle={hex}"));
    } else if *clear_tab_color {
        parts.push("tabColorStyle=cleared".to_string());
    }
    if let Some(rtl) = right_to_left {
        parts.push(format!("rightToLeft={rtl}"));
    }
    if parts.is_empty() {
        return None;
    }
    Some(parts.join(", "))
}

/// Renders an outcome as human-readable text.
///
/// Joins [`describe_lines`]; see it for why the line structure, and not just
/// the finished string, is what this module produces.
#[must_use]
pub fn describe(outcome: &StructureOutcome) -> String {
    describe_lines(outcome).join("\n")
}

/// Renders an outcome as its individual lines, **none of which contains a
/// newline**.
///
/// Lives here rather than in the CLI layer so the CLI and a future MCP
/// caller describe an outcome identically.
///
/// The `WouldChange` arms are the substance of this module's answer to "what
/// does `--dry-run` show for an effect that isn't a range": the sheet's real
/// current dimensions, the resulting ones, and — for an insert — the shift
/// that no bounded range could express. That shift is a second line, which
/// is why this is the line list and `describe` the convenience over it.
///
/// Returning the lines rather than one pre-joined string is what lets the
/// CLI sanitize each one and then supply the separators itself. Every line
/// here interpolates untrusted text — a Drive-supplied file name, sheet
/// titles read out of the workbook, raw API error details — so a newline
/// arriving inside one of those values must not be able to pass for a line
/// break this module chose. Filtering a joined string cannot tell the two
/// apart; filtering the parts before joining them cannot confuse them.
/// `no_describe_line_contains_a_newline` pins the guarantee.
#[must_use]
pub fn describe_lines(outcome: &StructureOutcome) -> Vec<String> {
    let verb = &outcome.verb;
    let book = outcome.file_name.as_deref().map_or_else(
        || format!("'{}'", outcome.spreadsheet_id),
        |n| format!("'{n}'"),
    );

    match &outcome.result {
        StructureResult::WouldChange { sheet, sheet_count } => {
            describe_would_change(verb, sheet.as_deref(), *sheet_count, &book)
        }
        StructureResult::RefusedNotASpreadsheet { mime_type } => vec![format!(
            "Refused: {book} is not a Google Sheet (mimeType: {mime_type}); \
             `drive sheets {}` only works on spreadsheets",
            verb.label()
        )],
        StructureResult::RefusedShortcut => vec![format!(
            "Refused: {book} is a shortcut; `drive sheets {}` doesn't follow shortcuts — \
             resolve the target spreadsheet's id and use that instead",
            verb.label()
        )],
        StructureResult::RefusedNoVisibleParents => {
            let op = verb.gate_operation();
            vec![format!(
                "Refused: {book} has no parent folder visible to this account, so no folder \
                 rule can apply to it. This is normal for a Sheet shared by link or email. \
                 Grant it by id instead: add {{\"file_id\": \"<spreadsheet id>\", \"allow\": \
                 [\"{op}\"]}} to write_permissions.rules. (Adding it to a folder in your own \
                 Drive and granting that folder `{op}` also works.)"
            )]
        }
        StructureResult::RefusedSheetNotFound { title, available } => {
            vec![grid_range::no_sheet_refusal(&book, title, available)]
        }
        StructureResult::RefusedSheetExists { title } => {
            vec![format!(
                "Refused: {book} already has a sheet titled '{title}'"
            )]
        }
        StructureResult::RefusedInvalidRange { detail } => vec![format!("Refused: {detail}")],
        StructureResult::Blocked { decided_by } => {
            let op = verb.gate_operation();
            let action = if matches!(op, DriveOperation::SheetsDelete) {
                "destructive edits"
            } else {
                "structural edits"
            };
            vec![match decided_by {
                Some(rule) => format!(
                    "Blocked: {action} to {book} refused by rule on {} {}{}",
                    rule.kind_label(),
                    rule.id(),
                    rule.depth_suffix()
                ),
                None => format!(
                    "Blocked: {action} to {book} refused by default policy (no matching rule \
                     for {op})"
                ),
            }]
        }
        StructureResult::RefusedNoLease => LeaseGateRefusal::NoLease
            .describe_line(&outcome.spreadsheet_id, &book)
            .into_iter()
            .collect(),
        StructureResult::RefusedLeaseExpired => LeaseGateRefusal::Expired
            .describe_line(&outcome.spreadsheet_id, &book)
            .into_iter()
            .collect(),
        StructureResult::RefusedLeaseWrongFile => LeaseGateRefusal::WrongFile
            .describe_line(&outcome.spreadsheet_id, &book)
            .into_iter()
            .collect(),
        StructureResult::RefusedLeaseStale => LeaseGateRefusal::Stale
            .describe_line(&outcome.spreadsheet_id, &book)
            .into_iter()
            .collect(),
        StructureResult::Changed {
            sheet,
            sheet_id,
            backup,
        } => {
            vec![describe_changed(
                verb,
                sheet.as_deref(),
                *sheet_id,
                backup.as_deref(),
                &book,
            )]
        }
        StructureResult::Unchanged { detail } => vec![format!("Unchanged: {detail} in {book}")],
        StructureResult::Failed { detail } => vec![format!("Failed: {detail}")],
    }
}

fn describe_would_change(
    verb: &StructureVerb,
    sheet: Option<&SheetSnapshot>,
    sheet_count: usize,
    book: &str,
) -> Vec<String> {
    let id = sheet
        .and_then(|s| s.sheet_id)
        .map_or_else(String::new, |id| format!(" (sheetId {id})"));

    match verb {
        StructureVerb::AddSheet {
            title,
            index,
            rows,
            columns,
        } => {
            let size = match (rows, columns) {
                (Some(r), Some(c)) => format!(" ({r} x {c})"),
                (Some(r), None) => format!(" ({r} rows)"),
                (None, Some(c)) => format!(" ({c} columns)"),
                (None, None) => String::new(),
            };
            let position = index.map_or_else(
                || " at the end".to_string(),
                |index| format!(" at index {index}"),
            );
            vec![format!(
                "Would add sheet '{title}'{size}{position} of {book} \
                 ({sheet_count} sheet(s) -> {})",
                sheet_count + 1
            )]
        }
        StructureVerb::RenameSheet {
            sheet: from,
            new_title,
        } => {
            vec![format!(
                "Would rename sheet '{from}'{id} to '{new_title}' in {book}"
            )]
        }
        StructureVerb::InsertRows {
            sheet: from,
            at,
            count,
        } => describe_would_insert(Dimension::Rows, from, &id, *at, *count, sheet, book),
        StructureVerb::InsertColumns {
            sheet: from,
            at,
            count,
        } => describe_would_insert(Dimension::Columns, from, &id, *at, *count, sheet, book),
        StructureVerb::InsertRange {
            sheet: from,
            start_row,
            end_row,
            start_column,
            end_column,
            shift,
        } => vec![describe_would_insert_range(
            from,
            &id,
            *start_row,
            *end_row,
            *start_column,
            *end_column,
            *shift,
            book,
        )],
        StructureVerb::MoveRows {
            sheet: from,
            at,
            count,
            before,
        } => describe_would_move(
            Dimension::Rows,
            from,
            &id,
            *at,
            *count,
            *before,
            sheet,
            book,
        ),
        StructureVerb::MoveColumns {
            sheet: from,
            at,
            count,
            before,
        } => describe_would_move(
            Dimension::Columns,
            from,
            &id,
            *at,
            *count,
            *before,
            sheet,
            book,
        ),
        StructureVerb::DeleteSheet { sheet: from } => {
            vec![format!(
                "Would delete sheet '{from}'{id} from {book} ({sheet_count} sheet(s) -> {}); \
                 {FORMULA_CAVEAT}",
                sheet_count.saturating_sub(1)
            )]
        }
        StructureVerb::DeleteRows {
            sheet: from,
            at,
            count,
        } => describe_would_delete_dimension(Dimension::Rows, from, &id, *at, *count, sheet, book),
        StructureVerb::DeleteColumns {
            sheet: from,
            at,
            count,
        } => {
            describe_would_delete_dimension(Dimension::Columns, from, &id, *at, *count, sheet, book)
        }
        StructureVerb::DeleteRange {
            sheet: from,
            start_row,
            end_row,
            start_column,
            end_column,
            shift,
        } => vec![describe_would_delete_range(
            from,
            &id,
            *start_row,
            *end_row,
            *start_column,
            *end_column,
            *shift,
            book,
        )],
        StructureVerb::DuplicateSheet {
            sheet: from,
            title,
            index,
        } => {
            let to = title.as_deref().map_or_else(
                || " as a copy Sheets names automatically".to_string(),
                |title| format!(" as '{title}'"),
            );
            let position = index.map_or_else(
                // Confirmed against the live API: unlike `add-sheet`,
                // `duplicateSheetRequest` does not default to appending —
                // an omitted index lands the copy at the *front* (index 0).
                || " at the front (Sheets' default; not the end)".to_string(),
                |index| format!(" at index {index}"),
            );
            vec![format!(
                "Would duplicate sheet '{from}'{id}{to}{position} of {book} \
                 ({sheet_count} sheet(s) -> {})",
                sheet_count + 1
            )]
        }
        StructureVerb::ReorderSheet { sheet: from, index } => {
            vec![format!(
                "Would move sheet '{from}'{id} to index {index} in {book}"
            )]
        }
        StructureVerb::SetSheetVisibility {
            sheet: from,
            hidden,
        } => {
            let verb_word = if *hidden { "hide" } else { "show" };
            vec![format!("Would {verb_word} sheet '{from}'{id} in {book}")]
        }
        StructureVerb::UpdateSheetProperties {
            sheet: from,
            freeze_rows,
            freeze_columns,
            tab_color,
            clear_tab_color,
            right_to_left,
            hide_gridlines,
        } => {
            let fragments = update_sheet_properties_fragments(
                freeze_rows,
                freeze_columns,
                tab_color,
                *clear_tab_color,
                *right_to_left,
                *hide_gridlines,
                sheet,
            );
            vec![format!(
                "Would update sheet '{from}'{id} in {book}: {}",
                fragments.join(", ")
            )]
        }
        StructureVerb::UpdateWorkbookProperties { .. } => vec![format!(
            "Would update workbook properties of {book}: {}",
            workbook_properties_summary(verb)
        )],
    }
}

/// One `"<label> <before> -> <after>"` fragment, or `"<label> -> <after>"`
/// when `before` is `None` — the shape every `update-sheet-properties`
/// property reduces to (issue #1835). Shared so the four properties that
/// carry a "before" value from the snapshot can't phrase it four different
/// ways.
fn before_after_fragment(
    label: &str,
    before: Option<impl std::fmt::Display>,
    after: impl std::fmt::Display,
) -> String {
    match before {
        Some(before) => format!("{label} {before} -> {after}"),
        None => format!("{label} -> {after}"),
    }
}

/// The `hide_gridlines` before/after label: `true`/`false` read as
/// "hidden"/"shown" rather than as bare booleans.
fn gridlines_label(hidden: bool) -> &'static str {
    if hidden {
        "hidden"
    } else {
        "shown"
    }
}

/// The fragments shared by [`describe_would_change`]'s and
/// [`describe_changed`]'s `UpdateSheetProperties` arms (issue #1835) — one
/// per property the verb actually set, each stated as a before->after where
/// the snapshot knows the current value and as just the target otherwise.
/// Kept as one function so the dry-run preview and the real-run report can
/// never phrase the same effect two different ways.
fn update_sheet_properties_fragments(
    freeze_rows: &Option<i64>,
    freeze_columns: &Option<i64>,
    tab_color: &Option<String>,
    clear_tab_color: bool,
    right_to_left: Option<bool>,
    hide_gridlines: Option<bool>,
    sheet: Option<&SheetSnapshot>,
) -> Vec<String> {
    let mut fragments = Vec::new();
    if let Some(rows) = freeze_rows {
        fragments.push(before_after_fragment(
            "frozen rows",
            sheet.and_then(|s| s.frozen_row_count),
            rows,
        ));
    }
    if let Some(columns) = freeze_columns {
        fragments.push(before_after_fragment(
            "frozen columns",
            sheet.and_then(|s| s.frozen_column_count),
            columns,
        ));
    }
    if let Some(hex) = tab_color {
        fragments.push(format!("tab color -> {}", normalize_hex_for_display(hex)));
    } else if clear_tab_color {
        fragments.push("tab color cleared".to_string());
    }
    if let Some(rtl) = right_to_left {
        fragments.push(before_after_fragment(
            "right-to-left",
            sheet.and_then(|s| s.right_to_left),
            rtl,
        ));
    }
    if let Some(hide) = hide_gridlines {
        fragments.push(before_after_fragment(
            "gridlines",
            sheet.and_then(|s| s.hide_gridlines).map(gridlines_label),
            gridlines_label(hide),
        ));
    }
    fragments
}

/// The insert arms of [`describe_would_change`].
///
/// This is where a structural dry run earns its keep: it names the resulting
/// dimension *and* the shift, which is the part of the effect no bounded
/// range could express and the reason ADR-0073 §12 called this out.
// One parameter per fact the message needs (dimension, the two labels
// already formatted by the caller, the insert's own `at`/`count`, the
// target's dimensions, and the workbook name) — bundling them into a struct
// would just move the same fields one level out for a private helper with a
// single call site.
#[allow(clippy::too_many_arguments)]
fn describe_would_insert(
    dimension: Dimension,
    from: &str,
    id: &str,
    at: i64,
    count: i64,
    sheet: Option<&SheetSnapshot>,
    book: &str,
) -> Vec<String> {
    let summary = format!(
        "Would insert {count} {noun}(s) before {noun} {at} of '{from}'{id} in {book}",
        noun = dimension.noun(),
    );
    let before = match dimension {
        Dimension::Rows => sheet.and_then(|s| s.row_count),
        Dimension::Columns => sheet.and_then(|s| s.column_count),
    };
    // The shift line is the trustworthy half of a structural preview, so it
    // is omitted outright when it cannot be stated — an unknown current size,
    // or a resulting size that does not fit. A wrong number here would be
    // worse than a missing one.
    let Some(before) = before else {
        return vec![summary];
    };
    let Some(after) = before.checked_add(count) else {
        return vec![summary];
    };
    // `at > before` only at the append boundary (`at == before + 1`,
    // enforced by `validate_verb_args`): there is nothing after the last
    // row/column to shift, so "existing N-M shift" would print an inverted,
    // self-contradictory range instead of the truth.
    let existing = if at <= before {
        format!(
            "; existing {plural} {at}-{before} shift {direction}",
            plural = plural(dimension),
            // An insert always pushes the existing rows/columns forward.
            direction = shift_word(dimension, true),
        )
    } else {
        format!(
            "; appended at the end, no existing {plural} shift",
            plural = plural(dimension)
        )
    };
    vec![
        summary,
        format!(
            "  ({before} {plural} -> {after}{existing})",
            plural = plural(dimension),
        ),
    ]
}

/// The move arms of [`describe_would_change`].
///
/// Same shape and the same reason as [`describe_would_insert`]: the summary
/// names the block and its destination, and the second line names the
/// shift — which for a move is the whole point, since `--before` is numbered
/// in the sheet's *pre-move* coordinates and the block therefore does not
/// land on the number the user typed. Spelling out where the block ends up,
/// and which rows/columns slid past it, is what stops that convention being
/// a trap.
// One parameter per fact the message needs, with a single call site — see
// `describe_would_insert`'s note.
#[allow(clippy::too_many_arguments)]
fn describe_would_move(
    dimension: Dimension,
    from: &str,
    id: &str,
    at: i64,
    count: i64,
    before: i64,
    sheet: Option<&SheetSnapshot>,
    book: &str,
) -> Vec<String> {
    let Some(last) = at.checked_add(count).and_then(|end| end.checked_sub(1)) else {
        return vec![format!(
            "Would move {count} {noun}(s) from {noun} {at} of '{from}'{id} in {book}",
            noun = dimension.noun(),
        )];
    };
    let summary = format!(
        "Would move {count} {noun}(s) {at}-{last} of '{from}'{id} in {book} to before \
         {noun} {before}",
        noun = dimension.noun(),
    );
    let current = match dimension {
        Dimension::Rows => sheet.and_then(|s| s.row_count),
        Dimension::Columns => sheet.and_then(|s| s.column_count),
    };
    // The shift line is the trustworthy half of a structural preview, so it
    // is omitted outright when the current size is unknown rather than
    // guessed at — `describe_would_insert`'s rule.
    let Some(current) = current else {
        return vec![summary];
    };
    // `validate_move_bounds` refuses every `before` in `at..=at + count`, so
    // exactly one of these two branches applies. Each yields the same five
    // facts — the shifted range's old and new bounds, and which way it
    // moved — which the single `format!` below turns into the line.
    let (land_first, land_last) = move_landing_span(before, count, last);
    let (shift_first, shift_last, shifted_first, shifted_last, forward) = if before > last {
        // Downward: the rows/columns strictly between the block and the
        // destination slide back to close the gap — `count` short of the
        // number typed, which is the convention this line exists to spell
        // out.
        (last + 1, before - 1, at, before - 1 - count, false)
    } else {
        // Upward (`before < at`): the block lands exactly on the number
        // typed, and everything from there to the block's old start slides
        // forward by `count`.
        (before, at - 1, before + count, at - 1 + count, true)
    };
    let detail = format!(
        "  ({current} {plural} unchanged; {plural} {shift_first}-{shift_last} shift \
         {direction} to {shifted_first}-{shifted_last}; moved {plural} land at {land_first}-\
         {land_last})",
        plural = plural(dimension),
        direction = shift_word(dimension, forward),
    );
    vec![summary, detail]
}

/// A destructive `--dry-run` cannot check whether some formula elsewhere in
/// the workbook references what would be deleted — that would need reading
/// every other sheet's formulas, not just this verb's own target, and ADR-0077
/// keeps a destructive dry run structural-only (no extra `values.get` read,
/// no cell content in its output or the request log). This fixed caveat is
/// the honest substitute.
const FORMULA_CAVEAT: &str =
    "formulas elsewhere in the workbook that reference this may break, which cannot be \
     checked automatically";

/// Shared by [`describe_would_insert_range`] and [`describe_inserted_range`]
/// so the wording can't drift between the preview and the post-execution
/// message; tense differs (the dry run hasn't happened yet) so this is two
/// constants rather than one, unlike [`FORMULA_CAVEAT`].
const INSERT_RANGE_EDGE_CAVEAT_DRY_RUN: &str =
    "cells pushed past the sheet's grid extent may be dropped by Sheets";
const INSERT_RANGE_EDGE_CAVEAT: &str =
    "cells pushed past the sheet's grid extent may have been dropped by Sheets";

/// The `DeleteRows`/`DeleteColumns` arm of [`describe_would_change`].
///
/// Mirrors [`describe_would_insert`]'s shape (a summary line plus a shift
/// line), shrinking instead of growing and shifting the opposite direction.
/// Unlike insert, deletion has no append-boundary case — every row/column
/// named already exists — so the "nothing remains after" branch replaces
/// insert's "appended at the end" one.
#[allow(clippy::too_many_arguments)]
fn describe_would_delete_dimension(
    dimension: Dimension,
    from: &str,
    id: &str,
    at: i64,
    count: i64,
    sheet: Option<&SheetSnapshot>,
    book: &str,
) -> Vec<String> {
    let Some(last) = at.checked_add(count).and_then(|end| end.checked_sub(1)) else {
        return vec![format!(
            "Would delete {count} {noun}(s) from {noun} {at} of '{from}'{id} in {book}",
            noun = dimension.noun(),
        )];
    };
    let summary = format!(
        "Would delete {count} {noun}(s) {at}-{last} of '{from}'{id} in {book}",
        noun = dimension.noun(),
    );
    let before = match dimension {
        Dimension::Rows => sheet.and_then(|s| s.row_count),
        Dimension::Columns => sheet.and_then(|s| s.column_count),
    };
    let Some(before) = before else {
        return vec![summary];
    };
    let Some(after) = before.checked_sub(count) else {
        return vec![summary];
    };
    let existing = if last < before {
        format!(
            "; existing {plural} {next}-{before} shift {direction}",
            plural = plural(dimension),
            next = last + 1,
            direction = shift_word(dimension, false),
        )
    } else {
        format!(
            "; nothing remains after the deleted {plural}",
            plural = plural(dimension)
        )
    };
    vec![
        summary,
        format!(
            "  ({before} {plural} -> {after}{existing}; {FORMULA_CAVEAT})",
            plural = plural(dimension),
        ),
    ]
}

/// The `DeleteRange` arm of [`describe_would_change`].
///
/// `deleteRange` never changes the sheet's `rowCount`/`columnCount` — it
/// shifts cells within the same bounded grid — so unlike the dimension
/// deletes there is no "before -> after" size line to add; the rectangle and
/// shift direction already say the whole effect in one line.
#[allow(clippy::too_many_arguments)]
fn describe_would_delete_range(
    from: &str,
    id: &str,
    start_row: i64,
    end_row: i64,
    start_column: i64,
    end_column: i64,
    shift: ShiftDimension,
    book: &str,
) -> String {
    let direction = shift_word(shift.into(), false);
    format!(
        "Would delete rows {start_row}-{end_row}, columns {start_column}-{end_column} of \
         '{from}'{id} in {book}, shifting remaining cells {direction} to close the gap; \
         {FORMULA_CAVEAT}"
    )
}

/// The `InsertRange` arm of [`describe_would_change`].
#[allow(clippy::too_many_arguments)]
fn describe_would_insert_range(
    from: &str,
    id: &str,
    start_row: i64,
    end_row: i64,
    start_column: i64,
    end_column: i64,
    shift: ShiftDimension,
    book: &str,
) -> String {
    let direction = shift_word(shift.into(), true);
    format!(
        "Would insert empty cells at rows {start_row}-{end_row}, columns {start_column}-{end_column} \
         of '{from}'{id} in {book}, shifting existing cells {direction}; \
         {INSERT_RANGE_EDGE_CAVEAT_DRY_RUN}"
    )
}

fn describe_changed(
    verb: &StructureVerb,
    sheet: Option<&SheetSnapshot>,
    sheet_id: Option<i64>,
    backup: Option<&LeaseBackup>,
    book: &str,
) -> String {
    let id = sheet_id.map_or_else(String::new, |id| format!(" (sheetId {id})"));
    let recovery = recovery_note(backup, matches!(verb, StructureVerb::DeleteSheet { .. }));
    match verb {
        StructureVerb::AddSheet { title, .. } => {
            format!("Added sheet '{title}'{id} to {book}")
        }
        StructureVerb::RenameSheet {
            sheet: from,
            new_title,
        } => {
            format!("Renamed sheet '{from}' to '{new_title}'{id} in {book}")
        }
        StructureVerb::InsertRows {
            sheet: from,
            at,
            count,
        } => describe_inserted(Dimension::Rows, from, &id, *at, *count, sheet, book),
        StructureVerb::InsertColumns {
            sheet: from,
            at,
            count,
        } => describe_inserted(Dimension::Columns, from, &id, *at, *count, sheet, book),
        StructureVerb::InsertRange {
            sheet: from,
            start_row,
            end_row,
            start_column,
            end_column,
            shift,
        } => describe_inserted_range(
            from,
            &id,
            *start_row,
            *end_row,
            *start_column,
            *end_column,
            *shift,
            book,
        ),
        StructureVerb::MoveRows {
            sheet: from,
            at,
            count,
            before,
        } => describe_moved(Dimension::Rows, from, &id, *at, *count, *before, book),
        StructureVerb::MoveColumns {
            sheet: from,
            at,
            count,
            before,
        } => describe_moved(Dimension::Columns, from, &id, *at, *count, *before, book),
        StructureVerb::DeleteSheet { sheet: from } => {
            format!("Deleted sheet '{from}'{id} from {book}; {recovery}")
        }
        StructureVerb::DeleteRows {
            sheet: from,
            at,
            count,
        } => describe_deleted_dimension(
            Dimension::Rows,
            from,
            &id,
            *at,
            *count,
            sheet,
            book,
            &recovery,
        ),
        StructureVerb::DeleteColumns {
            sheet: from,
            at,
            count,
        } => describe_deleted_dimension(
            Dimension::Columns,
            from,
            &id,
            *at,
            *count,
            sheet,
            book,
            &recovery,
        ),
        StructureVerb::DeleteRange {
            sheet: from,
            start_row,
            end_row,
            start_column,
            end_column,
            shift,
        } => describe_deleted_range(
            from,
            &id,
            *start_row,
            *end_row,
            *start_column,
            *end_column,
            *shift,
            book,
            &recovery,
        ),
        StructureVerb::DuplicateSheet {
            sheet: from, title, ..
        } => {
            let to = title
                .as_deref()
                .map_or_else(String::new, |title| format!(" as '{title}'"));
            format!("Duplicated sheet '{from}'{to}{id} in {book}")
        }
        StructureVerb::ReorderSheet { sheet: from, index } => {
            format!("Moved sheet '{from}'{id} to index {index} in {book}")
        }
        StructureVerb::SetSheetVisibility {
            sheet: from,
            hidden,
        } => {
            let verb_word = if *hidden { "Hid" } else { "Showed" };
            format!("{verb_word} sheet '{from}'{id} in {book}")
        }
        StructureVerb::UpdateSheetProperties {
            sheet: from,
            freeze_rows,
            freeze_columns,
            tab_color,
            clear_tab_color,
            right_to_left,
            hide_gridlines,
        } => {
            let fragments = update_sheet_properties_fragments(
                freeze_rows,
                freeze_columns,
                tab_color,
                *clear_tab_color,
                *right_to_left,
                *hide_gridlines,
                sheet,
            );
            format!(
                "Updated sheet '{from}'{id} in {book}: {}",
                fragments.join(", ")
            )
        }
        StructureVerb::UpdateWorkbookProperties { .. } => format!(
            "Updated workbook properties of {book}: {}",
            workbook_properties_summary(verb)
        ),
    }
}

/// The insert arms of [`describe_changed`].
// Same shape as `describe_would_insert`, for the same reason: one parameter
// per fact the message needs, with a single call site.
#[allow(clippy::too_many_arguments)]
fn describe_inserted(
    dimension: Dimension,
    from: &str,
    id: &str,
    at: i64,
    count: i64,
    sheet: Option<&SheetSnapshot>,
    book: &str,
) -> String {
    let now = match dimension {
        Dimension::Rows => sheet.and_then(|s| s.row_count),
        Dimension::Columns => sheet.and_then(|s| s.column_count),
    }
    .and_then(|before| before.checked_add(count))
    .map_or_else(String::new, |after| {
        format!(" ({after} {} now)", plural(dimension))
    });
    format!(
        "Inserted {count} {noun}(s) before {noun} {at} of '{from}'{id} in {book}{now}",
        noun = dimension.noun(),
    )
}

/// The move arms of [`describe_changed`].
///
/// One line, like [`describe_inserted`], but it still names the landing
/// span: `--before` is pre-move numbering, so "moved rows 2-3 to before row
/// 6" alone would leave the reader to redo the arithmetic that
/// [`describe_would_move`] already does for the preview. It takes no
/// [`SheetSnapshot`], unlike every other `describe_*` helper here: a move
/// changes neither the row nor the column count, so there is no "now N
/// rows" tail the sheet's dimensions could supply — the landing span is
/// determined by the block's own numbers alone.
fn describe_moved(
    dimension: Dimension,
    from: &str,
    id: &str,
    at: i64,
    count: i64,
    before: i64,
    book: &str,
) -> String {
    let last = at.checked_add(count).and_then(|end| end.checked_sub(1));
    let range = last.map_or_else(|| at.to_string(), |last| format!("{at}-{last}"));
    let now = last.map_or_else(String::new, |last| {
        let (land_first, land_last) = move_landing_span(before, count, last);
        format!(" (now {} {land_first}-{land_last})", plural(dimension))
    });
    format!(
        "Moved {count} {noun}(s) {range} of '{from}'{id} in {book} to before {noun} \
         {before}{now}",
        noun = dimension.noun(),
    )
}

/// The `DeleteRows`/`DeleteColumns` arm of [`describe_changed`].
#[allow(clippy::too_many_arguments)]
fn describe_deleted_dimension(
    dimension: Dimension,
    from: &str,
    id: &str,
    at: i64,
    count: i64,
    sheet: Option<&SheetSnapshot>,
    book: &str,
    recovery: &str,
) -> String {
    let last = at.checked_add(count).and_then(|end| end.checked_sub(1));
    let range = last.map_or_else(|| at.to_string(), |last| format!("{at}-{last}"));
    let now = match dimension {
        Dimension::Rows => sheet.and_then(|s| s.row_count),
        Dimension::Columns => sheet.and_then(|s| s.column_count),
    }
    .and_then(|before| before.checked_sub(count))
    .map_or_else(String::new, |after| {
        format!(" ({after} {} now)", plural(dimension))
    });
    format!(
        "Deleted {count} {noun}(s) {range} of '{from}'{id} in {book}{now}; {recovery}",
        noun = dimension.noun(),
    )
}

/// The `DeleteRange` arm of [`describe_changed`].
#[allow(clippy::too_many_arguments)]
fn describe_deleted_range(
    from: &str,
    id: &str,
    start_row: i64,
    end_row: i64,
    start_column: i64,
    end_column: i64,
    shift: ShiftDimension,
    book: &str,
    recovery: &str,
) -> String {
    let direction = shift_word(shift.into(), false);
    format!(
        "Deleted rows {start_row}-{end_row}, columns {start_column}-{end_column} of '{from}'{id} \
         in {book}, shifted remaining cells {direction}; {recovery}"
    )
}

/// The `InsertRange` arm of [`describe_changed`].
#[allow(clippy::too_many_arguments)]
fn describe_inserted_range(
    from: &str,
    id: &str,
    start_row: i64,
    end_row: i64,
    start_column: i64,
    end_column: i64,
    shift: ShiftDimension,
    book: &str,
) -> String {
    let direction = shift_word(shift.into(), true);
    format!(
        "Inserted empty cells at rows {start_row}-{end_row}, columns {start_column}-{end_column} \
         of '{from}'{id} in {book}, shifting existing cells {direction}; \
         {INSERT_RANGE_EDGE_CAVEAT}"
    )
}

const fn plural(dimension: Dimension) -> &'static str {
    match dimension {
        Dimension::Rows => "rows",
        Dimension::Columns => "columns",
    }
}

/// The direction word for a shift along `dimension`: `forward` is the
/// direction rows/columns move when something is inserted or a block moves
/// upward past them (`down`/`right`); the other way (a downward move's
/// displaced rows/columns closing the gap, or a deletion closing the gap
/// left behind) is `!forward` (`up`/`left`). Shared by every `describe_*`
/// preview/post-execution message in this module (insert, move, delete
/// dimension, delete/insert range) so the direction vocabulary can't drift
/// apart between them.
const fn shift_word(dimension: Dimension, forward: bool) -> &'static str {
    match (dimension, forward) {
        (Dimension::Rows, true) => "down",
        (Dimension::Rows, false) => "up",
        (Dimension::Columns, true) => "right",
        (Dimension::Columns, false) => "left",
    }
}

#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::expect_used)]
mod tests {
    use super::*;
    use crate::drive::auth::{DriveCredentials, DriveGrantedScopes};
    use crate::drive::sheets::client::SHEETS_API_URL;
    use crate::drive::test_support::{seed_lease, seed_lease_with_backup};
    use crate::drive::types::GOOGLE_SHEET_MIME_TYPE;
    use crate::drive::write_gate::Verdict;
    use crate::test_support::env::MapEnv;
    use crate::utils::secret::Secret;
    use std::collections::HashSet;

    fn test_credentials() -> DriveCredentials {
        DriveCredentials {
            client_id: "client-1".to_string(),
            client_secret: Secret::new("secret-1"),
            refresh_token: Secret::new("refresh-1"),
            scope: DriveGrantedScopes::READONLY,
        }
    }

    /// Both clients against one wiremock server, sharing an OAuth session.
    ///
    /// `replace_session` must run before the derive: it swaps the Drive
    /// client's whole transport, so deriving first would leave the Sheets
    /// client pointed at the real `oauth2.googleapis.com`.
    async fn clients(server: &wiremock::MockServer) -> (DriveClient, SheetsClient) {
        wiremock::Mock::given(wiremock::matchers::method("POST"))
            .and(wiremock::matchers::path("/token"))
            .respond_with(
                wiremock::ResponseTemplate::new(200).set_body_json(serde_json::json!({
                    "access_token": "test-token", "expires_in": 3600,
                })),
            )
            .mount(server)
            .await;
        let mut drive = DriveClient::new(&server.uri(), &test_credentials()).unwrap();
        crate::drive::client::test_support::replace_session(
            &mut drive,
            &test_credentials(),
            &format!("{}/token", server.uri()),
        );
        let env = MapEnv::new().with(SHEETS_API_URL, &server.uri());
        let sheets = SheetsClient::from_drive_client_with(&env, &drive).unwrap();
        (drive, sheets)
    }

    /// `version: "1"` throughout — matches [`opts`]'s default seeded
    /// lease, so any test reaching the mutating call has a live, non-stale
    /// lease by construction (ADR-0080 §9).
    fn mount_file(id: &str, mime_type: &str, parents: &[&str]) -> wiremock::Mock {
        let parents: Vec<&str> = parents.to_vec();
        wiremock::Mock::given(wiremock::matchers::method("GET"))
            .and(wiremock::matchers::path(format!("/drive/v3/files/{id}")))
            .respond_with(
                wiremock::ResponseTemplate::new(200).set_body_json(serde_json::json!({
                    "id": id, "name": id, "mimeType": mime_type, "parents": parents,
                    "version": "1",
                })),
            )
    }

    fn mount_folder(id: &str) -> wiremock::Mock {
        mount_file(id, "application/vnd.google-apps.folder", &[])
    }

    fn allow_rule(folder: &str) -> FolderPermissionRule {
        FolderPermissionRule {
            folder_id: Some(folder.to_string()),
            file_id: None,
            recursive: true,
            allow: std::iter::once(DriveOperation::SheetsStructure).collect(),
            deny: HashSet::default(),
            require_lease: true,
        }
    }

    /// The `spreadsheets.get` reply body shared by [`mount_workbook`] and
    /// its variants: `Q1` (1000 x 26) fixed, plus whatever `Q2` object the
    /// caller supplies — the one thing every variant actually varies.
    fn workbook_body(q2: serde_json::Value) -> serde_json::Value {
        serde_json::json!({
            "spreadsheetId": "sheet-1",
            "properties": {"title": "Budget"},
            "sheets": [
                {"properties": {
                    "sheetId": 0, "title": "Q1", "index": 0,
                    "gridProperties": {"rowCount": 1000, "columnCount": 26}}},
                q2,
            ],
        })
    }

    /// The `Q2` sheet object [`mount_workbook`] mounts: 500 x 10, no extra
    /// properties.
    fn default_q2() -> serde_json::Value {
        serde_json::json!({"properties": {
            "sheetId": 118_293, "title": "Q2", "index": 1,
            "gridProperties": {"rowCount": 500, "columnCount": 10}}})
    }

    /// [`default_q2`], but hidden — what `show-sheet` needs to have
    /// something to show.
    fn hidden_q2() -> serde_json::Value {
        serde_json::json!({"properties": {
            "sheetId": 118_293, "title": "Q2", "index": 1, "hidden": true,
            "gridProperties": {"rowCount": 500, "columnCount": 10}}})
    }

    /// A `spreadsheets.get` reply with two sheets, `Q1` (1000 x 26) and
    /// `Q2` (500 x 10).
    fn mount_workbook() -> wiremock::Mock {
        mount_workbook_with_q2(default_q2())
    }

    fn mount_batch_update(body: serde_json::Value) -> wiremock::Mock {
        wiremock::Mock::given(wiremock::matchers::method("POST"))
            .and(wiremock::matchers::path(
                "/v4/spreadsheets/sheet-1:batchUpdate",
            ))
            .respond_with(wiremock::ResponseTemplate::new(200).set_body_json(body))
    }

    /// Seeds a fresh, isolated ledger with a live lease for `"sheet-1"` at
    /// version `"1"` (matching [`mount_file`]'s default) and returns
    /// options carrying it. Every existing test built before the lease
    /// (ADR-0080 §9) reaches its mutating call this way by construction —
    /// see [`opts_for`]'s doc comment for why this doesn't need touching
    /// each test individually. A test exercising the lease *refusal* paths
    /// builds `StructureOptions` directly instead (see the
    /// "the Drive write lease" test section below).
    fn opts(verb: StructureVerb, dry_run: bool) -> StructureOptions {
        opts_for("sheet-1", verb, dry_run)
    }

    /// [`opts`], generalised over the spreadsheet id.
    ///
    /// The backing ledger directory is deliberately leaked (`into_path`,
    /// not dropped) rather than threaded through every caller as a
    /// `tempfile::TempDir` binding: it must outlive the `.await` on
    /// `structure(...)`, and plumbing that lifetime through several dozen
    /// pre-existing tests — none of which are *about* the lease — would
    /// dwarf the fix in size for no reviewing benefit. The leak costs a
    /// few bytes of `/tmp` per test process, cleaned up by the OS.
    fn opts_for(spreadsheet_id: &str, verb: StructureVerb, dry_run: bool) -> StructureOptions {
        let ledger_path = tempfile::tempdir()
            .unwrap()
            .keep()
            .join("lease-ledger.jsonl");
        let token = seed_lease(&ledger_path, spreadsheet_id, "1");
        StructureOptions {
            spreadsheet_id: spreadsheet_id.to_string(),
            verb,
            dry_run,
            lease_token: Some(token),
            ledger_path,
        }
    }

    fn rename() -> StructureVerb {
        StructureVerb::RenameSheet {
            sheet: "Q2".to_string(),
            new_title: "Q3".to_string(),
        }
    }

    fn insert_rows() -> StructureVerb {
        StructureVerb::InsertRows {
            sheet: "Q2".to_string(),
            at: 5,
            count: 3,
        }
    }

    /// Rows 2-3 of `Q2` moved to before row 6 — a downward move, the case
    /// where `--before`'s pre-move numbering and the block's landing
    /// position differ.
    fn move_rows() -> StructureVerb {
        StructureVerb::MoveRows {
            sheet: "Q2".to_string(),
            at: 2,
            count: 2,
            before: 6,
        }
    }

    fn add_sheet() -> StructureVerb {
        StructureVerb::AddSheet {
            title: "Q3".to_string(),
            index: None,
            rows: None,
            columns: None,
        }
    }

    fn delete_sheet() -> StructureVerb {
        StructureVerb::DeleteSheet {
            sheet: "Q2".to_string(),
        }
    }

    fn delete_rows() -> StructureVerb {
        StructureVerb::DeleteRows {
            sheet: "Q2".to_string(),
            at: 5,
            count: 3,
        }
    }

    fn delete_columns() -> StructureVerb {
        StructureVerb::DeleteColumns {
            sheet: "Q2".to_string(),
            at: 3,
            count: 2,
        }
    }

    fn insert_range() -> StructureVerb {
        StructureVerb::InsertRange {
            sheet: "Q2".to_string(),
            start_row: 2,
            end_row: 4,
            start_column: 2,
            end_column: 3,
            shift: ShiftDimension::Rows,
        }
    }

    /// [`insert_range`]'s twin with the other shift axis, so the `COLUMNS`
    /// wire value and "shift ... right" wording get exercised too — `Rows`
    /// is otherwise the only [`ShiftDimension`] any test ever names, mirroring
    /// [`delete_range_columns_shift`].
    fn insert_range_columns_shift() -> StructureVerb {
        StructureVerb::InsertRange {
            sheet: "Q2".to_string(),
            start_row: 2,
            end_row: 4,
            start_column: 2,
            end_column: 3,
            shift: ShiftDimension::Columns,
        }
    }

    fn delete_range() -> StructureVerb {
        StructureVerb::DeleteRange {
            sheet: "Q2".to_string(),
            start_row: 2,
            end_row: 4,
            start_column: 2,
            end_column: 3,
            shift: ShiftDimension::Rows,
        }
    }

    /// [`delete_range`]'s twin with the other shift axis, so the `COLUMNS`
    /// wire value and "shift ... left" wording get exercised too — `Rows` is
    /// otherwise the only [`ShiftDimension`] any test ever names.
    fn delete_range_columns_shift() -> StructureVerb {
        StructureVerb::DeleteRange {
            sheet: "Q2".to_string(),
            start_row: 2,
            end_row: 4,
            start_column: 2,
            end_column: 3,
            shift: ShiftDimension::Columns,
        }
    }

    fn duplicate_sheet() -> StructureVerb {
        StructureVerb::DuplicateSheet {
            sheet: "Q2".to_string(),
            title: Some("Q2 Copy".to_string()),
            index: Some(1),
        }
    }

    fn duplicate_sheet_default() -> StructureVerb {
        StructureVerb::DuplicateSheet {
            sheet: "Q2".to_string(),
            title: None,
            index: None,
        }
    }

    fn reorder_sheet() -> StructureVerb {
        StructureVerb::ReorderSheet {
            sheet: "Q2".to_string(),
            index: 0,
        }
    }

    fn hide_sheet() -> StructureVerb {
        StructureVerb::SetSheetVisibility {
            sheet: "Q2".to_string(),
            hidden: true,
        }
    }

    fn show_sheet() -> StructureVerb {
        StructureVerb::SetSheetVisibility {
            sheet: "Q2".to_string(),
            hidden: false,
        }
    }

    fn update_workbook_properties() -> StructureVerb {
        StructureVerb::UpdateWorkbookProperties {
            locale: Some("en_US".to_string()),
            time_zone: Some("America/New_York".to_string()),
            auto_recalc: Some(RecalculationInterval::OnChange),
            iterative_calculation: None,
            iterative_calculation_max_iterations: None,
            iterative_calculation_convergence_threshold: None,
        }
    }

    fn delete_allow_rule(folder: &str) -> FolderPermissionRule {
        FolderPermissionRule {
            folder_id: Some(folder.to_string()),
            file_id: None,
            recursive: true,
            allow: std::iter::once(DriveOperation::SheetsDelete).collect(),
            deny: HashSet::default(),
            require_lease: true,
        }
    }

    // ── the safety property this module now enforces ───────────────────
    //
    // ADR-0075 §3/§4 kept every destructive `batchUpdate` request
    // unreachable at the type level, pinned by a
    // `no_destructive_request_is_reachable` grep-guard test. ADR-0077
    // (issue #1623) supersedes that: the requests are now reachable, but
    // only through `StructureVerb::gate_operation` routing them to
    // `DriveOperation::SheetsDelete` — never `SheetsStructure`, and never
    // through a raw passthrough (there still isn't one). The tests below are
    // what replace the old grep-guard: they pin the *new* invariant instead
    // of the old absence.

    #[test]
    fn every_delete_verb_gates_on_sheets_delete_not_sheets_structure() {
        for verb in [
            StructureVerb::DeleteSheet {
                sheet: "Q1".to_string(),
            },
            StructureVerb::DeleteRows {
                sheet: "Q1".to_string(),
                at: 1,
                count: 1,
            },
            StructureVerb::DeleteColumns {
                sheet: "Q1".to_string(),
                at: 1,
                count: 1,
            },
            StructureVerb::DeleteRange {
                sheet: "Q1".to_string(),
                start_row: 1,
                end_row: 2,
                start_column: 1,
                end_column: 2,
                shift: ShiftDimension::Rows,
            },
        ] {
            assert_eq!(verb.gate_operation(), DriveOperation::SheetsDelete);
        }
    }

    #[test]
    fn every_additive_verb_still_gates_on_sheets_structure() {
        for verb in [
            add_sheet(),
            StructureVerb::RenameSheet {
                sheet: "Q1".to_string(),
                new_title: "Q2".to_string(),
            },
            StructureVerb::InsertRows {
                sheet: "Q1".to_string(),
                at: 1,
                count: 1,
            },
            StructureVerb::InsertColumns {
                sheet: "Q1".to_string(),
                at: 1,
                count: 1,
            },
            StructureVerb::InsertRange {
                sheet: "Q1".to_string(),
                start_row: 1,
                end_row: 2,
                start_column: 1,
                end_column: 2,
                shift: ShiftDimension::Rows,
            },
            StructureVerb::MoveRows {
                sheet: "Q1".to_string(),
                at: 1,
                count: 1,
                before: 3,
            },
            StructureVerb::MoveColumns {
                sheet: "Q1".to_string(),
                at: 1,
                count: 1,
                before: 3,
            },
            StructureVerb::DuplicateSheet {
                sheet: "Q1".to_string(),
                title: None,
                index: None,
            },
            StructureVerb::ReorderSheet {
                sheet: "Q1".to_string(),
                index: 0,
            },
            StructureVerb::SetSheetVisibility {
                sheet: "Q1".to_string(),
                hidden: true,
            },
            StructureVerb::UpdateSheetProperties {
                sheet: "Q1".to_string(),
                freeze_rows: None,
                freeze_columns: None,
                tab_color: None,
                clear_tab_color: false,
                right_to_left: Some(true),
                hide_gridlines: None,
            },
            StructureVerb::UpdateWorkbookProperties {
                locale: Some("en_US".to_string()),
                time_zone: None,
                auto_recalc: None,
                iterative_calculation: None,
                iterative_calculation_max_iterations: None,
                iterative_calculation_convergence_threshold: None,
            },
        ] {
            assert_eq!(verb.gate_operation(), DriveOperation::SheetsStructure);
        }
    }

    // ── the 1-based/0-based conversion, the obvious off-by-one ─────────

    #[test]
    fn at_is_one_based_inclusive_and_becomes_zero_based_half_open() {
        // "insert 3 rows before row 5" == indices [4, 7).
        let range = dimension_range(7, Dimension::Rows, 5, 3);
        assert_eq!(range.start_index, 4);
        assert_eq!(range.end_index, 7);
        assert_eq!(range.sheet_id, 7);
        assert_eq!(range.dimension, Dimension::Rows);
    }

    #[test]
    fn inserting_at_row_one_starts_at_index_zero() {
        // The boundary case, and the reason `inherit_from_before` is fixed
        // at false: the API rejects `true` when start_index is 0.
        let range = dimension_range(0, Dimension::Rows, 1, 1);
        assert_eq!(range.start_index, 0);
        assert_eq!(range.end_index, 1);
    }

    #[test]
    fn a_single_insert_spans_exactly_one_index() {
        let range = dimension_range(0, Dimension::Columns, 3, 1);
        assert_eq!((range.start_index, range.end_index), (2, 3));
    }

    #[test]
    fn dimension_range_label_is_one_based_inclusive_like_the_flag() {
        // Insert 3 rows at row 5 => rows 5, 6, 7 are the new ones.
        assert_eq!(
            dimension_range_label(&insert_rows()).as_deref(),
            Some("ROWS 5:7")
        );
        assert_eq!(
            dimension_range_label(&StructureVerb::InsertColumns {
                sheet: "Q2".to_string(),
                at: 2,
                count: 1,
            })
            .as_deref(),
            Some("COLUMNS 2:2")
        );
        // Verbs that span no dimension record none.
        assert_eq!(dimension_range_label(&rename()), None);
        assert_eq!(dimension_range_label(&add_sheet()), None);
    }

    #[test]
    fn dimension_range_label_omits_a_span_it_cannot_compute() {
        // `record_attempt` logs attempts, refused ones included, so this is
        // reached with arguments no validation let through. An uncomputable
        // span is omitted rather than recorded inverted — the omit-if-absent
        // log key already expresses "no span", and the refusal's own detail
        // carries the numbers.
        for (at, count) in [(i64::MAX, 5), (1, i64::MIN), (-1, i64::MIN)] {
            assert_eq!(
                dimension_range_label(&StructureVerb::InsertRows {
                    sheet: "Q2".to_string(),
                    at,
                    count,
                }),
                None,
                "--at {at} --count {count} must not produce a span"
            );
        }
    }

    // ── refusals that must precede the gate and the network ────────────

    #[tokio::test]
    async fn non_spreadsheet_is_refused_before_any_gate_or_sheets_call() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", "application/pdf", &["parent-1"])
            .mount(&server)
            .await;
        // No mock for parent-1 (the gate never runs) and none for any Sheets
        // endpoint, even though the rule below would otherwise permit this.
        let outcome = structure(
            &drive,
            &sheets,
            &opts(rename(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(
            outcome.result,
            StructureResult::RefusedNotASpreadsheet { .. }
        ));
        let text = describe(&outcome);
        assert!(text.contains("is not a Google Sheet"), "{text}");
        assert!(text.contains("drive sheets rename-sheet"), "{text}");
    }

    #[tokio::test]
    async fn shortcut_is_refused_with_its_own_message() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file(
            "sheet-1",
            "application/vnd.google-apps.shortcut",
            &["parent-1"],
        )
        .mount(&server)
        .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(rename(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::RefusedShortcut));
        let text = describe(&outcome);
        assert!(text.contains("is a shortcut"), "{text}");
    }

    #[tokio::test]
    async fn a_sheet_with_no_visible_parents_is_refused_distinctly_from_blocked() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &[])
            .mount(&server)
            .await;
        let outcome = structure(&drive, &sheets, &opts(rename(), false), &[]).await;
        assert!(matches!(
            outcome.result,
            StructureResult::RefusedNoVisibleParents
        ));
        let text = describe(&outcome);
        assert!(text.contains("no parent folder visible"), "{text}");
        // Names the operation the operator would have to grant, so the
        // message is actionable rather than merely accurate.
        assert!(text.contains("sheets-structure"), "{text}");
    }

    /// The same message for a delete verb must name `sheets-delete`, not
    /// `sheets-structure` — suggesting the wrong operation here would send an
    /// operator to grant a capability that does not cover what they asked
    /// for.
    #[tokio::test]
    async fn a_delete_verbs_no_visible_parents_message_names_sheets_delete() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &[])
            .mount(&server)
            .await;
        let outcome = structure(&drive, &sheets, &opts(delete_sheet(), false), &[]).await;
        let text = describe(&outcome);
        assert!(text.contains("sheets-delete"), "{text}");
        assert!(!text.contains("sheets-structure"), "{text}");
    }

    // ── the gate ───────────────────────────────────────────────────────

    #[tokio::test]
    async fn denied_target_makes_zero_sheets_calls() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        // Deliberately no `spreadsheets.get` mock and no `batchUpdate` mock:
        // a blocked attempt must not reach the Sheets API at all, which is
        // what keeps a refusal exactly as auditable as a success.
        let outcome = structure(&drive, &sheets, &opts(rename(), false), &[]).await;
        assert!(matches!(
            outcome.result,
            StructureResult::Blocked { decided_by: None }
        ));
        let text = describe(&outcome);
        assert!(text.contains("default policy"), "{text}");
    }

    #[tokio::test]
    async fn a_blocked_delete_names_destructive_edits_and_sheets_delete() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        let outcome = structure(&drive, &sheets, &opts(delete_sheet(), false), &[]).await;
        assert!(matches!(
            outcome.result,
            StructureResult::Blocked { decided_by: None }
        ));
        let text = describe(&outcome);
        assert!(text.contains("destructive edits"), "{text}");
        assert!(text.contains("default policy"), "{text}");
        assert!(text.contains("sheets-delete"), "{text}");
        assert!(!text.contains("structural edits"), "{text}");
    }

    #[tokio::test]
    async fn a_sheets_write_rule_alone_does_not_permit_a_structural_edit() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        // The non-widening property, observed end to end rather than only in
        // the gate's unit tests: a folder granted cell writes must not gain
        // the power to restructure the workbook.
        let rules = [FolderPermissionRule {
            folder_id: Some("parent-1".to_string()),
            file_id: None,
            recursive: true,
            allow: std::iter::once(DriveOperation::SheetsWrite).collect(),
            deny: HashSet::default(),
            require_lease: true,
        }];
        let outcome = structure(&drive, &sheets, &opts(rename(), false), &rules).await;
        assert!(matches!(outcome.result, StructureResult::Blocked { .. }));
    }

    /// The property ADR-0077 exists to protect: a folder granted
    /// `sheets-structure` before deletion existed must not silently gain the
    /// power to destroy data now that it does.
    #[tokio::test]
    async fn a_sheets_structure_rule_alone_does_not_permit_deletion() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        let rules = [allow_rule("parent-1")]; // grants SheetsStructure only
        for verb in [delete_sheet(), delete_rows(), delete_range()] {
            let outcome = structure(&drive, &sheets, &opts(verb, false), &rules).await;
            assert!(matches!(outcome.result, StructureResult::Blocked { .. }));
        }
    }

    /// The converse: `sheets-delete` must not grant the additive verbs
    /// either — the two operations are siblings, not a hierarchy.
    #[tokio::test]
    async fn a_sheets_delete_rule_alone_does_not_permit_a_structural_edit() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        let rules = [delete_allow_rule("parent-1")];
        let outcome = structure(&drive, &sheets, &opts(rename(), false), &rules).await;
        assert!(matches!(outcome.result, StructureResult::Blocked { .. }));
    }

    #[tokio::test]
    async fn an_explicit_deny_is_reported_with_the_deciding_rule() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        let rules = [FolderPermissionRule {
            folder_id: Some("parent-1".to_string()),
            file_id: None,
            recursive: true,
            allow: HashSet::default(),
            deny: std::iter::once(DriveOperation::SheetsStructure).collect(),
            require_lease: true,
        }];
        let outcome = structure(&drive, &sheets, &opts(rename(), false), &rules).await;
        let StructureResult::Blocked { decided_by } = &outcome.result else {
            panic!("expected Blocked, got {:?}", outcome.result);
        };
        let rule = decided_by.as_ref().expect("an explicit rule decided this");
        assert_eq!(rule.kind_label(), "folder");
        assert_eq!(rule.id(), "parent-1");
        assert_eq!(rule.depth_suffix(), " (depth 0)");
    }

    #[tokio::test]
    async fn ancestor_chain_fetch_failure_produces_failed_not_allow() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        wiremock::Mock::given(wiremock::matchers::method("GET"))
            .and(wiremock::matchers::path("/drive/v3/files/parent-1"))
            .respond_with(wiremock::ResponseTemplate::new(500))
            .mount(&server)
            .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(rename(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Failed { .. }));
    }

    // ── --dry-run ──────────────────────────────────────────────────────

    /// A dry run must never issue `batchUpdate`.
    ///
    /// It *does* issue one `spreadsheets.get` — deliberately, and unlike
    /// `sheets write`'s dry run, which touches Sheets not at all. Describing
    /// a structural effect honestly needs the sheet's real dimensions, and a
    /// read is not a mutation. The absent `batchUpdate` mock is what proves
    /// the distinction: wiremock fails an unmatched request.
    #[tokio::test]
    async fn dry_run_reads_the_workbook_but_never_calls_batch_update() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().expect(1).mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(insert_rows(), true),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(
            outcome.result,
            StructureResult::WouldChange { .. }
        ));
    }

    #[tokio::test]
    async fn dry_run_names_the_resulting_dimensions_and_the_shift() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(insert_rows(), true),
            &[allow_rule("parent-1")],
        )
        .await;
        let text = describe(&outcome);
        // The answer to "what does --dry-run show when the effect isn't a
        // range": the real before/after, plus the shift a range can't express.
        assert!(
            text.contains("Would insert 3 row(s) before row 5"),
            "{text}"
        );
        assert!(text.contains("500 rows -> 503"), "{text}");
        assert!(text.contains("shift down"), "{text}");
        assert!(text.contains("sheetId 118293"), "{text}");
    }

    /// A destructive dry run must never issue `batchUpdate` either, and stays
    /// structural-only (ADR-0077): no `values.get`, no cell content, just the
    /// same single `spreadsheets.get` an additive dry run already issues.
    #[tokio::test]
    async fn dry_run_never_calls_batch_update_for_a_delete_verb() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        for verb in [delete_sheet(), delete_rows(), delete_range()] {
            let outcome = structure(
                &drive,
                &sheets,
                &opts(verb, true),
                &[delete_allow_rule("parent-1")],
            )
            .await;
            assert!(matches!(
                outcome.result,
                StructureResult::WouldChange { .. }
            ));
        }
    }

    #[tokio::test]
    async fn dry_run_names_the_deleted_dimensions_and_the_shift_plus_the_caveat() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(delete_rows(), true),
            &[delete_allow_rule("parent-1")],
        )
        .await;
        let text = describe(&outcome);
        assert!(text.contains("Would delete 3 row(s) 5-7"), "{text}");
        assert!(text.contains("500 rows -> 497"), "{text}");
        assert!(text.contains("shift up"), "{text}");
        assert!(
            text.contains("formulas elsewhere in the workbook"),
            "{text}"
        );
    }

    #[tokio::test]
    async fn dry_run_names_the_deleted_sheet_and_the_caveat() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(delete_sheet(), true),
            &[delete_allow_rule("parent-1")],
        )
        .await;
        let text = describe(&outcome);
        assert!(text.contains("Would delete sheet 'Q2'"), "{text}");
        assert!(text.contains("2 sheet(s) -> 1"), "{text}");
        assert!(
            text.contains("formulas elsewhere in the workbook"),
            "{text}"
        );
    }

    #[tokio::test]
    async fn dry_run_names_the_deleted_range_and_the_shift() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(delete_range(), true),
            &[delete_allow_rule("parent-1")],
        )
        .await;
        let text = describe(&outcome);
        assert!(
            text.contains("Would delete rows 2-4, columns 2-3"),
            "{text}"
        );
        assert!(text.contains("shifting remaining cells up"), "{text}");
    }

    #[tokio::test]
    async fn dry_run_surfaces_the_same_blocked_reasoning_as_a_real_denied_run() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        // The gate precedes the dry-run early return, so a preview of a
        // denied edit reports the denial rather than a rosy preview.
        let dry = structure(&drive, &sheets, &opts(rename(), true), &[]).await;
        let wet = structure(&drive, &sheets, &opts(rename(), false), &[]).await;
        assert_eq!(dry.result, wet.result);
        assert!(matches!(dry.result, StructureResult::Blocked { .. }));
    }

    // ── resolving the target sheet ─────────────────────────────────────

    #[tokio::test]
    async fn a_missing_sheet_is_refused_and_lists_what_does_exist() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let verb = StructureVerb::RenameSheet {
            sheet: "Nope".to_string(),
            new_title: "Q3".to_string(),
        };
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb.clone(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(
            outcome.result,
            StructureResult::RefusedSheetNotFound { .. }
        ));
        let text = describe(&outcome);
        assert!(text.contains("no sheet titled 'Nope'"), "{text}");
        assert!(text.contains("'Q1'"), "{text}");
        assert!(text.contains("'Q2'"), "{text}");
    }

    /// A duplicate title is caught before `batchUpdate` rather than left to
    /// the server, so a dry run cannot promise a change the real run fails.
    #[tokio::test]
    async fn add_sheet_refuses_a_title_the_workbook_already_uses() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let verb = StructureVerb::AddSheet {
            title: "Q1".to_string(),
            index: None,
            rows: None,
            columns: None,
        };
        // No batchUpdate mock: the refusal must short-circuit the mutation.
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb.clone(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(
            outcome.result,
            StructureResult::RefusedSheetExists { .. }
        ));
        assert!(describe(&outcome).contains("already has a sheet titled 'Q1'"));
    }

    /// The rename analogue of the `add-sheet` test above: renaming to a
    /// title a *different* sheet already has must be caught before
    /// `batchUpdate`, not left to a dry run that then can't be trusted.
    #[tokio::test]
    async fn rename_sheet_refuses_a_title_another_sheet_already_uses() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let verb = StructureVerb::RenameSheet {
            sheet: "Q2".to_string(),
            new_title: "Q1".to_string(),
        };
        // No batchUpdate mock: the refusal must short-circuit the mutation,
        // and the same must hold for a --dry-run preview of it.
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb.clone(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(
            outcome.result,
            StructureResult::RefusedSheetExists { .. }
        ));
        assert!(describe(&outcome).contains("already has a sheet titled 'Q1'"));

        let dry = structure(
            &drive,
            &sheets,
            &opts(verb.clone(), true),
            &[allow_rule("parent-1")],
        )
        .await;
        assert_eq!(dry.result, outcome.result);
    }

    /// Renaming a sheet to the title it already has names itself, not a
    /// different sheet, so it must not be refused as a duplicate.
    #[tokio::test]
    async fn rename_sheet_to_its_own_current_title_is_not_a_duplicate() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        let verb = StructureVerb::RenameSheet {
            sheet: "Q2".to_string(),
            new_title: "Q2".to_string(),
        };
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Changed { .. }));
    }

    // ── argument validation ──────────────────────────────────────────────

    #[tokio::test]
    async fn insert_rows_refuses_a_count_below_one() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let verb = StructureVerb::InsertRows {
            sheet: "Q2".to_string(),
            at: 5,
            count: 0,
        };
        // No batchUpdate mock: the refusal must short-circuit the mutation.
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb.clone(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result);
        };
        assert!(detail.contains("--count"), "{detail}");
        assert!(describe(&outcome).starts_with("Refused: --count"));
    }

    #[tokio::test]
    async fn insert_columns_refuses_an_at_below_one() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let verb = StructureVerb::InsertColumns {
            sheet: "Q2".to_string(),
            at: 0,
            count: 1,
        };
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, false),
            &[allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result);
        };
        assert!(detail.contains("--at"), "{detail}");
    }

    /// `Q2` has 500 rows (from `mount_workbook`); `--at 502` names a
    /// position that does not exist and is not immediately after one that
    /// does, so it must be refused rather than sent to `batchUpdate` or
    /// promised by a `--dry-run`.
    #[tokio::test]
    async fn insert_rows_refuses_an_at_past_the_sheets_end() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let verb = StructureVerb::InsertRows {
            sheet: "Q2".to_string(),
            at: 502,
            count: 1,
        };
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb.clone(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result);
        };
        assert!(detail.contains("500 row(s)"), "{detail}");
        assert!(detail.contains("501"), "{detail}");

        let dry = structure(
            &drive,
            &sheets,
            &opts(verb, true),
            &[allow_rule("parent-1")],
        )
        .await;
        assert_eq!(dry.result, outcome.result);
    }

    #[test]
    fn an_at_and_count_that_would_overflow_the_index_space_are_refused() {
        let sheet = SheetSnapshot {
            sheet_id: Some(1),
            title: "Q2".to_string(),
            row_count: Some(500),
            column_count: Some(26),
            ..Default::default()
        };
        // Both halves of `at - 1 + count`, since either can be the one that
        // overflows: a huge `--at` (refused for being past the end too, but
        // only *after* this check) and a huge `--count` at a legal `--at`
        // (which nothing else bounds — see the comment on the guard).
        for (at, count) in [(i64::MAX, 5), (500, i64::MAX)] {
            let Err(StructureResult::RefusedInvalidRange { detail }) =
                validate_insert_bounds(Dimension::Rows, at, count, Some(&sheet))
            else {
                panic!("expected RefusedInvalidRange for --at {at} --count {count}");
            };
            assert!(detail.contains("overflows the row index space"), "{detail}");
        }
    }

    #[tokio::test]
    async fn a_refused_out_of_range_insert_still_records_without_panicking() {
        // The regression that matters for `dimension_range_label`: this runs
        // with `dry_run: false`, so `record_attempt` builds a log record from
        // the very arguments `validate_insert_bounds` just rejected. Computing
        // the span with plain arithmetic panics here rather than in the
        // mutation it refused to make.
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;

        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::InsertRows {
                    sheet: "Q2".to_string(),
                    at: i64::MAX,
                    count: 5,
                },
                false,
            ),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(
            matches!(outcome.result, StructureResult::RefusedInvalidRange { .. }),
            "{:?}",
            outcome.result
        );
    }

    /// `--at` equal to `row_count + 1` is a legal append (insert after the
    /// last row), the one boundary value the check above must not reject —
    /// and the dry-run message must not print an inverted "existing rows
    /// 501-500 shift down".
    #[tokio::test]
    async fn insert_rows_allows_at_equal_to_row_count_plus_one_as_an_append() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let verb = StructureVerb::InsertRows {
            sheet: "Q2".to_string(),
            at: 501,
            count: 2,
        };
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb.clone(), true),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(
            outcome.result,
            StructureResult::WouldChange { .. }
        ));
        let text = describe(&outcome);
        assert!(text.contains("500 rows -> 502"), "{text}");
        assert!(text.contains("appended at the end"), "{text}");
        assert!(!text.contains("501-500"), "{text}");
    }

    #[tokio::test]
    async fn add_sheet_refuses_non_positive_rows_and_columns() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let verb = StructureVerb::AddSheet {
            title: "Q3".to_string(),
            index: None,
            rows: Some(0),
            columns: None,
        };
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, false),
            &[allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result);
        };
        assert!(detail.contains("--rows"), "{detail}");
    }

    /// `mount_workbook` has 2 sheets, so 0/1/2 are the only valid indices
    /// (2 means "append", the same as omitting `--index`).
    #[tokio::test]
    async fn add_sheet_refuses_an_out_of_range_index() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let verb = StructureVerb::AddSheet {
            title: "Q3".to_string(),
            index: Some(3),
            rows: None,
            columns: None,
        };
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, false),
            &[allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result);
        };
        assert!(detail.contains("--index"), "{detail}");
    }

    #[tokio::test]
    async fn add_sheet_allows_an_index_equal_to_the_sheet_count() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let verb = StructureVerb::AddSheet {
            title: "Q3".to_string(),
            index: Some(2),
            rows: None,
            columns: None,
        };
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, true),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(
            outcome.result,
            StructureResult::WouldChange { .. }
        ));
    }

    // ── the mutation ───────────────────────────────────────────────────

    #[tokio::test]
    async fn rename_sends_a_title_masked_update_for_the_resolved_sheet_id() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .expect(1)
            .mount(&server)
            .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(rename(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Changed { .. }));

        let requests = server.received_requests().await.unwrap();
        let body: serde_json::Value = requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request");
        let update = &body["requests"][0]["updateSheetProperties"];
        // Resolved by title to the numeric id the API addresses.
        assert_eq!(update["properties"]["sheetId"], 118_293);
        assert_eq!(update["properties"]["title"], "Q3");
        // The mask names exactly the one field we set; a wider mask would
        // blank every property it named but we left unpopulated.
        assert_eq!(update["fields"], "title");
        assert_eq!(body["requests"].as_array().unwrap().len(), 1);
    }

    #[tokio::test]
    async fn insert_rows_sends_a_zero_based_half_open_range() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(insert_rows(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Changed { .. }));

        let requests = server.received_requests().await.unwrap();
        let body: serde_json::Value = requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request");
        let insert = &body["requests"][0]["insertDimension"];
        assert_eq!(insert["range"]["dimension"], "ROWS");
        assert_eq!(insert["range"]["sheetId"], 118_293);
        // `--at 5 --count 3` on the wire, 1-based inclusive to 0-based
        // half-open.
        assert_eq!(insert["range"]["startIndex"], 4);
        assert_eq!(insert["range"]["endIndex"], 7);
        assert_eq!(insert["inheritFromBefore"], false);
    }

    #[tokio::test]
    async fn delete_sheet_sends_the_resolved_sheet_id() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .expect(1)
            .mount(&server)
            .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(delete_sheet(), false),
            &[delete_allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Changed { .. }));
        assert!(describe(&outcome).contains("Deleted sheet 'Q2'"));
        // `seed_lease` records a bytes backup, so the message names its
        // path; the Drive-copy and no-lease wordings have their own tests
        // in the lease section below.
        assert!(describe(&outcome).contains("backed the file up when it was acquired"));
        assert!(describe(&outcome).contains("/tmp/test-backup"));
        assert!(describe(&outcome).contains("Google Drive's own version history"));

        let requests = server.received_requests().await.unwrap();
        let body: serde_json::Value = requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request");
        assert_eq!(body["requests"][0]["deleteSheet"]["sheetId"], 118_293);
        assert_eq!(body["requests"].as_array().unwrap().len(), 1);
    }

    #[tokio::test]
    async fn delete_rows_sends_a_zero_based_half_open_range() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(delete_rows(), false),
            &[delete_allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Changed { .. }));

        let requests = server.received_requests().await.unwrap();
        let body: serde_json::Value = requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request");
        let delete = &body["requests"][0]["deleteDimension"];
        assert_eq!(delete["range"]["dimension"], "ROWS");
        assert_eq!(delete["range"]["sheetId"], 118_293);
        // `--at 5 --count 3` on the wire, 1-based inclusive to 0-based
        // half-open — same conversion as insert, same site.
        assert_eq!(delete["range"]["startIndex"], 4);
        assert_eq!(delete["range"]["endIndex"], 7);
    }

    #[tokio::test]
    async fn delete_columns_sends_a_zero_based_half_open_range() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(delete_columns(), false),
            &[delete_allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Changed { .. }));
        assert!(describe(&outcome).contains("Deleted 2 column(s) 3-4"));

        let requests = server.received_requests().await.unwrap();
        let body: serde_json::Value = requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request");
        let delete = &body["requests"][0]["deleteDimension"];
        assert_eq!(delete["range"]["dimension"], "COLUMNS");
        assert_eq!(delete["range"]["sheetId"], 118_293);
        // `--at 3 --count 2` on the wire, 1-based inclusive to 0-based
        // half-open.
        assert_eq!(delete["range"]["startIndex"], 2);
        assert_eq!(delete["range"]["endIndex"], 4);
    }

    #[tokio::test]
    async fn insert_range_sends_a_zero_based_half_open_grid_range() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(insert_range(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Changed { .. }));
        assert!(describe(&outcome).contains("shifting existing cells down"));
        assert!(describe(&outcome).contains("may have been dropped by Sheets"));

        let requests = server.received_requests().await.unwrap();
        let body: serde_json::Value = requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request");
        assert_eq!(
            body["requests"][0]["insertRange"],
            serde_json::json!({
                "range": {
                    "sheetId": 118_293,
                    "startRowIndex": 1,
                    "endRowIndex": 4,
                    "startColumnIndex": 1,
                    "endColumnIndex": 3,
                },
                "shiftDimension": "ROWS",
            })
        );
    }

    #[tokio::test]
    async fn insert_range_with_columns_shift_sends_the_column_direction() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(insert_range_columns_shift(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Changed { .. }));
        assert!(describe(&outcome).contains("shifting existing cells right"));

        let requests = server.received_requests().await.unwrap();
        let body: serde_json::Value = requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request");
        assert_eq!(
            body["requests"][0]["insertRange"]["shiftDimension"],
            "COLUMNS"
        );
    }

    #[tokio::test]
    async fn insert_range_dry_run_at_the_grid_edge_warns_without_mutating() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::InsertRange {
                    sheet: "Q2".to_string(),
                    start_row: 500,
                    end_row: 500,
                    start_column: 10,
                    end_column: 10,
                    shift: ShiftDimension::Columns,
                },
                true,
            ),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(
            outcome.result,
            StructureResult::WouldChange { .. }
        ));
        let text = describe(&outcome);
        assert!(text.contains("shifting existing cells right"), "{text}");
        assert!(text.contains("may be dropped by Sheets"), "{text}");
        assert!(server
            .received_requests()
            .await
            .unwrap()
            .iter()
            .all(|request| !request.url.path().ends_with(":batchUpdate")));
    }

    #[tokio::test]
    async fn insert_range_dry_run_with_rows_shift_warns_without_mutating() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::InsertRange {
                    sheet: "Q2".to_string(),
                    start_row: 500,
                    end_row: 500,
                    start_column: 10,
                    end_column: 10,
                    shift: ShiftDimension::Rows,
                },
                true,
            ),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(
            outcome.result,
            StructureResult::WouldChange { .. }
        ));
        let text = describe(&outcome);
        assert!(text.contains("shifting existing cells down"), "{text}");
        assert!(text.contains("may be dropped by Sheets"), "{text}");
        assert!(server
            .received_requests()
            .await
            .unwrap()
            .iter()
            .all(|request| !request.url.path().ends_with(":batchUpdate")));
    }

    #[tokio::test]
    async fn delete_range_sends_a_zero_based_half_open_grid_range() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(delete_range(), false),
            &[delete_allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Changed { .. }));

        let requests = server.received_requests().await.unwrap();
        let body: serde_json::Value = requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request");
        let delete = &body["requests"][0]["deleteRange"];
        assert_eq!(delete["range"]["sheetId"], 118_293);
        // `--start-row 2 --end-row 4 --start-column 2 --end-column 3` on the
        // wire, 1-based inclusive to 0-based half-open.
        assert_eq!(delete["range"]["startRowIndex"], 1);
        assert_eq!(delete["range"]["endRowIndex"], 4);
        assert_eq!(delete["range"]["startColumnIndex"], 1);
        assert_eq!(delete["range"]["endColumnIndex"], 3);
        assert_eq!(delete["shiftDimension"], "ROWS");
    }

    #[tokio::test]
    async fn delete_range_with_columns_shift_sends_the_column_direction() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(delete_range_columns_shift(), false),
            &[delete_allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Changed { .. }));
        assert!(describe(&outcome).contains("shifted remaining cells left"));

        let requests = server.received_requests().await.unwrap();
        let body: serde_json::Value = requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request");
        assert_eq!(
            body["requests"][0]["deleteRange"]["shiftDimension"],
            "COLUMNS"
        );
    }

    #[tokio::test]
    async fn delete_dimension_past_the_end_of_the_sheet_is_refused() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        // Q2 has 500 rows; deleting 5 rows starting at 499 reaches row 503.
        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::DeleteRows {
                    sheet: "Q2".to_string(),
                    at: 499,
                    count: 5,
                },
                true,
            ),
            &[delete_allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(
            outcome.result,
            StructureResult::RefusedInvalidRange { .. }
        ));
    }

    #[tokio::test]
    async fn delete_range_with_end_before_start_is_refused() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::DeleteRange {
                    sheet: "Q2".to_string(),
                    start_row: 5,
                    end_row: 2,
                    start_column: 1,
                    end_column: 2,
                    shift: ShiftDimension::Rows,
                },
                true,
            ),
            &[delete_allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(
            outcome.result,
            StructureResult::RefusedInvalidRange { .. }
        ));
    }

    #[tokio::test]
    async fn delete_dimension_refuses_a_non_positive_count() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::DeleteRows {
                    sheet: "Q2".to_string(),
                    at: 1,
                    count: 0,
                },
                true,
            ),
            &[delete_allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result);
        };
        assert!(detail.contains("--count must be at least 1"), "{detail}");
    }

    #[tokio::test]
    async fn delete_dimension_refuses_an_at_below_one() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::DeleteColumns {
                    sheet: "Q2".to_string(),
                    at: 0,
                    count: 1,
                },
                true,
            ),
            &[delete_allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result);
        };
        assert!(detail.contains("--at must be at least 1"), "{detail}");
    }

    #[tokio::test]
    async fn delete_dimension_refuses_an_at_and_count_that_overflow_the_index_space() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::DeleteRows {
                    sheet: "Q2".to_string(),
                    at: i64::MAX,
                    count: 2,
                },
                true,
            ),
            &[delete_allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result);
        };
        assert!(detail.contains("overflows the row index space"), "{detail}");
    }

    #[tokio::test]
    async fn delete_range_refuses_a_start_row_below_one() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::DeleteRange {
                    sheet: "Q2".to_string(),
                    start_row: 0,
                    end_row: 2,
                    start_column: 1,
                    end_column: 2,
                    shift: ShiftDimension::Rows,
                },
                true,
            ),
            &[delete_allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result);
        };
        assert!(
            detail.contains("--start-row must be at least 1"),
            "{detail}"
        );
    }

    #[tokio::test]
    async fn delete_range_refuses_a_start_column_below_one() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::DeleteRange {
                    sheet: "Q2".to_string(),
                    start_row: 1,
                    end_row: 2,
                    start_column: 0,
                    end_column: 2,
                    shift: ShiftDimension::Rows,
                },
                true,
            ),
            &[delete_allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result);
        };
        assert!(
            detail.contains("--start-column must be at least 1"),
            "{detail}"
        );
    }

    #[tokio::test]
    async fn delete_range_refuses_an_end_column_before_start_column() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        // Rows are well-ordered on their own; only the columns are inverted,
        // so this is refused for a different reason than
        // `delete_range_with_end_before_start_is_refused`.
        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::DeleteRange {
                    sheet: "Q2".to_string(),
                    start_row: 1,
                    end_row: 2,
                    start_column: 5,
                    end_column: 2,
                    shift: ShiftDimension::Rows,
                },
                true,
            ),
            &[delete_allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result);
        };
        assert!(
            detail.contains("--end-column (2) must be at or after --start-column (5)"),
            "{detail}"
        );
    }

    #[tokio::test]
    async fn delete_range_refuses_an_end_row_past_the_end_of_the_sheet() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        // Q2 has 500 rows.
        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::DeleteRange {
                    sheet: "Q2".to_string(),
                    start_row: 1,
                    end_row: 501,
                    start_column: 1,
                    end_column: 2,
                    shift: ShiftDimension::Rows,
                },
                true,
            ),
            &[delete_allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result);
        };
        assert!(
            detail.contains("--end-row 501 is past the end of the sheet"),
            "{detail}"
        );
    }

    #[tokio::test]
    async fn delete_range_refuses_an_end_column_past_the_end_of_the_sheet() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        // Q2 has 10 columns.
        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::DeleteRange {
                    sheet: "Q2".to_string(),
                    start_row: 1,
                    end_row: 2,
                    start_column: 1,
                    end_column: 11,
                    shift: ShiftDimension::Rows,
                },
                true,
            ),
            &[delete_allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result);
        };
        assert!(
            detail.contains("--end-column 11 is past the end of the sheet"),
            "{detail}"
        );
    }

    #[tokio::test]
    async fn add_sheet_reports_the_server_assigned_sheet_id() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({
            "spreadsheetId": "sheet-1",
            "replies": [{"addSheet": {"properties": {"sheetId": 999, "title": "Q3"}}}],
        }))
        .mount(&server)
        .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(add_sheet(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        // The one fact the reply carries that the request did not know.
        assert!(matches!(
            outcome.result,
            StructureResult::Changed {
                sheet_id: Some(999),
                ..
            }
        ));
        assert!(describe(&outcome).contains("sheetId 999"));
    }

    #[tokio::test]
    async fn add_sheet_omits_grid_properties_when_no_size_was_asked_for() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        let _ = structure(
            &drive,
            &sheets,
            &opts(add_sheet(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        let requests = server.received_requests().await.unwrap();
        let body: serde_json::Value = requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request");
        let props = &body["requests"][0]["addSheet"]["properties"];
        // Omitted, not zeroed: Sheets' own default (1000 x 26) should apply
        // rather than a size we invented.
        assert!(props.get("gridProperties").is_none(), "{props}");
        assert!(props.get("index").is_none(), "{props}");
        assert_eq!(props["title"], "Q3");
    }

    #[tokio::test]
    async fn a_batch_update_failure_is_reported_as_failed_not_changed() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        wiremock::Mock::given(wiremock::matchers::method("POST"))
            .and(wiremock::matchers::path(
                "/v4/spreadsheets/sheet-1:batchUpdate",
            ))
            .respond_with(
                wiremock::ResponseTemplate::new(403).set_body_json(serde_json::json!({
                    "error": {
                        "code": 403,
                        "message": "The caller does not have permission",
                        "status": "PERMISSION_DENIED",
                    }
                })),
            )
            .mount(&server)
            .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(rename(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        let StructureResult::Failed { detail } = &outcome.result else {
            panic!("expected Failed, got {:?}", outcome.result);
        };
        // The `google.rpc` envelope has no `errors[]`, so the scope hint has
        // to match on `status` — ADR-0073 §2.
        assert!(detail.contains("drive auth login"), "{detail}");
    }

    // ── duplicate-sheet / reorder-sheet / hide-show-sheet (issue #1643) ─

    #[tokio::test]
    async fn duplicate_sheet_apply_sends_source_title_and_index() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(duplicate_sheet(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Changed { .. }));

        let requests = server.received_requests().await.unwrap();
        let body: serde_json::Value = requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request");
        let dup = &body["requests"][0]["duplicateSheet"];
        assert_eq!(dup["sourceSheetId"], 118_293);
        assert_eq!(dup["insertSheetIndex"], 1);
        assert_eq!(dup["newSheetName"], "Q2 Copy");
    }

    #[tokio::test]
    async fn duplicate_sheet_apply_with_default_title_and_index() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(duplicate_sheet_default(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Changed { .. }));

        let requests = server.received_requests().await.unwrap();
        let body: serde_json::Value = requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request");
        let dup = &body["requests"][0]["duplicateSheet"];
        assert!(dup.get("insertSheetIndex").is_none());
        assert!(dup.get("newSheetName").is_none());
    }

    #[tokio::test]
    async fn duplicate_sheet_dry_run_names_title_and_index() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(duplicate_sheet(), true),
            &[allow_rule("parent-1")],
        )
        .await;
        let text = describe(&outcome);
        assert!(text.contains("Would duplicate sheet 'Q2'"), "{text}");
        assert!(text.contains("as 'Q2 Copy'"), "{text}");
        assert!(text.contains("at index 1"), "{text}");
        let requests = server.received_requests().await.unwrap();
        assert!(!requests
            .iter()
            .any(|r| r.url.path().ends_with(":batchUpdate")));
    }

    #[tokio::test]
    async fn duplicate_sheet_dry_run_uses_defaults_when_omitted() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(duplicate_sheet_default(), true),
            &[allow_rule("parent-1")],
        )
        .await;
        let text = describe(&outcome);
        assert!(
            text.contains("as a copy Sheets names automatically"),
            "{text}"
        );
        assert!(text.contains("at the front"), "{text}");
    }

    #[tokio::test]
    async fn duplicate_sheet_refuses_a_missing_source_sheet() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::DuplicateSheet {
                    sheet: "Nope".to_string(),
                    title: None,
                    index: None,
                },
                false,
            ),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(
            outcome.result,
            StructureResult::RefusedSheetNotFound { .. }
        ));
    }

    #[tokio::test]
    async fn duplicate_sheet_refuses_a_colliding_new_title() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::DuplicateSheet {
                    sheet: "Q2".to_string(),
                    title: Some("Q1".to_string()),
                    index: None,
                },
                false,
            ),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(
            outcome.result,
            StructureResult::RefusedSheetExists { ref title } if title == "Q1"
        ));
    }

    #[tokio::test]
    async fn duplicate_sheet_refuses_an_out_of_range_index() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::DuplicateSheet {
                    sheet: "Q2".to_string(),
                    title: None,
                    index: Some(99),
                },
                false,
            ),
            &[allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result);
        };
        assert!(
            detail.contains("--index must be between 0 and 2"),
            "{detail}"
        );
    }

    #[tokio::test]
    async fn reorder_sheet_apply_sends_index_masked_update() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(reorder_sheet(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Changed { .. }));

        let requests = server.received_requests().await.unwrap();
        let body: serde_json::Value = requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request");
        let update = &body["requests"][0]["updateSheetProperties"];
        assert_eq!(update["properties"]["sheetId"], 118_293);
        assert_eq!(update["properties"]["index"], 0);
        assert_eq!(update["fields"], "index");
    }

    #[tokio::test]
    async fn reorder_sheet_dry_run_names_the_target_index() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(reorder_sheet(), true),
            &[allow_rule("parent-1")],
        )
        .await;
        let text = describe(&outcome);
        assert!(text.contains("Would move sheet 'Q2'"), "{text}");
        assert!(text.contains("to index 0"), "{text}");
    }

    #[tokio::test]
    async fn reorder_sheet_refuses_an_out_of_range_index() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::ReorderSheet {
                    sheet: "Q2".to_string(),
                    index: 5,
                },
                false,
            ),
            &[allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result);
        };
        assert!(
            detail.contains("--index must be between 0 and 1"),
            "{detail}"
        );
    }

    #[tokio::test]
    async fn hide_sheet_apply_sends_hidden_true() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(hide_sheet(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Changed { .. }));

        let requests = server.received_requests().await.unwrap();
        let body: serde_json::Value = requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request");
        let update = &body["requests"][0]["updateSheetProperties"];
        assert_eq!(update["properties"]["sheetId"], 118_293);
        assert_eq!(update["properties"]["hidden"], true);
        assert_eq!(update["fields"], "hidden");
    }

    #[tokio::test]
    async fn show_sheet_apply_sends_hidden_false() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook_with_q2(hidden_q2()).mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(show_sheet(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Changed { .. }));

        let requests = server.received_requests().await.unwrap();
        let body: serde_json::Value = requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request");
        let update = &body["requests"][0]["updateSheetProperties"];
        assert_eq!(update["properties"]["hidden"], false);
    }

    #[tokio::test]
    async fn hide_sheet_dry_run_names_the_hide() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(hide_sheet(), true),
            &[allow_rule("parent-1")],
        )
        .await;
        let text = describe(&outcome);
        assert!(text.contains("Would hide sheet 'Q2'"), "{text}");
    }

    #[tokio::test]
    async fn show_sheet_dry_run_names_the_show() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook_with_q2(hidden_q2()).mount(&server).await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(show_sheet(), true),
            &[allow_rule("parent-1")],
        )
        .await;
        let text = describe(&outcome);
        assert!(text.contains("Would show sheet 'Q2'"), "{text}");
    }

    /// Hiding a hidden sheet or showing a visible one sends nothing and
    /// says so, in a dry run exactly as in a real run, rather than
    /// reporting a change that did not happen.
    #[tokio::test]
    async fn a_visibility_no_op_is_unchanged_in_dry_run_and_real_run() {
        for (verb, q2, state) in [
            (hide_sheet(), hidden_q2(), "hidden"),
            (show_sheet(), default_q2(), "shown"),
        ] {
            for dry_run in [true, false] {
                let server = wiremock::MockServer::start().await;
                let (drive, sheets) = clients(&server).await;
                mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
                    .mount(&server)
                    .await;
                mount_folder("parent-1").mount(&server).await;
                mount_workbook_with_q2(q2.clone()).mount(&server).await;
                let outcome = structure(
                    &drive,
                    &sheets,
                    &opts(verb.clone(), dry_run),
                    &[allow_rule("parent-1")],
                )
                .await;
                assert_eq!(
                    outcome.result,
                    StructureResult::Unchanged {
                        detail: format!("sheet 'Q2' is already {state}")
                    },
                    "dry_run={dry_run}"
                );
                let text = describe(&outcome);
                assert!(
                    text.starts_with(&format!("Unchanged: sheet 'Q2' is already {state} in ")),
                    "{text}"
                );
                let requests = server.received_requests().await.unwrap();
                assert!(
                    !requests
                        .iter()
                        .any(|r| r.url.path().ends_with(":batchUpdate")),
                    "a no-op must not call batchUpdate"
                );
            }
        }
    }

    #[tokio::test]
    async fn hide_sheet_refuses_leaving_no_visible_sheets() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        wiremock::Mock::given(wiremock::matchers::method("GET"))
            .and(wiremock::matchers::path("/v4/spreadsheets/sheet-1"))
            .respond_with(
                wiremock::ResponseTemplate::new(200).set_body_json(serde_json::json!({
                    "spreadsheetId": "sheet-1",
                    "properties": {"title": "Budget"},
                    "sheets": [
                        {"properties": {"sheetId": 0, "title": "Q1", "index": 0, "hidden": true}},
                        {"properties": {"sheetId": 118_293, "title": "Q2", "index": 1}},
                    ],
                })),
            )
            .mount(&server)
            .await;
        let outcome = structure(
            &drive,
            &sheets,
            &opts(hide_sheet(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result);
        };
        assert!(
            detail.contains("would leave the workbook with no visible sheets"),
            "{detail}"
        );
    }

    // ── update-sheet-properties (issue #1835) ───────────────────────────

    fn update_sheet_properties(
        freeze_rows: Option<i64>,
        freeze_columns: Option<i64>,
        tab_color: Option<&str>,
        clear_tab_color: bool,
        right_to_left: Option<bool>,
        hide_gridlines: Option<bool>,
    ) -> StructureVerb {
        StructureVerb::UpdateSheetProperties {
            sheet: "Q2".to_string(),
            freeze_rows,
            freeze_columns,
            tab_color: tab_color.map(ToString::to_string),
            clear_tab_color,
            right_to_left,
            hide_gridlines,
        }
    }

    /// A `spreadsheets.get` reply like [`mount_workbook`], but `Q2` reports
    /// `frozenRowCount: 1` — the fixture
    /// [`update_sheet_properties_dry_run_reports_before_and_after`] needs to
    /// exercise the before->after line.
    fn mount_workbook_with_frozen_rows(
        sheet_id: i64,
        row_count: i64,
        frozen_row_count: i64,
    ) -> wiremock::Mock {
        mount_workbook_with_q2(serde_json::json!({
        "properties": {
            "sheetId": sheet_id, "title": "Q2", "index": 1,
            "gridProperties": {
                "rowCount": row_count, "columnCount": 10,
                "frozenRowCount": frozen_row_count,
            }}}))
    }

    /// A `spreadsheets.get` reply like [`mount_workbook`], but `Q2` already
    /// carries the three view properties whose "before" value is read off
    /// the snapshot rather than off `gridProperties.rowCount` —
    /// `frozenColumnCount`, `rightToLeft` and `hideGridlines`. Without a
    /// fixture that reports them, every fragment
    /// [`update_sheet_properties_fragments`] builds for them falls to the
    /// `before: None` shape, so the `"<label> <before> -> <after>"` half of
    /// the description would never be exercised for anything but frozen
    /// rows (issue #1835).
    fn mount_workbook_with_view_state() -> wiremock::Mock {
        mount_workbook_with_q2(serde_json::json!({
        "properties": {
            "sheetId": 118_293, "title": "Q2", "index": 1,
            "rightToLeft": true,
            "gridProperties": {
                "rowCount": 500, "columnCount": 10,
                "frozenColumnCount": 2,
                "hideGridlines": true,
            }}}))
    }

    #[tokio::test]
    async fn update_sheet_properties_apply_sends_only_the_set_fields_in_the_mask() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        let verb = update_sheet_properties(Some(2), None, Some("#FF8800"), false, None, None);
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Changed { .. }));

        let requests = server.received_requests().await.unwrap();
        let body: serde_json::Value = requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request");
        let update = &body["requests"][0]["updateSheetProperties"];
        assert_eq!(
            update["fields"],
            "gridProperties.frozenRowCount,tabColorStyle"
        );
        assert_eq!(update["properties"]["sheetId"], 118_293);
        assert_eq!(update["properties"]["gridProperties"]["frozenRowCount"], 2);
        let rgb = &update["properties"]["tabColorStyle"]["rgbColor"];
        assert!((rgb["red"].as_f64().unwrap() - 1.0).abs() < 1e-6, "{rgb}");
        assert!(
            (rgb["green"].as_f64().unwrap() - (136.0 / 255.0)).abs() < 1e-6,
            "{rgb}"
        );
        assert!((rgb["blue"].as_f64().unwrap() - 0.0).abs() < 1e-6, "{rgb}");
        assert!(
            update["properties"]["gridProperties"]
                .get("frozenColumnCount")
                .is_none(),
            "{update}"
        );
        assert!(
            update["properties"].get("rightToLeft").is_none(),
            "{update}"
        );
        assert!(update["properties"].get("hidden").is_none(), "{update}");
        assert!(update["properties"].get("title").is_none(), "{update}");
        assert!(update["properties"].get("index").is_none(), "{update}");
    }

    #[tokio::test]
    async fn update_sheet_properties_apply_clear_tab_color_names_tab_color_style_with_no_value() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        let verb = update_sheet_properties(None, None, None, true, None, None);
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Changed { .. }));

        let requests = server.received_requests().await.unwrap();
        let body: serde_json::Value = requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request");
        let update = &body["requests"][0]["updateSheetProperties"];
        assert_eq!(update["fields"], "tabColorStyle");
        assert!(
            update["properties"].get("tabColorStyle").is_none(),
            "{update}"
        );
    }

    #[tokio::test]
    async fn update_sheet_properties_dry_run_reports_before_and_after() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook_with_frozen_rows(118_293, 500, 1)
            .mount(&server)
            .await;
        let verb = update_sheet_properties(Some(3), None, None, false, None, None);
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, true),
            &[allow_rule("parent-1")],
        )
        .await;
        let text = describe(&outcome);
        assert!(text.contains("frozen rows 1 -> 3"), "{text}");
    }

    #[tokio::test]
    async fn update_sheet_properties_apply_sends_every_property_and_reports_each_one() {
        // The companion of
        // `update_sheet_properties_apply_sends_only_the_set_fields_in_the_mask`,
        // which sets two properties: this one sets all five, so every
        // `fields` entry and every description fragment is exercised, and
        // the mask's order is pinned against the order `build_request`
        // pushes them in. `mount_workbook`'s Q2 reports none of the three
        // optional view properties, so this is also the run where each
        // fragment takes its `before: None` shape ("<label> -> <after>").
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        // A bare hex, so the reported text also pins that the display
        // normalization supplies the '#' the user didn't type.
        let verb = update_sheet_properties(
            Some(2),
            Some(3),
            Some("0000FF"),
            false,
            Some(true),
            Some(true),
        );
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(
            matches!(outcome.result, StructureResult::Changed { .. }),
            "{:?}",
            outcome.result
        );

        let requests = server.received_requests().await.unwrap();
        let body: serde_json::Value = requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request");
        let update = &body["requests"][0]["updateSheetProperties"];
        assert_eq!(
            update["fields"],
            "gridProperties.frozenRowCount,gridProperties.frozenColumnCount,\
             gridProperties.hideGridlines,tabColorStyle,rightToLeft"
        );
        let grid = &update["properties"]["gridProperties"];
        assert_eq!(grid["frozenRowCount"], 2);
        assert_eq!(grid["frozenColumnCount"], 3);
        assert_eq!(grid["hideGridlines"], true);
        assert_eq!(update["properties"]["rightToLeft"], true);

        let text = describe(&outcome);
        assert!(text.starts_with("Updated sheet 'Q2'"), "{text}");
        for fragment in [
            "frozen rows -> 2",
            "frozen columns -> 3",
            "tab color -> #0000FF",
            "right-to-left -> true",
            "gridlines -> hidden",
        ] {
            assert!(text.contains(fragment), "{fragment} missing from {text}");
        }
    }

    #[tokio::test]
    async fn update_sheet_properties_dry_run_reports_clears_and_the_values_being_replaced() {
        // The other half of
        // `update_sheet_properties_apply_sends_every_property_and_reports_each_one`:
        // the sheet already carries `frozenColumnCount`/`rightToLeft`/
        // `hideGridlines`, so each fragment takes its
        // "<label> <before> -> <after>" shape, gridlines read as
        // hidden/shown rather than as booleans, and `--clear-tab-color`
        // states the clear instead of a target color. Frozen rows are left
        // unset, which is the only run where that property contributes no
        // fragment at all.
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook_with_view_state().mount(&server).await;
        let verb = update_sheet_properties(None, Some(4), None, true, Some(false), Some(false));
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, true),
            &[allow_rule("parent-1")],
        )
        .await;
        let text = describe(&outcome);
        assert!(text.starts_with("Would update sheet 'Q2'"), "{text}");
        assert!(!text.contains("frozen rows"), "{text}");
        for fragment in [
            "frozen columns 2 -> 4",
            "tab color cleared",
            "right-to-left true -> false",
            "gridlines hidden -> shown",
        ] {
            assert!(text.contains(fragment), "{fragment} missing from {text}");
        }
    }

    #[test]
    fn fields_changed_label_names_exactly_the_properties_the_verb_set() {
        // `record_attempt` logs what the verb *asked* to change, so this is
        // what lands in the request log's `fields_changed` context key for
        // an `update-sheet-properties` attempt — including a refused one.
        let every = update_sheet_properties(
            Some(2),
            Some(3),
            Some("#FF8800"),
            false,
            Some(true),
            Some(false),
        );
        assert_eq!(
            fields_changed_label(&every).as_deref(),
            Some(
                "frozenRowCount=2, frozenColumnCount=3, hideGridlines=false, \
                 tabColorStyle=#FF8800, rightToLeft=true"
            )
        );
        // A clear is a property change with no value, so it says so rather
        // than reporting a hex nobody asked for.
        let cleared = update_sheet_properties(None, None, None, true, None, None);
        assert_eq!(
            fields_changed_label(&cleared).as_deref(),
            Some("tabColorStyle=cleared")
        );
        // The shape `update_sheet_properties_refuses_when_nothing_is_set`
        // logs: refused before any property was set, so there is nothing to
        // name and the key is omitted rather than written empty.
        let empty = update_sheet_properties(None, None, None, false, None, None);
        assert_eq!(fields_changed_label(&empty), None);
        // Every other verb has no `fields_changed` at all.
        assert_eq!(fields_changed_label(&rename()), None);
    }

    #[tokio::test]
    async fn update_sheet_properties_refuses_a_tab_color_and_a_clear_together() {
        // The CLI's `clap::ArgGroup` already makes these two mutually
        // exclusive, but `StructureVerb` is also reachable from a
        // non-CLI caller, so the engine refuses the combination itself
        // rather than silently letting the color win.
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let verb = update_sheet_properties(None, None, Some("#FF8800"), true, None, None);
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, true),
            &[allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result); // omni-dev: coverage ignore-line reason="guards this test's assumption; validate_verb_args always refuses --tab-color with --clear-tab-color as RefusedInvalidRange"
        };
        assert!(detail.contains("mutually exclusive"), "{detail}");
    }

    #[tokio::test]
    async fn update_sheet_properties_names_its_own_subcommand_in_a_refusal() {
        // `label()` exists so a refusal names the command the user typed;
        // the `not a Google Sheet` refusal is the shortest path to it, and
        // nothing else in this module renders the verb's own name.
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", "application/pdf", &["parent-1"])
            .mount(&server)
            .await;
        let verb = update_sheet_properties(Some(2), None, None, false, None, None);
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(
            outcome.result,
            StructureResult::RefusedNotASpreadsheet { .. }
        ));
        let text = describe(&outcome);
        assert!(
            text.contains("drive sheets update-sheet-properties"),
            "{text}"
        );
    }

    #[tokio::test]
    async fn update_sheet_properties_refuses_a_negative_freeze_count() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let verb = update_sheet_properties(Some(-1), None, None, false, None, None);
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, true),
            &[allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result); // omni-dev: coverage ignore-line reason="guards this test's assumption; check_freeze_bound always refuses a negative --freeze-rows as RefusedInvalidRange"
        };
        assert!(
            detail.contains("--freeze-rows must be at least 0"),
            "{detail}"
        );
    }

    #[tokio::test]
    async fn update_sheet_properties_refuses_freezing_every_row() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook_with_frozen_rows(118_293, 5, 0)
            .mount(&server)
            .await;
        let verb = update_sheet_properties(Some(5), None, None, false, None, None);
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, true),
            &[allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result); // omni-dev: coverage ignore-line reason="guards this test's assumption; check_freeze_bound always refuses a --freeze-rows at or above the sheet's known row count as RefusedInvalidRange"
        };
        assert!(detail.contains("would freeze every row"), "{detail}");
    }

    #[tokio::test]
    async fn update_sheet_properties_allows_freezing_up_to_one_less_than_the_row_count() {
        // The boundary `check_freeze_bound` is supposed to allow: one
        // fewer than the sheet's current row count leaves exactly one row
        // unfrozen, which Sheets permits (the `>=` refusal in
        // `update_sheet_properties_refuses_freezing_every_row` above only
        // pins the refused side of this same bound).
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook_with_frozen_rows(118_293, 5, 0)
            .mount(&server)
            .await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        let verb = update_sheet_properties(Some(4), None, None, false, None, None);
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(
            matches!(outcome.result, StructureResult::Changed { .. }),
            "{:?}",
            outcome.result
        );
    }

    #[tokio::test]
    async fn update_sheet_properties_invents_no_freeze_ceiling_when_the_count_is_unknown() {
        // The other side of `check_freeze_bound`'s `Option`: a sheet with
        // no `gridProperties` at all — which is what Sheets reports for a
        // non-grid (`OBJECT`, full-page chart) sheet — leaves
        // `row_count`/`column_count` unknown. With no count to compare
        // against there is no ceiling to enforce, so the request goes
        // through and Sheets stays the authority on whether it is legal,
        // rather than omni-dev guessing a bound (ADR-0073 §7).
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        wiremock::Mock::given(wiremock::matchers::method("GET"))
            .and(wiremock::matchers::path("/v4/spreadsheets/sheet-1"))
            .respond_with(
                wiremock::ResponseTemplate::new(200).set_body_json(serde_json::json!({
                    "spreadsheetId": "sheet-1",
                    "properties": {"title": "Budget"},
                    "sheets": [
                        {"properties": {"sheetId": 118_293, "title": "Q2", "index": 0}}
                    ],
                })),
            )
            .mount(&server)
            .await;
        let verb = update_sheet_properties(Some(9_000), Some(9_000), None, false, None, None);
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, true),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(
            matches!(outcome.result, StructureResult::WouldChange { .. }),
            "{:?}",
            outcome.result
        );
    }

    #[tokio::test]
    async fn update_sheet_properties_refuses_a_negative_freeze_column_count() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let verb = update_sheet_properties(None, Some(-1), None, false, None, None);
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, true),
            &[allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result); // omni-dev: coverage ignore-line reason="guards this test's assumption; check_freeze_bound always refuses a negative --freeze-columns as RefusedInvalidRange"
        };
        assert!(
            detail.contains("--freeze-columns must be at least 0"),
            "{detail}"
        );
    }

    #[tokio::test]
    async fn update_sheet_properties_refuses_freezing_every_column() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        // mount_workbook()'s Q2 has columnCount 10.
        mount_workbook().mount(&server).await;
        let verb = update_sheet_properties(None, Some(10), None, false, None, None);
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, true),
            &[allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result); // omni-dev: coverage ignore-line reason="guards this test's assumption; check_freeze_bound always refuses a --freeze-columns at or above the sheet's known column count as RefusedInvalidRange"
        };
        assert!(detail.contains("would freeze every column"), "{detail}");
    }

    #[tokio::test]
    async fn update_sheet_properties_refuses_an_invalid_hex_color() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let verb = update_sheet_properties(None, None, Some("nope"), false, None, None);
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, true),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(
            outcome.result,
            StructureResult::RefusedInvalidRange { .. }
        ));
    }

    #[tokio::test]
    async fn update_sheet_properties_refuses_when_nothing_is_set() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        let verb = update_sheet_properties(None, None, None, false, None, None);
        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, true),
            &[allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result); // omni-dev: coverage ignore-line reason="guards this test's assumption; validate_verb_args always refuses an update-sheet-properties verb that set no property as RefusedInvalidRange"
        };
        assert!(detail.contains("at least one"), "{detail}");
    }

    // ── the Drive write lease (ADR-0080 §9) ─────────────────────────────

    fn allow_rule_no_lease(folder: &str) -> FolderPermissionRule {
        FolderPermissionRule {
            require_lease: false,
            ..allow_rule(folder)
        }
    }

    #[tokio::test]
    async fn refuses_without_a_lease_when_the_rule_requires_one() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        // No batchUpdate mock mounted — a refusal must make zero mutating
        // calls.

        let mut o = opts(rename(), false);
        o.lease_token = None;
        let outcome = structure(&drive, &sheets, &o, &[allow_rule("parent-1")]).await;
        assert_eq!(outcome.result, StructureResult::RefusedNoLease);
    }

    #[tokio::test]
    async fn refuses_an_unknown_lease_token() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;

        let mut o = opts(rename(), false);
        o.lease_token = Some("bogus-token".to_string());
        // Never seeded — no ledger exists at this fresh path.
        o.ledger_path = tempfile::tempdir()
            .unwrap()
            .keep()
            .join("lease-ledger.jsonl");
        let outcome = structure(&drive, &sheets, &o, &[allow_rule("parent-1")]).await;
        assert_eq!(outcome.result, StructureResult::RefusedLeaseExpired);
    }

    #[tokio::test]
    async fn refuses_a_lease_bound_to_a_different_file() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;

        let ledger_path = tempfile::tempdir()
            .unwrap()
            .keep()
            .join("lease-ledger.jsonl");
        let token = seed_lease(&ledger_path, "other-sheet", "1");
        let mut o = opts(rename(), false);
        o.lease_token = Some(token);
        o.ledger_path = ledger_path;
        let outcome = structure(&drive, &sheets, &o, &[allow_rule("parent-1")]).await;
        assert_eq!(outcome.result, StructureResult::RefusedLeaseWrongFile);
    }

    #[tokio::test]
    async fn refuses_a_stale_lease() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        // Live version "1" (`mount_file`'s default) but the lease was
        // acquired at "0" — the file has moved since.
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;

        let ledger_path = tempfile::tempdir()
            .unwrap()
            .keep()
            .join("lease-ledger.jsonl");
        let token = seed_lease(&ledger_path, "sheet-1", "0");
        let mut o = opts(rename(), false);
        o.lease_token = Some(token);
        o.ledger_path = ledger_path;
        let outcome = structure(&drive, &sheets, &o, &[allow_rule("parent-1")]).await;
        assert_eq!(outcome.result, StructureResult::RefusedLeaseStale);
    }

    #[tokio::test]
    async fn reports_a_lock_acquisition_failure_as_failed() {
        // A pre-existing lock file simulates another `drive lease`
        // operation genuinely in progress — reported as an operational
        // failure, not folded into `RefusedLeaseExpired`.
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;

        let o = opts(rename(), false);
        // Under `flock` (issue #1687), a busy lock now waits rather than
        // hard-failing (`check_and_lock_lease` -> `acquire_waiting`), so a
        // held `LedgerLock` no longer reproduces an immediate failure here.
        // A directory at the lock path does: opening it for write fails
        // outright with an I/O error, which is never retried.
        let mut lock_path = o.ledger_path.clone().into_os_string();
        lock_path.push(".lock");
        std::fs::create_dir(std::path::PathBuf::from(lock_path)).unwrap();

        let outcome = structure(&drive, &sheets, &o, &[allow_rule("parent-1")]).await;
        assert!(matches!(outcome.result, StructureResult::Failed { .. }));
    }

    #[tokio::test]
    async fn a_failed_pre_lease_refetch_is_reported_as_failed_with_no_batch_update_call() {
        // The gate's own resolve step succeeds off the first `files.get`,
        // but the fresh re-fetch feeding the staleness check (ADR-0080 §6)
        // fails — the change must report `Failed` and never reach
        // `batchUpdate`.
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .up_to_n_times(1)
            .with_priority(1)
            .mount(&server)
            .await;
        wiremock::Mock::given(wiremock::matchers::method("GET"))
            .and(wiremock::matchers::path("/drive/v3/files/sheet-1"))
            .respond_with(wiremock::ResponseTemplate::new(500))
            .with_priority(2)
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        wiremock::Mock::given(wiremock::matchers::method("POST"))
            .and(wiremock::matchers::path(
                "/v4/spreadsheets/sheet-1:batchUpdate",
            ))
            .respond_with(wiremock::ResponseTemplate::new(200))
            .expect(0)
            .mount(&server)
            .await;

        let outcome = structure(
            &drive,
            &sheets,
            &opts(rename(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Failed { .. }));
    }

    #[tokio::test]
    async fn a_rule_that_does_not_require_a_lease_skips_the_check_entirely() {
        // No lease token and no ledger seeded, with a rule that sets
        // `require_lease: false` — the change must still succeed, taking
        // the `else { None }` branch and never consulting the ledger.
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .expect(1)
            .mount(&server)
            .await;

        let mut o = opts(rename(), false);
        o.lease_token = None;
        let outcome = structure(&drive, &sheets, &o, &[allow_rule_no_lease("parent-1")]).await;
        assert!(matches!(
            outcome.result,
            StructureResult::Changed { backup: None, .. }
        ));
    }

    #[tokio::test]
    async fn a_rule_that_does_not_require_a_lease_still_refuses_a_stale_one_if_presented() {
        // ADR-0080 §13: `require_lease: false` relaxes the *requirement*,
        // not the *meaning* — a token volunteered anyway is checked exactly
        // like a required one, including staleness.
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        // Live version "1" (`mount_file`'s default) but the lease was
        // acquired at "0" — the file has moved since.
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        // No batchUpdate mock mounted — a refusal must make zero mutating
        // calls.

        let ledger_path = tempfile::tempdir()
            .unwrap()
            .keep()
            .join("lease-ledger.jsonl");
        let token = seed_lease(&ledger_path, "sheet-1", "0");
        let mut o = opts(rename(), false);
        o.lease_token = Some(token);
        o.ledger_path = ledger_path;
        let outcome = structure(&drive, &sheets, &o, &[allow_rule_no_lease("parent-1")]).await;
        assert_eq!(outcome.result, StructureResult::RefusedLeaseStale);
    }

    /// A native document's lease backs it up as a Drive copy (ADR-0080
    /// §3); a real-run delete under it names that copy's file id — the one
    /// thing a user can search the Drive UI for — and says the copy dates
    /// from acquisition, since a multi-use lease (§5) may have written
    /// since.
    #[tokio::test]
    async fn a_leased_delete_names_the_drive_copy_to_restore_from() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .expect(1)
            .mount(&server)
            .await;

        let ledger_path = tempfile::tempdir()
            .unwrap()
            .keep()
            .join("lease-ledger.jsonl");
        let token = seed_lease_with_backup(
            &ledger_path,
            "sheet-1",
            "1",
            LeaseBackup::DriveCopy {
                file_id: "backup-copy-1".to_string(),
            },
        );
        let mut o = opts(delete_sheet(), false);
        o.lease_token = Some(token);
        o.ledger_path = ledger_path;
        let outcome = structure(&drive, &sheets, &o, &[delete_allow_rule("parent-1")]).await;

        assert!(matches!(
            &outcome.result,
            StructureResult::Changed {
                backup: Some(backup),
                ..
            } if **backup == LeaseBackup::DriveCopy { file_id: "backup-copy-1".to_string() }
        ));
        let text = describe(&outcome);
        assert!(text.contains("Deleted sheet 'Q2'"), "{text}");
        assert!(
            text.contains(
                "backed the whole spreadsheet up when it was acquired (Drive copy backup-copy-1)"
            ),
            "{text}"
        );
        assert!(
            text.contains("restores a single deleted sheet automatically"),
            "{text}"
        );
        assert!(
            text.contains("Google Drive's own version history"),
            "{text}"
        );
        assert!(!text.contains("only recovery path"), "{text}");

        // The copy rides the JSON outcome too, so a machine caller can find
        // it without parsing the message.
        let json = serde_json::to_value(&outcome).unwrap();
        assert_eq!(json["result"]["backup"]["kind"], "drive_copy");
        assert_eq!(json["result"]["backup"]["file_id"], "backup-copy-1");
    }

    /// ADR-0080 §13: a `require_lease: false` rule takes no backup of its
    /// own, so `recovery_note` falls back to ADR-0077 §5's "no recovery
    /// path but Drive's own version history" wording — but a lease
    /// volunteered anyway is still checked and its backup still named,
    /// making that fallback wording false unless the presented lease is
    /// honoured.
    #[tokio::test]
    async fn a_presented_lease_under_a_non_requiring_rule_still_names_the_backup() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .expect(1)
            .mount(&server)
            .await;

        let ledger_path = tempfile::tempdir()
            .unwrap()
            .keep()
            .join("lease-ledger.jsonl");
        let token = seed_lease_with_backup(
            &ledger_path,
            "sheet-1",
            "1",
            LeaseBackup::DriveCopy {
                file_id: "backup-copy-1".to_string(),
            },
        );
        let mut o = opts(delete_sheet(), false);
        o.lease_token = Some(token);
        o.ledger_path = ledger_path;
        let rule = FolderPermissionRule {
            require_lease: false,
            ..delete_allow_rule("parent-1")
        };
        let outcome = structure(&drive, &sheets, &o, &[rule]).await;

        assert!(matches!(
            &outcome.result,
            StructureResult::Changed {
                backup: Some(backup),
                ..
            } if **backup == LeaseBackup::DriveCopy { file_id: "backup-copy-1".to_string() }
        ));
        let text = describe(&outcome);
        assert!(
            text.contains(
                "backed the whole spreadsheet up when it was acquired (Drive copy backup-copy-1)"
            ),
            "{text}"
        );
        assert!(!text.contains("only recovery path"), "{text}");
    }

    /// The other half of the honesty rule: a `require_lease: false` rule
    /// reaches the delete with no lease and no backup, and the message
    /// must not claim one — it falls back to ADR-0077's original wording
    /// and says why.
    #[tokio::test]
    async fn an_unleased_delete_does_not_claim_a_backup_exists() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .expect(1)
            .mount(&server)
            .await;

        let mut o = opts(delete_sheet(), false);
        o.lease_token = None;
        let rule = FolderPermissionRule {
            require_lease: false,
            ..delete_allow_rule("parent-1")
        };
        let outcome = structure(&drive, &sheets, &o, &[rule]).await;

        assert!(matches!(
            outcome.result,
            StructureResult::Changed { backup: None, .. }
        ));
        let text = describe(&outcome);
        assert!(text.contains("Deleted sheet 'Q2'"), "{text}");
        assert!(text.contains("no lease backup was taken"), "{text}");
        assert!(text.contains("`require_lease: false`"), "{text}");
        assert!(
            text.contains("version history is the only recovery path"),
            "{text}"
        );
        assert!(!text.contains("restore from that copy"), "{text}");
        assert!(serde_json::to_value(&outcome).unwrap()["result"]
            .get("backup")
            .is_none());
    }

    // ── move-rows / move-columns (issue #1834) ─────────────────────────

    /// The `batchUpdate` body the server actually received.
    fn sent_batch_update(requests: &[wiremock::Request]) -> serde_json::Value {
        requests
            .iter()
            .find(|r| r.url.path().ends_with(":batchUpdate"))
            .map(|r| serde_json::from_slice(&r.body).unwrap())
            .expect("a batchUpdate request")
    }

    /// [`mount_workbook`] with the `Q2` sheet object supplied wholesale —
    /// the hook the "does not consult" tests below use to add grid state
    /// this engine must keep ignoring.
    fn mount_workbook_with_q2(q2: serde_json::Value) -> wiremock::Mock {
        wiremock::Mock::given(wiremock::matchers::method("GET"))
            .and(wiremock::matchers::path("/v4/spreadsheets/sheet-1"))
            .respond_with(wiremock::ResponseTemplate::new(200).set_body_json(workbook_body(q2)))
    }

    /// Everything a move's real run needs mounted, minus the workbook.
    async fn mount_move_prereqs(server: &wiremock::MockServer) {
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(server)
            .await;
        mount_folder("parent-1").mount(server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(server)
            .await;
    }

    /// The conversion this verb exists to get right: `--at 2 --count 2`
    /// becomes the half-open `[1, 3)`, and `--before 6` becomes
    /// `destinationIndex: 5` — the API's *pre-move* numbering, so the block
    /// actually lands on rows 4-5, not row 6.
    #[tokio::test]
    async fn move_rows_apply_sends_move_dimension_with_pre_move_destination() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_move_prereqs(&server).await;
        mount_workbook().mount(&server).await;

        let outcome = structure(
            &drive,
            &sheets,
            &opts(move_rows(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(
            matches!(outcome.result, StructureResult::Changed { .. }),
            "{:?}",
            outcome.result
        );

        let requests = server.received_requests().await.unwrap();
        let body = sent_batch_update(&requests);
        assert_eq!(
            body["requests"][0]["moveDimension"],
            serde_json::json!({
                "source": {
                    "sheetId": 118_293, "dimension": "ROWS",
                    "startIndex": 1, "endIndex": 3,
                },
                "destinationIndex": 5,
            })
        );
        assert_eq!(body["requests"].as_array().unwrap().len(), 1);

        // The real-run message resolves the pre-move numbering for the
        // reader rather than echoing `--before` alone.
        let rendered = describe(&outcome);
        assert!(rendered.contains("Moved 2 row(s) 2-3"), "{rendered}");
        assert!(rendered.contains("to before row 6"), "{rendered}");
        assert!(rendered.contains("(now rows 4-5)"), "{rendered}");
    }

    #[tokio::test]
    async fn move_columns_apply_sends_move_dimension() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_move_prereqs(&server).await;
        mount_workbook().mount(&server).await;

        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::MoveColumns {
                    sheet: "Q2".to_string(),
                    at: 2,
                    count: 2,
                    before: 6,
                },
                false,
            ),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(
            matches!(outcome.result, StructureResult::Changed { .. }),
            "{:?}",
            outcome.result
        );

        let requests = server.received_requests().await.unwrap();
        let body = sent_batch_update(&requests);
        assert_eq!(
            body["requests"][0]["moveDimension"],
            serde_json::json!({
                "source": {
                    "sheetId": 118_293, "dimension": "COLUMNS",
                    "startIndex": 1, "endIndex": 3,
                },
                "destinationIndex": 5,
            })
        );
    }

    /// The append boundary: `Q2` has 500 rows, so `--before 501` is the
    /// furthest legal destination — "move it to the very end" — and must
    /// not be refused the way `--before 502` is.
    #[tokio::test]
    async fn move_rows_to_the_end_uses_row_count_plus_one() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_move_prereqs(&server).await;
        mount_workbook().mount(&server).await;

        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::MoveRows {
                    sheet: "Q2".to_string(),
                    at: 1,
                    count: 1,
                    before: 501,
                },
                false,
            ),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(
            matches!(outcome.result, StructureResult::Changed { .. }),
            "{:?}",
            outcome.result
        );

        let requests = server.received_requests().await.unwrap();
        let body = sent_batch_update(&requests);
        assert_eq!(
            body["requests"][0]["moveDimension"]["destinationIndex"],
            500
        );
    }

    /// The source block must exist in full — `delete`'s rule, and the
    /// reason a move validates two spans rather than one.
    #[tokio::test]
    async fn move_rows_refuses_a_source_past_the_sheets_end() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_move_prereqs(&server).await;
        mount_workbook().mount(&server).await;

        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::MoveRows {
                    sheet: "Q2".to_string(),
                    at: 499,
                    count: 3,
                    before: 1,
                },
                false,
            ),
            &[allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result);
        };
        assert!(detail.contains("500 row(s)"), "{detail}");
        assert!(detail.contains("501"), "{detail}");
    }

    #[tokio::test]
    async fn move_rows_refuses_a_destination_past_the_end() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_move_prereqs(&server).await;
        mount_workbook().mount(&server).await;

        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::MoveRows {
                    sheet: "Q2".to_string(),
                    at: 5,
                    count: 1,
                    before: 502,
                },
                false,
            ),
            &[allow_rule("parent-1")],
        )
        .await;
        let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
            panic!("expected RefusedInvalidRange, got {:?}", outcome.result);
        };
        assert!(detail.contains("500 row(s)"), "{detail}");
        assert!(detail.contains("501"), "{detail}");
    }

    /// The refusal a move adds on top of insert's and delete's: for
    /// `--at 2 --count 2` the block occupies rows 2-3, and every
    /// `--before` in `2..=4` describes where it already is. Sheets accepts
    /// all three and changes nothing, so reporting "Moved" would be a
    /// lie — the "never promise a change the real run then rejects" rule
    /// read the other way round.
    #[tokio::test]
    async fn move_rows_refuses_a_destination_inside_or_adjacent_to_the_block() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_move_prereqs(&server).await;
        mount_workbook().mount(&server).await;

        for before in 2..=4 {
            let outcome = structure(
                &drive,
                &sheets,
                &opts(
                    StructureVerb::MoveRows {
                        sheet: "Q2".to_string(),
                        at: 2,
                        count: 2,
                        before,
                    },
                    false,
                ),
                &[allow_rule("parent-1")],
            )
            .await;
            let StructureResult::RefusedInvalidRange { detail } = &outcome.result else {
                panic!(
                    "expected RefusedInvalidRange for --before {before}, got {:?}",
                    outcome.result
                );
            };
            assert!(detail.contains("nothing would move"), "{detail}");
            assert!(detail.contains("rows 2-3"), "{detail}");
        }
    }

    /// The two values immediately outside that band, which must stay legal.
    /// For rows 2-3: `--before 1` is the smallest upward move (one position
    /// earlier) and `--before 5` the smallest downward one — `4` is the
    /// no-op boundary, so `5` is the first real move above the block, not
    /// `4`.
    #[tokio::test]
    async fn move_rows_allows_a_destination_immediately_adjacent_but_outside_the_block() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        // `dry_run: true` throughout: the point is the classification, and
        // a dry run issues no `batchUpdate` to mock.
        for before in [1, 5] {
            let outcome = structure(
                &drive,
                &sheets,
                &opts(
                    StructureVerb::MoveRows {
                        sheet: "Q2".to_string(),
                        at: 2,
                        count: 2,
                        before,
                    },
                    true,
                ),
                &[allow_rule("parent-1")],
            )
            .await;
            assert!(
                matches!(outcome.result, StructureResult::WouldChange { .. }),
                "--before {before} must be a real move, got {:?}",
                outcome.result
            );
        }
    }

    #[test]
    fn move_bounds_refuse_every_argument_below_one() {
        let sheet = SheetSnapshot {
            sheet_id: Some(1),
            title: "Q2".to_string(),
            row_count: Some(500),
            column_count: Some(26),
            ..Default::default()
        };
        for (at, count, before, expected) in [
            (2, 0, 9, "--count must be at least 1, got 0"),
            (0, 1, 9, "--at must be at least 1, got 0"),
            (2, 1, 0, "--before must be at least 1, got 0"),
        ] {
            let Err(StructureResult::RefusedInvalidRange { detail }) =
                validate_move_bounds(Dimension::Rows, at, count, before, Some(&sheet))
            else {
                panic!(
                    "expected RefusedInvalidRange for --at {at} --count {count} --before {before}"
                );
            };
            assert_eq!(detail, expected);
        }
    }

    #[test]
    fn a_move_at_and_count_that_would_overflow_the_index_space_are_refused() {
        let sheet = SheetSnapshot {
            sheet_id: Some(1),
            title: "Q2".to_string(),
            row_count: Some(500),
            column_count: Some(26),
            ..Default::default()
        };
        // `--before 1` throughout, so the overflow guard is what fires and
        // not the inside-the-block refusal that follows it.
        for (at, count) in [(i64::MAX, 5), (500, i64::MAX)] {
            let Err(StructureResult::RefusedInvalidRange { detail }) =
                validate_move_bounds(Dimension::Rows, at, count, 1, Some(&sheet))
            else {
                panic!("expected RefusedInvalidRange for --at {at} --count {count}");
            };
            assert!(detail.contains("overflows the row index space"), "{detail}");
        }
    }

    /// `record_attempt` builds a record from the very arguments
    /// `validate_move_bounds` just rejected, so `dimension_range_label`'s
    /// span arithmetic runs on them. Plain arithmetic panics here rather
    /// than in the mutation it refused to make — the
    /// `a_refused_out_of_range_insert_still_records_without_panicking`
    /// regression, for the move verbs.
    #[tokio::test]
    async fn a_refused_move_still_records_without_panicking() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;

        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::MoveRows {
                    sheet: "Q2".to_string(),
                    at: i64::MAX,
                    count: 5,
                    before: 1,
                },
                false,
            ),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(
            matches!(outcome.result, StructureResult::RefusedInvalidRange { .. }),
            "{:?}",
            outcome.result
        );
    }

    /// The dry run's second line is where `--before`'s pre-move numbering
    /// stops being a trap: rows 2-3 moved to before row 6 land on rows
    /// 4-5, because rows 4-5 slid up into the gap first.
    #[tokio::test]
    async fn move_rows_dry_run_describes_a_downward_move_and_its_landing_rows() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;

        let outcome = structure(
            &drive,
            &sheets,
            &opts(move_rows(), true),
            &[allow_rule("parent-1")],
        )
        .await;
        let lines = describe_lines(&outcome);
        assert_eq!(lines.len(), 2, "{lines:?}");
        assert!(lines[0].contains("Would move 2 row(s) 2-3"), "{lines:?}");
        assert!(lines[0].contains("to before row 6"), "{lines:?}");
        assert_eq!(
            lines[1],
            "  (500 rows unchanged; rows 4-5 shift up to 2-3; moved rows land at 4-5)"
        );
    }

    /// The mirror image: an upward move lands the block exactly on the
    /// number typed, and pushes everything from there to its old start
    /// forward by `--count`.
    #[tokio::test]
    async fn move_rows_dry_run_describes_an_upward_move_and_its_landing_rows() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;

        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::MoveRows {
                    sheet: "Q2".to_string(),
                    at: 6,
                    count: 2,
                    before: 2,
                },
                true,
            ),
            &[allow_rule("parent-1")],
        )
        .await;
        let lines = describe_lines(&outcome);
        assert_eq!(lines.len(), 2, "{lines:?}");
        assert!(lines[0].contains("Would move 2 row(s) 6-7"), "{lines:?}");
        assert!(lines[0].contains("to before row 2"), "{lines:?}");
        assert_eq!(
            lines[1],
            "  (500 rows unchanged; rows 2-5 shift down to 4-7; moved rows land at 2-3)"
        );
    }

    /// [`move_rows_dry_run_describes_a_downward_move_and_its_landing_rows`]'s
    /// twin on the other dimension, pinning `describe_would_move`'s
    /// `Dimension::Columns` wording (noun, plural, and `left`/`right`
    /// direction words) before the two branches are collapsed into one
    /// template.
    #[tokio::test]
    async fn move_columns_dry_run_describes_a_downward_move_and_its_landing_columns() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;

        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::MoveColumns {
                    sheet: "Q2".to_string(),
                    at: 2,
                    count: 2,
                    before: 6,
                },
                true,
            ),
            &[allow_rule("parent-1")],
        )
        .await;
        let lines = describe_lines(&outcome);
        assert_eq!(lines.len(), 2, "{lines:?}");
        assert!(lines[0].contains("Would move 2 column(s) 2-3"), "{lines:?}");
        assert!(lines[0].contains("to before column 6"), "{lines:?}");
        assert_eq!(
            lines[1],
            "  (10 columns unchanged; columns 4-5 shift left to 2-3; moved columns land at 4-5)"
        );
    }

    /// [`move_rows_dry_run_describes_an_upward_move_and_its_landing_rows`]'s
    /// twin on the other dimension — see the downward test above for why
    /// this pins the refactor.
    #[tokio::test]
    async fn move_columns_dry_run_describes_an_upward_move_and_its_landing_columns() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;

        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::MoveColumns {
                    sheet: "Q2".to_string(),
                    at: 6,
                    count: 2,
                    before: 2,
                },
                true,
            ),
            &[allow_rule("parent-1")],
        )
        .await;
        let lines = describe_lines(&outcome);
        assert_eq!(lines.len(), 2, "{lines:?}");
        assert!(lines[0].contains("Would move 2 column(s) 6-7"), "{lines:?}");
        assert!(lines[0].contains("to before column 2"), "{lines:?}");
        assert_eq!(
            lines[1],
            "  (10 columns unchanged; columns 2-5 shift right to 4-7; moved columns land at 2-3)"
        );
    }

    /// A preview and a real run share one classification by construction
    /// (the dry run returns after the gate, not before it), so a refusal
    /// must read identically either way — `--dry-run` may never promise a
    /// move the real run then refuses.
    #[tokio::test]
    async fn move_rows_dry_run_matches_the_real_run_refusal() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_move_prereqs(&server).await;
        mount_workbook().mount(&server).await;

        let verb = StructureVerb::MoveRows {
            sheet: "Q2".to_string(),
            at: 5,
            count: 1,
            before: 502,
        };
        let real = structure(
            &drive,
            &sheets,
            &opts(verb.clone(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        let dry = structure(
            &drive,
            &sheets,
            &opts(verb, true),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(
            matches!(real.result, StructureResult::RefusedInvalidRange { .. }),
            "{:?}",
            real.result
        );
        assert_eq!(dry.result, real.result);
    }

    /// Frozen panes are Sheets' own business. `moveDimension` interacts with
    /// them server-side (a frozen band does not travel with the move), and
    /// no client-side check here may grow around that: the request must be
    /// byte-identical to the one sent against a sheet with no frozen rows,
    /// and the move must not be refused. ADR-0073 §7's rule — Sheets is the
    /// authority on its own semantics.
    #[tokio::test]
    async fn move_rows_does_not_consult_frozen_rows() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_move_prereqs(&server).await;
        mount_workbook_with_q2(serde_json::json!({
            "properties": {
                "sheetId": 118_293, "title": "Q2", "index": 1,
                "gridProperties": {
                    "rowCount": 500, "columnCount": 10, "frozenRowCount": 2,
                },
            },
        }))
        .mount(&server)
        .await;

        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::MoveRows {
                    sheet: "Q2".to_string(),
                    at: 1,
                    count: 1,
                    before: 3,
                },
                false,
            ),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(
            matches!(outcome.result, StructureResult::Changed { .. }),
            "{:?}",
            outcome.result
        );

        let requests = server.received_requests().await.unwrap();
        let body = sent_batch_update(&requests);
        assert_eq!(
            body["requests"][0]["moveDimension"],
            serde_json::json!({
                "source": {
                    "sheetId": 118_293, "dimension": "ROWS",
                    "startIndex": 0, "endIndex": 1,
                },
                "destinationIndex": 2,
            })
        );
    }

    /// The same claim for row/column groups: an outline group whose range
    /// spans the block being moved is state this engine never reads, so it
    /// can neither refuse nor reshape the request. Sheets resolves what
    /// happens to the group.
    #[tokio::test]
    async fn move_rows_does_not_consult_dimension_groups() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_move_prereqs(&server).await;
        mount_workbook_with_q2(serde_json::json!({
            "properties": {
                "sheetId": 118_293, "title": "Q2", "index": 1,
                "gridProperties": {"rowCount": 500, "columnCount": 10},
            },
            "rowGroups": [{
                "range": {
                    "sheetId": 118_293, "dimension": "ROWS",
                    "startIndex": 1, "endIndex": 4,
                },
            }],
        }))
        .mount(&server)
        .await;

        let outcome = structure(
            &drive,
            &sheets,
            &opts(
                StructureVerb::MoveRows {
                    sheet: "Q2".to_string(),
                    at: 2,
                    count: 1,
                    before: 1,
                },
                false,
            ),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(
            matches!(outcome.result, StructureResult::Changed { .. }),
            "{:?}",
            outcome.result
        );

        let requests = server.received_requests().await.unwrap();
        let body = sent_batch_update(&requests);
        assert_eq!(
            body["requests"][0]["moveDimension"],
            serde_json::json!({
                "source": {
                    "sheetId": 118_293, "dimension": "ROWS",
                    "startIndex": 1, "endIndex": 2,
                },
                "destinationIndex": 0,
            })
        );
    }

    // ── update-workbook-properties (issue #1836) ────────────────────────

    #[test]
    fn sheet_title_is_none_for_update_workbook_properties() {
        assert_eq!(update_workbook_properties().sheet_title(), None);
        assert_eq!(update_workbook_properties().new_sheet_title(), None);
        assert_eq!(update_workbook_properties().dimension(), None);
    }

    #[test]
    fn resolve_sheet_returns_none_for_update_workbook_properties_without_consulting_sheets() {
        // An empty `sheets` list would make every other verb's
        // `resolve_sheet` fail with `RefusedSheetNotFound` — this verb must
        // return `Ok(None)` regardless, since it never looks.
        let workbook = Spreadsheet {
            spreadsheet_id: Some("sheet-1".to_string()),
            properties: None,
            sheets: Vec::new(),
            named_ranges: Vec::new(),
        };
        assert_eq!(
            resolve_sheet(&workbook, &update_workbook_properties()),
            Ok(None)
        );
    }

    #[test]
    fn validate_verb_args_refuses_update_workbook_properties_with_no_fields() {
        let verb = StructureVerb::UpdateWorkbookProperties {
            locale: None,
            time_zone: None,
            auto_recalc: None,
            iterative_calculation: None,
            iterative_calculation_max_iterations: None,
            iterative_calculation_convergence_threshold: None,
        };
        let workbook = Spreadsheet::default();
        let err = validate_verb_args(&workbook, &verb, None).unwrap_err();
        assert!(
            matches!(&err, StructureResult::RefusedInvalidRange { detail }
                if detail.contains("at least one property")),
            "{err:?}"
        );
    }

    fn update_time_zone(time_zone: &str) -> StructureVerb {
        StructureVerb::UpdateWorkbookProperties {
            locale: None,
            time_zone: Some(time_zone.to_string()),
            auto_recalc: None,
            iterative_calculation: None,
            iterative_calculation_max_iterations: None,
            iterative_calculation_convergence_threshold: None,
        }
    }

    #[test]
    fn validate_verb_args_refuses_an_unrecognised_time_zone() {
        // The API accepts this with a 200 and resets the workbook to
        // `Etc/GMT` (issue #1938), so the refusal has to be local.
        let workbook = Spreadsheet::default();
        let err =
            validate_verb_args(&workbook, &update_time_zone("Bogus/Zone9"), None).unwrap_err();
        assert!(
            matches!(&err, StructureResult::RefusedInvalidRange { detail }
                if detail.contains("'Bogus/Zone9'")
                    && detail.contains("IANA")
                    && detail.contains("America/New_York")),
            "{err:?}"
        );
    }

    #[test]
    fn validate_verb_args_accepts_recognised_iana_time_zones() {
        let workbook = Spreadsheet::default();
        for tz in ["Europe/London", "America/New_York", "Etc/GMT", "UTC"] {
            assert_eq!(
                validate_verb_args(&workbook, &update_time_zone(tz), None),
                Ok(()),
                "{tz}"
            );
        }
    }

    #[test]
    fn validate_verb_args_refuses_iterative_calculation_settings_without_the_toggle() {
        let verb = StructureVerb::UpdateWorkbookProperties {
            locale: None,
            time_zone: None,
            auto_recalc: None,
            iterative_calculation: None,
            iterative_calculation_max_iterations: Some(50),
            iterative_calculation_convergence_threshold: None,
        };
        let workbook = Spreadsheet::default();
        let err = validate_verb_args(&workbook, &verb, None).unwrap_err();
        assert!(
            matches!(&err, StructureResult::RefusedInvalidRange { detail }
                if detail.contains("--iterative-calculation on")),
            "{err:?}"
        );

        // Also refused when explicitly turning it *off*.
        let verb_off = StructureVerb::UpdateWorkbookProperties {
            locale: None,
            time_zone: None,
            auto_recalc: None,
            iterative_calculation: Some(IterativeCalculationToggle::Off),
            iterative_calculation_max_iterations: Some(50),
            iterative_calculation_convergence_threshold: None,
        };
        assert!(validate_verb_args(&workbook, &verb_off, None).is_err());
    }

    #[test]
    fn validate_verb_args_refuses_non_positive_iterative_calculation_bounds() {
        let workbook = Spreadsheet::default();
        let bad_max = StructureVerb::UpdateWorkbookProperties {
            locale: None,
            time_zone: None,
            auto_recalc: None,
            iterative_calculation: Some(IterativeCalculationToggle::On),
            iterative_calculation_max_iterations: Some(0),
            iterative_calculation_convergence_threshold: None,
        };
        assert!(validate_verb_args(&workbook, &bad_max, None).is_err());

        let bad_threshold = StructureVerb::UpdateWorkbookProperties {
            locale: None,
            time_zone: None,
            auto_recalc: None,
            iterative_calculation: Some(IterativeCalculationToggle::On),
            iterative_calculation_max_iterations: None,
            iterative_calculation_convergence_threshold: Some(0.0),
        };
        assert!(validate_verb_args(&workbook, &bad_threshold, None).is_err());

        let nan_threshold = StructureVerb::UpdateWorkbookProperties {
            locale: None,
            time_zone: None,
            auto_recalc: None,
            iterative_calculation: Some(IterativeCalculationToggle::On),
            iterative_calculation_max_iterations: None,
            iterative_calculation_convergence_threshold: Some(f64::NAN),
        };
        assert!(validate_verb_args(&workbook, &nan_threshold, None).is_err());
    }

    #[test]
    fn validate_verb_args_accepts_positive_iterative_calculation_bounds() {
        let workbook = Spreadsheet::default();
        let verb = StructureVerb::UpdateWorkbookProperties {
            locale: None,
            time_zone: None,
            auto_recalc: None,
            iterative_calculation: Some(IterativeCalculationToggle::On),
            iterative_calculation_max_iterations: Some(50),
            iterative_calculation_convergence_threshold: Some(0.01),
        };
        assert!(validate_verb_args(&workbook, &verb, None).is_ok());
    }

    #[test]
    fn validate_verb_args_accepts_a_single_field() {
        let workbook = Spreadsheet::default();
        let verb = StructureVerb::UpdateWorkbookProperties {
            locale: Some("fr_FR".to_string()),
            time_zone: None,
            auto_recalc: None,
            iterative_calculation: None,
            iterative_calculation_max_iterations: None,
            iterative_calculation_convergence_threshold: None,
        };
        assert!(validate_verb_args(&workbook, &verb, None).is_ok());
    }

    #[test]
    fn build_request_masks_exactly_the_fields_given() {
        let verb = StructureVerb::UpdateWorkbookProperties {
            locale: Some("en_US".to_string()),
            time_zone: None,
            auto_recalc: Some(RecalculationInterval::Hour),
            iterative_calculation: None,
            iterative_calculation_max_iterations: None,
            iterative_calculation_convergence_threshold: None,
        };
        let request = build_request(&verb, None).unwrap();
        let BatchUpdateRequestItem::UpdateSpreadsheetProperties(req) = request else {
            panic!("expected UpdateSpreadsheetProperties, got {request:?}"); // omni-dev: coverage ignore-line reason="build_request always returns UpdateSpreadsheetProperties for an UpdateWorkbookProperties verb, so this else-arm exists only to unwrap the shared enum"
        };
        assert_eq!(req.fields, "locale,autoRecalc");
        assert_eq!(req.properties.locale.as_deref(), Some("en_US"));
        assert_eq!(req.properties.time_zone, None);
        assert_eq!(
            req.properties.auto_recalc,
            Some(RecalculationInterval::Hour)
        );
        assert_eq!(req.properties.iterative_calculation_settings, None);
    }

    #[test]
    fn build_request_turns_iterative_calculation_on_with_explicit_settings() {
        let verb = StructureVerb::UpdateWorkbookProperties {
            locale: None,
            time_zone: None,
            auto_recalc: None,
            iterative_calculation: Some(IterativeCalculationToggle::On),
            iterative_calculation_max_iterations: Some(50),
            iterative_calculation_convergence_threshold: Some(0.01),
        };
        let request = build_request(&verb, None).unwrap();
        let BatchUpdateRequestItem::UpdateSpreadsheetProperties(req) = request else {
            panic!("expected UpdateSpreadsheetProperties, got {request:?}"); // omni-dev: coverage ignore-line reason="build_request always returns UpdateSpreadsheetProperties for an UpdateWorkbookProperties verb, so this else-arm exists only to unwrap the shared enum"
        };
        assert_eq!(req.fields, "iterativeCalculationSettings");
        assert_eq!(
            req.properties.iterative_calculation_settings,
            Some(IterativeCalculationSettings {
                max_iterations: Some(50),
                convergence_threshold: Some(0.01),
            })
        );
    }

    #[test]
    fn build_request_turns_iterative_calculation_off_by_naming_the_field_without_a_value() {
        // The field-mask idiom `IterativeCalculationSettings`'s doc comment
        // describes: `fields` names the property, but
        // `iterative_calculation_settings` itself stays `None`, so it is
        // omitted from the JSON body and the server clears it.
        let verb = StructureVerb::UpdateWorkbookProperties {
            locale: None,
            time_zone: None,
            auto_recalc: None,
            iterative_calculation: Some(IterativeCalculationToggle::Off),
            iterative_calculation_max_iterations: None,
            iterative_calculation_convergence_threshold: None,
        };
        let request = build_request(&verb, None).unwrap();
        let BatchUpdateRequestItem::UpdateSpreadsheetProperties(req) = request else {
            panic!("expected UpdateSpreadsheetProperties, got {request:?}"); // omni-dev: coverage ignore-line reason="build_request always returns UpdateSpreadsheetProperties for an UpdateWorkbookProperties verb, so this else-arm exists only to unwrap the shared enum"
        };
        assert_eq!(req.fields, "iterativeCalculationSettings");
        assert_eq!(req.properties.iterative_calculation_settings, None);
        let json = serde_json::to_value(&req.properties).unwrap();
        assert!(
            json.as_object().unwrap().is_empty(),
            "expected an empty properties object, got {json}"
        );
    }

    #[test]
    fn workbook_properties_summary_formats_every_field() {
        let verb = StructureVerb::UpdateWorkbookProperties {
            locale: Some("en_US".to_string()),
            time_zone: Some("America/New_York".to_string()),
            auto_recalc: Some(RecalculationInterval::OnChange),
            iterative_calculation: Some(IterativeCalculationToggle::On),
            iterative_calculation_max_iterations: Some(50),
            iterative_calculation_convergence_threshold: Some(0.01),
        };
        let summary = workbook_properties_summary(&verb);
        assert_eq!(
            summary,
            "locale -> 'en_US', time zone -> 'America/New_York', \
             auto-recalc -> ON_CHANGE, iterative calculation -> on \
             (max 50 iterations, threshold 0.01)"
        );
    }

    #[tokio::test]
    async fn update_workbook_properties_dry_run_reports_would_change_with_no_sheet() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;

        let outcome = structure(
            &drive,
            &sheets,
            &opts(update_workbook_properties(), true),
            &[allow_rule("parent-1")],
        )
        .await;
        match &outcome.result {
            StructureResult::WouldChange { sheet, sheet_count } => {
                assert_eq!(*sheet, None);
                assert_eq!(*sheet_count, 2);
            }
            other => panic!("expected WouldChange, got {other:?}"), // omni-dev: coverage ignore-line reason="guards this test's assumption; a dry run against an allowed target always reaches WouldChange here"
        }
        let lines = describe_lines(&outcome);
        assert_eq!(lines.len(), 1);
        assert!(
            lines[0].starts_with("Would update workbook properties of 'sheet-1'"),
            "{lines:?}"
        );

        // A dry run reads the workbook (to report `sheet_count` honestly)
        // but never calls `batchUpdate`.
        let requests = server.received_requests().await.unwrap();
        assert!(!requests
            .iter()
            .any(|r| r.url.path().ends_with(":batchUpdate")));
    }

    #[tokio::test]
    async fn update_workbook_properties_refuses_an_unrecognised_time_zone_on_dry_run_and_apply() {
        // Issue #1938: a dry run used to report "would change" for a zone the
        // API silently replaces with `Etc/GMT`. Both paths now refuse it.
        for dry_run in [true, false] {
            let server = wiremock::MockServer::start().await;
            let (drive, sheets) = clients(&server).await;
            mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
                .mount(&server)
                .await;
            mount_folder("parent-1").mount(&server).await;
            mount_workbook().mount(&server).await;

            let outcome = structure(
                &drive,
                &sheets,
                &opts(update_time_zone("Bogus/Zone9"), dry_run),
                &[allow_rule("parent-1")],
            )
            .await;
            assert!(
                matches!(&outcome.result, StructureResult::RefusedInvalidRange { detail }
                    if detail.contains("'Bogus/Zone9'")),
                "dry_run={dry_run}: {:?}",
                outcome.result
            );
            let requests = server.received_requests().await.unwrap();
            assert!(
                !requests
                    .iter()
                    .any(|r| r.url.path().ends_with(":batchUpdate")),
                "dry_run={dry_run}"
            );
        }
    }

    #[tokio::test]
    async fn update_workbook_properties_apply_sends_the_masked_request_and_reports_changed() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;

        let outcome = structure(
            &drive,
            &sheets,
            &opts(update_workbook_properties(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        match &outcome.result {
            StructureResult::Changed {
                sheet, sheet_id, ..
            } => {
                assert_eq!(*sheet, None);
                assert_eq!(*sheet_id, None);
            }
            other => panic!("expected Changed, got {other:?}"), // omni-dev: coverage ignore-line reason="guards this test's assumption; an apply against an allowed target with a mocked batchUpdate always reaches Changed here"
        }

        let requests = server.received_requests().await.unwrap();
        let body = sent_batch_update(&requests);
        let update = &body["requests"][0]["updateSpreadsheetProperties"];
        assert_eq!(update["properties"]["locale"], "en_US");
        assert_eq!(update["properties"]["timeZone"], "America/New_York");
        assert_eq!(update["properties"]["autoRecalc"], "ON_CHANGE");
        assert_eq!(update["fields"], "locale,timeZone,autoRecalc");
    }

    #[test]
    fn record_attempt_carries_the_fields_changed_summary_and_no_sheet_title() {
        let opts = opts(update_workbook_properties(), false);
        assert_eq!(opts.verb.sheet_title(), None);
        assert_eq!(
            workbook_properties_summary(&opts.verb),
            "locale -> 'en_US', time zone -> 'America/New_York', auto-recalc -> ON_CHANGE"
        );
    }

    // ── plumbing ───────────────────────────────────────────────────────

    #[test]
    fn log_operation_is_distinct_per_verb() {
        let verbs = [
            add_sheet(),
            rename(),
            insert_rows(),
            StructureVerb::InsertColumns {
                sheet: "Q2".to_string(),
                at: 1,
                count: 1,
            },
            insert_range(),
            move_rows(),
            StructureVerb::MoveColumns {
                sheet: "Q2".to_string(),
                at: 1,
                count: 1,
                before: 3,
            },
            delete_sheet(),
            delete_rows(),
            StructureVerb::DeleteColumns {
                sheet: "Q2".to_string(),
                at: 1,
                count: 1,
            },
            delete_range(),
            duplicate_sheet(),
            reorder_sheet(),
            hide_sheet(),
            show_sheet(),
            update_workbook_properties(),
        ];
        let names: Vec<&str> = verbs.iter().map(StructureVerb::log_operation).collect();
        assert_eq!(
            names,
            vec![
                "sheets-add-sheet",
                "sheets-rename-sheet",
                "sheets-insert-rows",
                "sheets-insert-columns",
                "sheets-insert-range",
                "sheets-move-rows",
                "sheets-move-columns",
                "sheets-delete-sheet",
                "sheets-delete-rows",
                "sheets-delete-columns",
                "sheets-delete-range",
                "sheets-duplicate-sheet",
                "sheets-reorder-sheet",
                "sheets-hide-sheet",
                "sheets-show-sheet",
                "sheets-update-workbook-properties",
            ]
        );
        // One record per user-visible verb means the operations must not
        // collide with each other or with the cell verbs.
        let unique: HashSet<&&str> = names.iter().collect();
        assert_eq!(unique.len(), names.len());
        assert!(!names.contains(&"sheets-write"));
    }

    #[test]
    fn insert_range_records_its_one_based_inclusive_grid_context() {
        assert_eq!(
            grid_range_label(&insert_range()).as_deref(),
            Some("rows 2-4, columns 2-3")
        );
    }

    /// One of every [`StructureResult`] variant.
    ///
    /// Exhaustive and wildcard-free on purpose, mirroring `write.rs`'s
    /// `every_write_result`: adding a variant breaks this build, which is
    /// what forces the new arm through the newline check below.
    fn every_structure_result() -> Vec<StructureResult> {
        let all = vec![
            StructureResult::WouldChange {
                sheet: Some(Box::new(SheetSnapshot {
                    sheet_id: Some(7),
                    title: "Q2".to_string(),
                    row_count: Some(500),
                    column_count: Some(26),
                    ..Default::default()
                })),
                sheet_count: 2,
            },
            StructureResult::RefusedNotASpreadsheet {
                mime_type: "application/pdf".to_string(),
            },
            StructureResult::RefusedShortcut,
            StructureResult::RefusedNoVisibleParents,
            StructureResult::RefusedSheetNotFound {
                title: "Nope".to_string(),
                available: vec!["Q1".to_string(), "Q2".to_string()],
            },
            StructureResult::RefusedSheetExists {
                title: "Q1".to_string(),
            },
            StructureResult::RefusedInvalidRange {
                detail: "--count must be at least 1, got 0".to_string(),
            },
            StructureResult::Blocked { decided_by: None },
            StructureResult::RefusedNoLease,
            StructureResult::RefusedLeaseExpired,
            StructureResult::RefusedLeaseWrongFile,
            StructureResult::RefusedLeaseStale,
            StructureResult::Unchanged {
                detail: "sheet 'Q2' is already hidden".to_string(),
            },
            StructureResult::Changed {
                sheet: Some(Box::new(SheetSnapshot {
                    sheet_id: Some(7),
                    title: "Q2".to_string(),
                    row_count: Some(500),
                    column_count: Some(26),
                    ..Default::default()
                })),
                sheet_id: Some(7),
                backup: Some(Box::new(LeaseBackup::DriveCopy {
                    file_id: "backup-copy-1".to_string(),
                })),
            },
            StructureResult::Failed {
                detail: "boom".to_string(),
            },
        ];
        // Compile-time exhaustiveness: a new variant fails to match here.
        for result in &all {
            match result {
                StructureResult::WouldChange { .. }
                | StructureResult::RefusedNotASpreadsheet { .. }
                | StructureResult::RefusedShortcut
                | StructureResult::RefusedNoVisibleParents
                | StructureResult::RefusedSheetNotFound { .. }
                | StructureResult::RefusedSheetExists { .. }
                | StructureResult::RefusedInvalidRange { .. }
                | StructureResult::Blocked { .. }
                | StructureResult::RefusedNoLease
                | StructureResult::RefusedLeaseExpired
                | StructureResult::RefusedLeaseWrongFile
                | StructureResult::RefusedLeaseStale
                | StructureResult::Unchanged { .. }
                | StructureResult::Changed { .. }
                | StructureResult::Failed { .. } => {}
            }
        }
        all
    }

    /// No `describe_lines` line ever contains a newline, and the insert
    /// preview is the only arm that emits a second line.
    ///
    /// Both halves are load-bearing, and they are different claims. The
    /// second is presentation: `write.rs`/`create.rs` pin every arm to one
    /// line, and a structural insert earns its extra one because the shift is
    /// the substance of the dry run (ADR-0075 §6).
    ///
    /// The first is what makes `cli::drive::sheets::structure`'s sanitizing
    /// sound. Every line here interpolates untrusted text — a Drive-supplied
    /// file name, workbook sheet titles, raw API error details — and the CLI
    /// strips control characters from each line before supplying the
    /// separators itself. That is only equivalent to filtering each
    /// interpolation while this module contributes no newline of its own: a
    /// line built with an embedded `\n` would smuggle a separator past the
    /// filter and let an injected one pass for a real one.
    ///
    /// The wildcard-free `every_structure_result` is the other half — a new
    /// variant will not compile until it is listed there, so it cannot reach
    /// the terminal without passing through this check.
    #[test]
    fn no_describe_line_contains_a_newline() {
        for verb in [
            add_sheet(),
            rename(),
            insert_rows(),
            StructureVerb::InsertColumns {
                sheet: "Q2".to_string(),
                at: 2,
                count: 1,
            },
            move_rows(),
            StructureVerb::MoveColumns {
                sheet: "Q2".to_string(),
                at: 2,
                count: 1,
                before: 5,
            },
            delete_sheet(),
            delete_rows(),
            delete_columns(),
            insert_range(),
            insert_range_columns_shift(),
            delete_range(),
            delete_range_columns_shift(),
            duplicate_sheet(),
            duplicate_sheet_default(),
            reorder_sheet(),
            hide_sheet(),
            show_sheet(),
            update_workbook_properties(),
        ] {
            // A verb with a single axis (insert, delete-dimension or
            // move-dimension) earns a second `WouldChange` line for the
            // shift; every other verb, additive or destructive, stays one
            // line.
            let has_dimension_shift = verb.dimension().is_some();
            for result in every_structure_result() {
                let previews_an_insert =
                    has_dimension_shift && matches!(result, StructureResult::WouldChange { .. });
                let outcome = StructureOutcome {
                    spreadsheet_id: "sheet-1".to_string(),
                    file_name: Some("Budget".to_string()),
                    resolved_folder_id: None,
                    verb: verb.clone(),
                    result,
                };
                let lines = describe_lines(&outcome);
                assert_eq!(
                    lines.len(),
                    usize::from(previews_an_insert) + 1,
                    "unexpected line count for {:?}/{:?}: {lines:?}",
                    outcome.verb,
                    outcome.result
                );
                for rendered in &lines {
                    assert!(
                        !rendered.chars().any(char::is_control),
                        "describe_lines emitted a control character for {:?}/{:?}: \
                         {rendered:?}",
                        outcome.verb,
                        outcome.result
                    );
                }
                // `describe` is the join, so it reconstructs exactly the
                // separators the CLI would supply and nothing else.
                assert_eq!(describe(&outcome), lines.join("\n"));
            }
        }
    }

    /// [`describe_would_delete_dimension`]'s own defensive branches, reached
    /// with arguments `validate_verb_args` would already have refused (an
    /// overflowing `--at`/`--count`) or a workbook snapshot the real pipeline
    /// never hands it (`sheet: None`, or a size too small to subtract
    /// `count` from) — the `describe_lines(&outcome)` bypass used above lets
    /// a test construct exactly that, the same way
    /// `dimension_range_label_omits_a_span_it_cannot_compute` does for
    /// `record_attempt`'s logging path.
    #[test]
    fn describe_would_delete_dimension_handles_unvalidated_edge_cases() {
        let would_change = |verb: StructureVerb, sheet: Option<SheetSnapshot>| StructureOutcome {
            spreadsheet_id: "sheet-1".to_string(),
            file_name: Some("Budget".to_string()),
            resolved_folder_id: None,
            verb,
            result: StructureResult::WouldChange {
                sheet: sheet.map(Box::new),
                sheet_count: 2,
            },
        };
        // `sheet_id: None` keeps every expected string free of the
        // `(sheetId N)` suffix, which is orthogonal to what this test checks.
        let sheet_with_columns = |column_count| SheetSnapshot {
            sheet_id: None,
            title: "Q2".to_string(),
            row_count: None,
            column_count: Some(column_count),
            ..Default::default()
        };

        // `--at`/`--count` overflowing the `last` computation: no dash-range
        // or shift line, just the plain summary.
        let overflow = describe(&would_change(
            StructureVerb::DeleteColumns {
                sheet: "Q2".to_string(),
                at: i64::MAX,
                count: 2,
            },
            Some(sheet_with_columns(26)),
        ));
        assert!(
            overflow.contains("Would delete 2 column(s) from column"),
            "{overflow}"
        );
        assert!(!overflow.contains('-'), "{overflow}");

        // No sheet snapshot at all: the shift line needs a real "before"
        // size, so it is omitted rather than guessed.
        let no_sheet = describe(&would_change(delete_columns(), None));
        assert_eq!(no_sheet, "Would delete 2 column(s) 3-4 of 'Q2' in 'Budget'");

        // A `before` too small for `count` to subtract from without
        // underflowing `i64::MIN`: also omitted rather than reported wrong.
        let after_underflows = describe(&would_change(
            StructureVerb::DeleteColumns {
                sheet: "Q2".to_string(),
                at: 0,
                count: i64::MAX,
            },
            Some(sheet_with_columns(-2)),
        ));
        assert_eq!(
            after_underflows,
            format!(
                "Would delete {} column(s) 0-{} of 'Q2' in 'Budget'",
                i64::MAX,
                i64::MAX - 1
            )
        );

        // Deleting exactly through the sheet's last column: "nothing
        // remains", not an inverted "existing N-M shift".
        let to_the_end = describe(&would_change(
            StructureVerb::DeleteColumns {
                sheet: "Q2".to_string(),
                at: 25,
                count: 2,
            },
            Some(sheet_with_columns(26)),
        ));
        assert!(
            to_the_end.contains("nothing remains after the deleted columns"),
            "{to_the_end}"
        );
    }

    #[test]
    fn log_status_covers_every_variant() {
        let statuses = [
            StructureResult::WouldChange {
                sheet: None,
                sheet_count: 1,
            }
            .log_status(),
            StructureResult::RefusedNotASpreadsheet {
                mime_type: "application/pdf".to_string(),
            }
            .log_status(),
            StructureResult::RefusedShortcut.log_status(),
            StructureResult::RefusedNoVisibleParents.log_status(),
            StructureResult::RefusedSheetNotFound {
                title: "x".to_string(),
                available: Vec::new(),
            }
            .log_status(),
            StructureResult::RefusedSheetExists {
                title: "x".to_string(),
            }
            .log_status(),
            StructureResult::RefusedInvalidRange {
                detail: "x".to_string(),
            }
            .log_status(),
            StructureResult::Blocked { decided_by: None }.log_status(),
            StructureResult::RefusedNoLease.log_status(),
            StructureResult::RefusedLeaseExpired.log_status(),
            StructureResult::RefusedLeaseWrongFile.log_status(),
            StructureResult::RefusedLeaseStale.log_status(),
            StructureResult::Unchanged {
                detail: "x".to_string(),
            }
            .log_status(),
            StructureResult::Changed {
                sheet: None,
                sheet_id: None,
                backup: None,
            }
            .log_status(),
            StructureResult::Failed {
                detail: "x".to_string(),
            }
            .log_status(),
        ];
        let unique: HashSet<&&str> = statuses.iter().collect();
        assert_eq!(unique.len(), statuses.len(), "statuses must be distinct");
        assert!(statuses.iter().all(|s| !s.is_empty()));
    }

    #[test]
    fn a_verdict_of_allow_is_what_lets_a_run_proceed() {
        // Pins the gate's vocabulary this module depends on, so a rename of
        // the enum can't silently invert the check above.
        assert_ne!(Verdict::Allow, Verdict::Deny);
    }

    #[test]
    fn build_request_fails_rather_than_guessing_a_missing_sheet_id() {
        // Sheet id 0 is a real sheet (the first tab), so defaulting would
        // aim a rename at the wrong tab.
        let sheet = SheetSnapshot {
            sheet_id: None,
            title: "Q2".to_string(),
            row_count: None,
            column_count: None,
            ..Default::default()
        };
        let err = build_request(&rename(), Some(&sheet)).unwrap_err();
        assert!(err.contains("sheetId"), "{err}");
    }

    #[test]
    fn added_sheet_id_reads_the_add_sheet_reply_only() {
        let empty: BatchUpdateResponse =
            serde_json::from_value(serde_json::json!({"spreadsheetId": "s", "replies": [{}]}))
                .unwrap();
        assert_eq!(added_sheet_id(&empty), None);
        let added: BatchUpdateResponse = serde_json::from_value(serde_json::json!({
            "replies": [{"addSheet": {"properties": {"sheetId": 42, "title": "New"}}}]
        }))
        .unwrap();
        assert_eq!(added_sheet_id(&added), Some(42));
    }

    // ── file-id rules (issue #1612) ────────────────────────────────────

    #[tokio::test]
    async fn a_file_rule_grants_a_sheet_with_no_visible_parents() {
        // The case issue #1612 exists for: before file rules there was no
        // rule an operator could write that would permit this at all.
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &[])
            .mount(&server)
            .await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .expect(1)
            .mount(&server)
            .await;

        let outcome = structure(
            &drive,
            &sheets,
            &opts(rename(), false),
            &[FolderPermissionRule::file("sheet-1").allowing([DriveOperation::SheetsStructure])],
        )
        .await;

        assert!(
            matches!(outcome.result, StructureResult::Changed { .. }),
            "{:?}",
            outcome.result
        );
    }

    #[tokio::test]
    async fn a_file_rule_denies_even_when_a_parent_folder_would_allow() {
        // Depth −1 beats depth 0 in the restrictive direction too.
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        // No mock for parent-1 and none for any Sheets endpoint: the file
        // rule must decide before either is reached.

        let outcome = structure(
            &drive,
            &sheets,
            &opts(rename(), false),
            &[
                allow_rule("parent-1"),
                FolderPermissionRule::file("sheet-1").denying([DriveOperation::SheetsStructure]),
            ],
        )
        .await;

        match &outcome.result {
            StructureResult::Blocked { decided_by } => {
                let rule = decided_by.as_ref().expect("a file rule decided this");
                assert_eq!(rule.kind_label(), "file");
                assert_eq!(rule.id(), "sheet-1");
            }
            other => panic!("expected Blocked, got {other:?}"),
        }
        let text = describe(&outcome);
        assert!(text.contains("refused by rule on file sheet-1"), "{text}");
        assert!(!text.contains("depth"), "a file rule has no depth: {text}");
    }

    #[tokio::test]
    async fn the_no_visible_parents_message_names_a_file_rule_as_the_fix() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &[])
            .mount(&server)
            .await;
        let outcome = structure(&drive, &sheets, &opts(rename(), false), &[]).await;
        let text = describe(&outcome);
        assert!(text.contains("file_id"), "{text}");
        assert!(text.contains("sheets-structure"), "{text}");
    }

    // ── the write's own audit trail (ADR-0080 §11) ─────────────────────

    #[tokio::test]
    async fn a_leased_structure_change_concludes_its_audit_pair_with_allowed() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        mount_workbook().mount(&server).await;
        mount_batch_update(serde_json::json!({"spreadsheetId": "sheet-1", "replies": [{}]}))
            .mount(&server)
            .await;
        let dir = tempfile::tempdir().unwrap();
        let audit = crate::test_support::AuditLogGuard::redirect(dir.path());
        let verb = StructureVerb::RenameSheet {
            sheet: "Q2".to_string(),
            new_title: "Q2 (final)".to_string(),
        };

        let outcome = structure(
            &drive,
            &sheets,
            &opts(verb, false),
            &[allow_rule("parent-1")],
        )
        .await;
        assert!(matches!(outcome.result, StructureResult::Changed { .. }));

        let records = audit.records();
        assert_eq!(audit.verdicts(), ["pending", "allowed"], "{records:?}");
        // The verb, not the engine — the same `["drive", <log_operation>]`
        // this write's `drivemutation` record carries, so an auditor can
        // see which verb ran without joining back to `log.jsonl`.
        assert_eq!(records[0].command, ["drive", "sheets-rename-sheet"]);
    }

    /// #1688: a sheet that resolved by title but reported no `sheetId` (a
    /// server contract violation, see [`build_request_fails_rather_than_guessing_a_missing_sheet_id`])
    /// is exactly the case `build_request` refuses on — and it must never
    /// open a `pending` audit record for a write that can never be issued.
    /// `build_request_fails_rather_than_guessing_a_missing_sheet_id` covers
    /// the pure function; this covers the engine path through it, which was
    /// untested before this fix (the bug this test guards against left the
    /// `pending` record unconcluded).
    #[tokio::test]
    async fn a_missing_sheet_id_fails_before_opening_the_audit_pair() {
        let server = wiremock::MockServer::start().await;
        let (drive, sheets) = clients(&server).await;
        mount_file("sheet-1", GOOGLE_SHEET_MIME_TYPE, &["parent-1"])
            .mount(&server)
            .await;
        mount_folder("parent-1").mount(&server).await;
        wiremock::Mock::given(wiremock::matchers::method("GET"))
            .and(wiremock::matchers::path("/v4/spreadsheets/sheet-1"))
            .respond_with(
                wiremock::ResponseTemplate::new(200).set_body_json(serde_json::json!({
                    "spreadsheetId": "sheet-1",
                    "properties": {"title": "Budget"},
                    "sheets": [
                        {"properties": {"title": "Q2", "index": 0}}
                    ],
                })),
            )
            .mount(&server)
            .await;
        // No batchUpdate mock mounted: `build_request`'s own missing-`sheetId`
        // check is the one that must catch this, before any mutating call.
        let dir = tempfile::tempdir().unwrap();
        let audit = crate::test_support::AuditLogGuard::redirect(dir.path());

        let outcome = structure(
            &drive,
            &sheets,
            &opts(rename(), false),
            &[allow_rule("parent-1")],
        )
        .await;
        match outcome.result {
            StructureResult::Failed { detail } => {
                assert!(detail.contains("sheetId"), "{detail}");
            }
            other => panic!("expected Failed, got {other:?}"),
        }
        assert!(audit.records().is_empty(), "{:?}", audit.records());
    }
}