formualizer_eval/engine/

eval.rs

use crate::SheetId;
use crate::arrow_store::{OverlayFragment, OverlayValue, SheetStore};
use crate::engine::arena::AstNodeId;
use crate::engine::eval_delta::{
    DeltaCollector, DeltaMode, EvalDelta, EvalDeltaCompatibilityPolicy,
};
use crate::engine::graph::prepared_legacy_graph::{
    PreparedLegacyGraphError, PreparedLegacyGraphPlan,
};
use crate::engine::graph::{FormulaDirtyEventSnapshot, FormulaDirtyLease, WholeSpanDirtyReason};
use crate::engine::ingest_pipeline::{DependencyPlanRow, FormulaAstInput};
use crate::engine::live_edges::{LiveEdgeCollector, RecordingContext};
use crate::engine::live_graph::analyze_live_graph;
use crate::engine::lookup_index_cache::{
    BuildOutcome, LookupAxis, LookupIndex, LookupIndexCache, LookupIndexCacheReport,
    LookupIndexKey, estimate_bytes,
};
use crate::engine::named_range::{NameScope, NamedDefinition};
use crate::engine::range_view::RangeView;
use crate::engine::row_visibility::RowVisibilityState;
use crate::engine::spill::{RegionLockManager, SpillMeta, SpillShape};
use crate::engine::target_preparation::{
    StagedFormulaIndex, StagedFormulaLease, StagedPackageLease,
};
use crate::engine::used_extent::{
    ExtentPolicy, OpenRangeBounds, resolve_used_extent_with_fallback,
};
use crate::engine::virtual_deps::{DynamicRefVirtualDepProvider, VirtualDepBuilder};
use crate::engine::{
    CycleDetection, CyclePolicy, DependencyGraph, EvalConfig, EvaluationRequestKind,
    EvaluationRequestOutcome, EvaluationResourceBaselineStats, EvaluationResourceReason,
    EvaluationResourceRequestStats, FormulaDirtyLeaseOutcome, FormulaIngestBatch,
    FormulaIngestRecord, FormulaIngestReport, FormulaParseDiagnostic, FormulaParsePolicy,
    FormulaPlaneMode, FormulaPlaneRoute, FormulaPlaneRouteEvent, FormulaPlaneRoutePhase,
    FormulaPlaneRouteTransitionReason, FormulaPlaneTopologyCacheOutcome,
    FormulaPlaneTopologyStrategy, ResourceLedger, RowVisibilitySource, ScheduleUnit, Scheduler,
    VertexId, VertexKind, VisibilityMaskMode,
};
use crate::formula_plane::placement::prepare_anchor_once_fragment;
use crate::formula_plane::placement::{
    CandidateAnalysis, FormulaPlacementCandidate, FormulaPlacementResult, PlacementFallbackReason,
    place_candidate_family_with_analyses, prepare_anchor_once_family,
    split_candidate_affine_literal_runs, validate_anchor_once_fragment_shadow,
    validate_anchor_once_shadow_relocation, validate_anchor_once_syntax,
};
use crate::formula_plane::producer::{
    DirtyProjectionRule, FormulaConsumerReadIndex, FormulaProducerId, FormulaProducerResultIndex,
    FormulaProducerWork, ProducerDirtyDomain, SpanReadSummary,
};
use crate::formula_plane::region_index::{DirtyDomain, Region};
use crate::formula_plane::runtime::{
    FormulaPlane, FormulaSpanId, FormulaSpanRef, PlacementCoord, PlacementDomain, ResultRegion,
};
use crate::formula_plane::scheduler::{
    MixedSchedule, MixedScheduleFallbackReason, MixedTopology, MixedTopologyCompileResult,
    MixedTopologyCompileStats, MixedTopologyConfig, build_demand_closure_cached,
    build_demand_closure_in_memory_runs, build_demand_closure_paged,
    build_demand_closure_repeated_passes, compile_mixed_topology, schedule_dirty_work,
    schedule_dirty_work_in_memory_runs, schedule_dirty_work_paged_hybrid,
    schedule_dirty_work_repeated_passes,
};
#[cfg(not(target_arch = "wasm32"))]
use crate::formula_plane::scheduler::{NativeExactDemandError, build_demand_closure_native};
#[cfg(not(target_arch = "wasm32"))]
use crate::formula_plane::scheduler::{NativeExactScheduleError, schedule_dirty_work_native};
#[cfg(test)]
use crate::formula_plane::span_eval::SpanEvalReport;
use crate::formula_plane::span_eval::{SpanComputedWriteSink, SpanEvalTask, SpanEvaluator};
use crate::formula_plane::structural::relocate_ast_for_template_placement;
use crate::formula_plane::structural_shift::{SpanShiftPlan, StructuralOp, classify_span_for_op};
use crate::function::FnCaps;
use crate::interpreter::Interpreter;
use crate::reference::{CellRef, Coord, RangeRef};
use crate::traits::FunctionProvider;
use crate::traits::{EvaluationContext, ReferenceInfo, Resolver};
use formualizer_common::{
    CoordBuildHasher, LiteralValue, col_letters_from_1based, parse_a1_1based,
};
use formualizer_parse::parser::ReferenceType;
use formualizer_parse::{ASTNode, ASTNodeType, ExcelError, ExcelErrorKind};
use rayon::ThreadPoolBuilder;
use rustc_hash::{FxHashMap, FxHashSet};
use std::collections::{BTreeMap, BTreeSet, VecDeque};
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
use std::time::Instant;

type StagedFormulaEntry = (u32, u32, String);
type StagedSheetParts = (
    Vec<StagedFormulaEntry>,
    Option<crate::engine::DeferredFormulaPackage>,
);

/// Per-sheet staged-formula store (NOTE(#126) follow-up).
///
/// Ingest consumers (`build_graph_all`/`build_graph_for_sheets`) walk staged
/// entries in INSERTION order, so the order-preserving `Vec` stays the
/// canonical storage; a `(row, col) → index` map removes the linear dup-scan
/// that made `stage_formula_text`/`get_staged_formula_text` O(staged-on-sheet)
/// per call (O(n²) for an n-formula deferred load on one sheet — ~570 ms for
/// 50k stages, release, before the index). `stage`/`get` are O(1);
/// `remove` keeps the old O(n) `Vec::remove` (rare path, order preserved).
#[derive(Default)]
pub(crate) struct StagedSheet {
    entries: Vec<StagedFormulaEntry>,
    index: FxHashMap<(u32, u32), usize>,
    deferred_package: Option<crate::engine::DeferredFormulaPackage>,
}

impl StagedSheet {
    fn invalidate_all_deferred_families(package: &mut crate::engine::DeferredFormulaPackage) {
        package
            .invalidated
            .extend(package.families.iter().map(|family| family.source_id));
        package.invalidated.extend(
            package
                .partitioned_families
                .iter()
                .map(|family| family.source_id),
        );
    }

    fn invalidate_deferred_at(&mut self, row: u32, col: u32) {
        let Some(package) = self.deferred_package.as_mut() else {
            return;
        };
        let family = package
            .replay
            .lock()
            .ok()
            .and_then(|mut replay| replay.formula_at(row, col).ok())
            .flatten()
            .and_then(|record| record.partition_owner.or(record.family));
        if let Some(family) = family {
            package.invalidated.insert(family);
        } else {
            // A poisoned lock, replay failure, malformed spool, or missing
            // lookup result must never let a possibly edited family commit.
            // Fail closed at package scope before suppressing the edited cell.
            Self::invalidate_all_deferred_families(package);
        }
        package.suppressed.insert((row, col));
    }

    fn reconcile_attached_deferred_package(&mut self) {
        let Some(package) = self.deferred_package.as_mut() else {
            return;
        };
        if self.entries.is_empty() {
            return;
        }

        let replayed = (|| {
            let mut disposition = crate::engine::FormulaReplayDisposition::default();
            for partition in &package.partitioned_families {
                disposition.register_partition(partition, false)?;
            }
            package
                .replay
                .lock()
                .map_err(|_| "deferred formula spool lock poisoned".to_string())?
                .replay_partitioned(&disposition, &package.partitioned_families)
        })();

        let Ok(records) = replayed else {
            Self::invalidate_all_deferred_families(package);
            package
                .suppressed
                .extend(self.entries.iter().map(|(row, col, _)| (*row, *col)));
            return;
        };
        let mut owners = FxHashMap::default();
        for record in &records {
            owners
                .entry((record.row, record.col))
                .or_insert(record.partition_owner.or(record.family));
        }
        for (row, col, _) in &self.entries {
            if let Some(family) = owners.get(&(*row, *col)).copied().flatten() {
                package.invalidated.insert(family);
            } else {
                Self::invalidate_all_deferred_families(package);
            }
            package.suppressed.insert((*row, *col));
        }
        package.reconciliation_replay = Some(records);
    }

    fn stage(&mut self, row: u32, col: u32, text: String) {
        self.invalidate_deferred_at(row, col);
        match self.index.entry((row, col)) {
            std::collections::hash_map::Entry::Occupied(slot) => {
                self.entries[*slot.get()].2 = text;
            }
            std::collections::hash_map::Entry::Vacant(slot) => {
                slot.insert(self.entries.len());
                self.entries.push((row, col, text));
            }
        }
    }

    fn remove(&mut self, row: u32, col: u32) -> Option<String> {
        let deferred_text = self.get(row, col);
        self.invalidate_deferred_at(row, col);
        let Some(idx) = self.index.remove(&(row, col)) else {
            return deferred_text;
        };
        let (_, _, text) = self.entries.remove(idx);
        // `Vec::remove` shifted everything after `idx` left by one.
        for slot in self.index.values_mut() {
            if *slot > idx {
                *slot -= 1;
            }
        }
        Some(text)
    }

    fn get_ordinary(&self, row: u32, col: u32) -> Option<&str> {
        self.index
            .get(&(row, col))
            .map(|&i| self.entries[i].2.as_str())
    }

    fn remove_ordinary(&mut self, row: u32, col: u32) -> Option<String> {
        let idx = self.index.remove(&(row, col))?;
        let (_, _, text) = self.entries.remove(idx);
        for slot in self.index.values_mut() {
            if *slot > idx {
                *slot -= 1;
            }
        }
        Some(text)
    }

    fn get(&self, row: u32, col: u32) -> Option<String> {
        if let Some(text) = self.get_ordinary(row, col) {
            return Some(text.to_string());
        }
        let package = self.deferred_package.as_ref()?;
        if package.suppressed.contains(&(row, col)) {
            return None;
        }
        package
            .replay
            .lock()
            .ok()?
            .formula_at(row, col)
            .ok()?
            .map(|record| record.text)
    }

    fn len(&self) -> usize {
        self.deferred_package
            .as_ref()
            .map_or(self.entries.len(), |package| {
                usize::try_from(package.report.source_formula_records_spooled)
                    .unwrap_or(usize::MAX)
                    .saturating_sub(package.suppressed.len())
                    .saturating_add(self.entries.len())
            })
    }

    fn is_empty(&self) -> bool {
        self.entries.is_empty() && self.deferred_package.is_none()
    }

    fn into_parts(self) -> StagedSheetParts {
        (self.entries, self.deferred_package)
    }
}

type StagedFormulaMap = std::collections::HashMap<String, StagedSheet>;

#[derive(Clone, Debug, PartialEq, Eq, Hash)]
struct PreparationRegion {
    sheet: String,
    sheet_id: SheetId,
    start_row: u32,
    start_col: u32,
    end_row: u32,
    end_col: u32,
}

// Span roots dedupe by exact demanded-region identity. Overlapping, non-identical
// regions remain ordered entries; downstream demand treats those entries as a union.
struct OrderedTargetProducers {
    ordered: Vec<crate::engine::target_preparation::TargetProducer>,
    seen: FxHashSet<crate::engine::target_preparation::TargetProducer>,
}

impl OrderedTargetProducers {
    fn with_capacity(capacity: usize) -> Result<Self, std::collections::TryReserveError> {
        let mut ordered = Vec::new();
        ordered.try_reserve(capacity)?;
        let mut seen = FxHashSet::default();
        seen.try_reserve(capacity)?;
        Ok(Self { ordered, seen })
    }

    fn from_ordered(
        ordered: Vec<crate::engine::target_preparation::TargetProducer>,
    ) -> Result<Self, std::collections::TryReserveError> {
        let mut seen = FxHashSet::default();
        seen.try_reserve(ordered.len())?;
        seen.extend(ordered.iter().copied());
        Ok(Self { ordered, seen })
    }

    fn push(
        &mut self,
        producer: crate::engine::target_preparation::TargetProducer,
    ) -> Result<bool, std::collections::TryReserveError> {
        #[cfg(test)]
        TARGET_ROOT_DEDUP_PROBES.with(|probes| probes.set(probes.get().saturating_add(1)));
        if self.seen.contains(&producer) {
            return Ok(false);
        }
        self.seen.try_reserve(1)?;
        self.ordered.try_reserve(1)?;
        self.seen.insert(producer);
        self.ordered.push(producer);
        Ok(true)
    }

    fn len(&self) -> usize {
        self.ordered.len()
    }

    fn into_vec(self) -> Vec<crate::engine::target_preparation::TargetProducer> {
        self.ordered
    }
}

#[cfg(test)]
thread_local! {
    static TARGET_ROOT_DEDUP_PROBES: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
}

fn target_root_allocation_error(observed: usize, request_id: Option<u64>) -> ExcelError {
    crate::engine::ResourceLedgerError::Exhausted(formualizer_common::ResourceExhaustionDetail {
        reason: formualizer_common::ResourceExhaustionReason::ScratchMemory,
        limit: u64::MAX,
        observed: observed as u64,
        request_id,
    })
    .into_excel_error()
}

#[derive(Debug)]
struct PreparedOrdinaryStagedFormula {
    sheet: String,
    sheet_id: SheetId,
    lease: StagedFormulaLease,
    ast_id: Option<AstNodeId>,
    plan: Option<DependencyPlanRow>,
}

struct PreparedTargetSourcePackage {
    sheet: String,
    sheet_id: SheetId,
    lease: StagedPackageLease,
    source_report: crate::engine::FormulaCompressedSourceReport,
    replay_records: Vec<crate::engine::DeferredReplayFormula>,
    disposition: crate::engine::FormulaReplayDisposition,
    placements: Vec<crate::formula_plane::placement::PreparedAnchorOncePlacement>,
    legacy: Vec<(u32, u32, AstNodeId, DependencyPlanRow)>,
    direct_families: usize,
    direct_cells: u64,
    direct_fragments: u64,
    direct_complete_families: u64,
    direct_complete_cells: u64,
    direct_partition_families: u64,
    direct_partition_cells: u64,
    anchor_parses: u64,
    anchor_asts: u64,
    anchor_analyses: u64,
}

impl PreparedTargetSourcePackage {
    fn fallback_records(&self) -> impl Iterator<Item = &crate::engine::DeferredReplayFormula> {
        self.replay_records.iter().filter(|record| {
            let Some((row, col)) = record.row.checked_sub(1).zip(record.col.checked_sub(1)) else {
                return true;
            };
            let coord = crate::engine::SourceCoord { row, col };
            let disposition = match record.family {
                Some(family) => self.disposition.shared_disposition(family, coord),
                None => self.disposition.ordinary_disposition(coord).0,
            };
            !matches!(
                disposition,
                crate::engine::FormulaReplayCoordinateDisposition::Direct
                    | crate::engine::FormulaReplayCoordinateDisposition::Suppressed
            )
        })
    }
}

fn producer_dirty_to_span_dirty(
    dirty: ProducerDirtyDomain,
    span_ref: FormulaSpanRef,
) -> DirtyDomain {
    match dirty {
        ProducerDirtyDomain::Whole => DirtyDomain::WholeSpan(span_ref),
        ProducerDirtyDomain::Cells(cells) => DirtyDomain::Cells(cells),
        ProducerDirtyDomain::Regions(regions) => DirtyDomain::Regions(regions),
    }
}
type PreparedFormulaBatches = Vec<FormulaIngestBatch>;
type StagedFormulaBatches = Vec<(String, StagedSheet)>;
#[derive(Debug)]
pub(crate) struct SourceFamilyPreparationError {
    reason: String,
    parse_attempted: bool,
    ast_created: bool,
    analysis_created: bool,
}

impl SourceFamilyPreparationError {
    fn contract(reason: &'static str) -> Self {
        Self {
            reason: reason.to_string(),
            parse_attempted: false,
            ast_created: false,
            analysis_created: false,
        }
    }

    fn parse(reason: &'static str) -> Self {
        Self {
            reason: reason.to_string(),
            parse_attempted: true,
            ast_created: false,
            analysis_created: false,
        }
    }

    fn ast(reason: impl Into<String>) -> Self {
        Self {
            reason: reason.into(),
            parse_attempted: true,
            ast_created: true,
            analysis_created: false,
        }
    }

    fn analysis(reason: impl Into<String>) -> Self {
        Self {
            reason: reason.into(),
            parse_attempted: true,
            ast_created: true,
            analysis_created: true,
        }
    }
}

struct PreparedPartitionShadow {
    fragment_count: u64,
    direct_cells: u64,
    fallback_cells: u64,
    function_semantics_used: bool,
}

pub(crate) fn classify_mixed_topology_incomplete(
    observed: &MixedTopologyCompileStats,
) -> crate::engine::EvaluationIncompleteReason {
    if observed.memory_overflow_count > 0 && observed.estimated_memory_bytes == usize::MAX {
        crate::engine::EvaluationIncompleteReason::FormulaPlaneTopologyAllocation
    } else if observed.memory_overflow_count > 0 {
        crate::engine::EvaluationIncompleteReason::FormulaPlaneTopologyRetainedBytes
    } else if observed.edge_overflow_count > 0 {
        crate::engine::EvaluationIncompleteReason::FormulaPlaneTopologyEdges
    } else if observed.candidate_overflow_count > 0 {
        crate::engine::EvaluationIncompleteReason::FormulaPlaneTopologyCandidates
    } else {
        crate::engine::EvaluationIncompleteReason::FormulaPlaneTopologySemanticStructural
    }
}

#[derive(Clone, Debug, Default)]
struct LegacyIslandPlan {
    membership: Vec<VertexId>,
    dirty_vertices: Vec<VertexId>,
    sheet_ids: Vec<SheetId>,
    island_id: u64,
    retained_bytes: usize,
    boundary_relationships: usize,
    omitted_relationships: usize,
    omitted_direct_relationships: usize,
}

impl LegacyIslandPlan {
    fn is_empty(&self) -> bool {
        self.membership.is_empty()
    }
}

type FormulaPlaneMixedScheduleBuild = (
    MixedSchedule,
    BTreeMap<crate::formula_plane::runtime::FormulaSpanId, FormulaSpanRef>,
    u64,
    Vec<VertexId>,
    Vec<usize>,
    LegacyIslandPlan,
);

#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub(crate) enum FormulaSpanDemotionFault {
    #[default]
    None,
    AstPreparation,
    LegacyGraphPreparation,
    FinalLegacyGraphValidation,
    FinalAuthorityValidation,
    AllocationReservation,
    BeforeFirstMutation,
}

#[derive(Debug)]
pub(crate) enum FormulaSpanDemotionError {
    StaleAuthority,
    InvalidSpan,
    CountOverflow,
    Resource(ExcelError),
    AstPreparation(ExcelError),
    LegacyGraph(PreparedLegacyGraphError),
    Injected(FormulaSpanDemotionFault),
}

impl std::fmt::Display for FormulaSpanDemotionError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::StaleAuthority => write!(f, "prepared FormulaPlane demotion is stale"),
            Self::InvalidSpan => write!(f, "FormulaPlane demotion referenced an invalid span"),
            Self::CountOverflow => write!(f, "FormulaPlane demotion count overflow"),
            Self::Resource(error) => write!(f, "{error}"),
            Self::AstPreparation(error) => {
                write!(f, "FormulaPlane demotion analysis failed: {error}")
            }
            Self::LegacyGraph(error) => {
                write!(f, "FormulaPlane demotion graph plan failed: {error}")
            }
            Self::Injected(fault) => write!(f, "injected FormulaPlane demotion fault: {fault:?}"),
        }
    }
}

impl std::error::Error for FormulaSpanDemotionError {}

pub(crate) struct PreparedFormulaSpanDemotion {
    span_refs: Vec<FormulaSpanRef>,
    expected_plane_epoch: u64,
    expected_indexes_epoch: u64,
    expected_indexed_plane_epoch: u64,
    placement_count: usize,
    legacy_graph: PreparedLegacyGraphPlan,
    fault: FormulaSpanDemotionFault,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) struct FormulaSpanDemotionReport {
    pub(crate) spans_demoted: usize,
    pub(crate) placements_materialized: usize,
}

type PlannedFormulaMaterialize = BTreeMap<String, Vec<(u32, u32, AstNodeId, DependencyPlanRow)>>;
type CompressedReplayBatch = (
    FormulaIngestBatch,
    crate::engine::FormulaCompressedSourceBatch,
);
type PreparedSourceBatch = (
    FormulaIngestBatch,
    crate::engine::FormulaCompressedSourceReport,
    crate::engine::FormulaCompressedPreparation,
);
type PreparedStagedFormulaBatches = (
    PreparedFormulaBatches,
    Vec<CompressedReplayBatch>,
    Vec<PreparedSourceBatch>,
);

/// Backend-neutral source-family ingress. Adapters may prepare candidates and
/// submit exact replay, but FormulaPlane authority remains engine-owned.
#[doc(hidden)]
pub struct SourceFormulaIngress<'a, R> {
    engine: &'a mut Engine<R>,
}

impl<R> SourceFormulaIngress<'_, R>
where
    R: EvaluationContext,
{
    pub fn prepare_families(
        &mut self,
        sheet_name: &str,
        families: &[crate::engine::SourceFormulaFamily],
    ) -> Result<crate::engine::FormulaCompressedPreparation, ExcelError> {
        self.engine.observe_function_semantic_epoch()?;
        Ok(self
            .engine
            .prepare_source_formula_families(sheet_name, families))
    }

    pub fn prepare_eager_proposals(
        &mut self,
        sheet_name: &str,
        families: &[crate::engine::SourceFormulaFamily],
        partitions: &[crate::engine::PartitionedSourceFormulaFamily],
        formula_record_count: u64,
        replay: Box<dyn crate::engine::DeferredFormulaReplay>,
    ) -> Result<crate::engine::FormulaCompressedPreparation, ExcelError> {
        self.engine.observe_function_semantic_epoch()?;
        let replay = Arc::new(std::sync::Mutex::new(replay));
        self.engine.prepare_source_formula_proposals(
            sheet_name,
            families,
            partitions,
            partitions,
            formula_record_count,
            replay,
            &BTreeSet::new(),
        )
    }

    pub fn stage_deferred(&mut self, package: crate::engine::DeferredFormulaPackage) {
        self.engine.stage_deferred_formula_package(package);
    }

    pub fn ingest_replay_batches(
        &mut self,
        batches: Vec<(
            FormulaIngestBatch,
            crate::engine::FormulaCompressedSourceBatch,
        )>,
    ) -> Result<FormulaIngestReport, ExcelError> {
        self.engine
            .ingest_compressed_formula_source_batches(batches)
    }

    pub fn finish_prepared(
        &mut self,
        batches: Vec<(
            FormulaIngestBatch,
            crate::engine::FormulaCompressedSourceReport,
            crate::engine::FormulaCompressedPreparation,
        )>,
    ) -> Result<FormulaIngestReport, ExcelError> {
        self.engine.finish_compressed_formula_sources(batches)
    }
}

// Computed-write coalescing pays a fixed grouping/planning cost. For very narrow
// layers there is not enough work to amortize it, and the direct point-write path
// is faster while preserving the same visibility semantics.
const COMPUTED_WRITE_COALESCING_MIN_LAYER_WIDTH: usize = 8;

#[derive(Debug, Clone, PartialEq)]
pub(crate) enum ComputedWrite {
    Cell {
        seq: u64,
        sheet_id: SheetId,
        row0: u32,
        col0: u32,
        value: OverlayValue,
    },
    Rect {
        seq: u64,
        sheet_id: SheetId,
        sr0: u32,
        sc0: u32,
        values: Vec<Vec<OverlayValue>>,
    },
}

impl ComputedWrite {
    #[inline]
    pub(crate) fn seq(&self) -> u64 {
        match self {
            ComputedWrite::Cell { seq, .. } | ComputedWrite::Rect { seq, .. } => *seq,
        }
    }
}

#[derive(Debug, Default)]
pub(crate) struct ComputedWriteBuffer {
    writes: Vec<ComputedWrite>,
    next_seq: u64,
    estimated_bytes: usize,
}

impl ComputedWriteBuffer {
    const ENTRY_BASE_BYTES: usize = 32;

    #[inline]
    pub(crate) fn is_empty(&self) -> bool {
        self.writes.is_empty()
    }

    #[inline]
    pub(crate) fn len(&self) -> usize {
        self.writes.len()
    }

    #[inline]
    pub(crate) fn estimated_bytes(&self) -> usize {
        self.estimated_bytes
    }

    #[inline]
    pub(crate) fn writes(&self) -> &[ComputedWrite] {
        &self.writes
    }

    pub(crate) fn push_cell(
        &mut self,
        sheet_id: SheetId,
        row0: u32,
        col0: u32,
        value: OverlayValue,
    ) {
        let seq = self.next_sequence();
        self.estimated_bytes = self
            .estimated_bytes
            .saturating_add(Self::estimate_value_bytes(&value));
        self.writes.push(ComputedWrite::Cell {
            seq,
            sheet_id,
            row0,
            col0,
            value,
        });
    }

    pub(crate) fn push_rect(
        &mut self,
        sheet_id: SheetId,
        sr0: u32,
        sc0: u32,
        values: Vec<Vec<OverlayValue>>,
    ) {
        let seq = self.next_sequence();
        let added = values
            .iter()
            .flat_map(|row| row.iter())
            .map(Self::estimate_value_bytes)
            .fold(0usize, usize::saturating_add);
        self.estimated_bytes = self.estimated_bytes.saturating_add(added);
        self.writes.push(ComputedWrite::Rect {
            seq,
            sheet_id,
            sr0,
            sc0,
            values,
        });
    }

    pub(crate) fn clear(&mut self) {
        self.writes.clear();
        self.estimated_bytes = 0;
    }

    fn take_writes(&mut self) -> Vec<ComputedWrite> {
        self.estimated_bytes = 0;
        std::mem::take(&mut self.writes)
    }

    fn next_sequence(&mut self) -> u64 {
        let seq = self.next_seq;
        self.next_seq = self.next_seq.wrapping_add(1);
        seq
    }

    #[inline]
    fn estimate_value_bytes(value: &OverlayValue) -> usize {
        Self::ENTRY_BASE_BYTES.saturating_add(value.estimated_payload_bytes())
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
struct ComputedWriteChunkKey {
    sheet_id: SheetId,
    col0: u32,
    chunk_idx: usize,
    chunk_start_row0: u32,
}

#[derive(Debug, Clone, PartialEq)]
pub(crate) struct ComputedWriteChunkEntryPlan {
    pub(crate) row_in_chunk: usize,
    pub(crate) seq: u64,
    pub(crate) value: OverlayValue,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum ComputedWriteChunkPlanShape {
    Point,
    SparseOffsets {
        entries: usize,
        span_len: usize,
    },
    DenseRange {
        start: usize,
        len: usize,
    },
    RunRange {
        start: usize,
        len: usize,
        runs: usize,
    },
}

#[derive(Debug, Clone, PartialEq)]
pub(crate) struct ComputedWriteChunkPlan {
    pub(crate) sheet_id: SheetId,
    pub(crate) col0: u32,
    pub(crate) chunk_idx: usize,
    pub(crate) chunk_start_row0: u32,
    pub(crate) entries: Vec<ComputedWriteChunkEntryPlan>,
    pub(crate) shape: ComputedWriteChunkPlanShape,
}

#[derive(Debug, Clone, Default, PartialEq)]
pub(crate) struct ComputedWriteCoalescingPlan {
    pub(crate) chunks: Vec<ComputedWriteChunkPlan>,
    pub(crate) input_cells: usize,
    pub(crate) coalesced_cells: usize,
    pub(crate) overwritten_cells: usize,
}

impl ComputedWriteCoalescingPlan {
    #[inline]
    pub(crate) fn is_empty(&self) -> bool {
        self.chunks.is_empty()
    }
}

impl ComputedWriteChunkPlan {
    fn from_group(
        key: ComputedWriteChunkKey,
        mut entries: Vec<ComputedWriteChunkEntryPlan>,
    ) -> (Self, usize) {
        entries.sort_by_key(|entry| (entry.row_in_chunk, entry.seq));
        let input_len = entries.len();
        let mut coalesced: Vec<ComputedWriteChunkEntryPlan> = Vec::with_capacity(input_len);
        for entry in entries {
            if let Some(prev) = coalesced.last_mut()
                && prev.row_in_chunk == entry.row_in_chunk
            {
                *prev = entry;
                continue;
            }
            coalesced.push(entry);
        }
        let overwritten = input_len.saturating_sub(coalesced.len());
        let shape = Self::classify_shape(&coalesced);
        (
            Self {
                sheet_id: key.sheet_id,
                col0: key.col0,
                chunk_idx: key.chunk_idx,
                chunk_start_row0: key.chunk_start_row0,
                entries: coalesced,
                shape,
            },
            overwritten,
        )
    }

    fn classify_shape(entries: &[ComputedWriteChunkEntryPlan]) -> ComputedWriteChunkPlanShape {
        debug_assert!(!entries.is_empty());
        if entries.len() == 1 {
            return ComputedWriteChunkPlanShape::Point;
        }

        let start = entries[0].row_in_chunk;
        let end = entries[entries.len() - 1].row_in_chunk;
        let span_len = end.saturating_sub(start).saturating_add(1);
        if span_len != entries.len() {
            return ComputedWriteChunkPlanShape::SparseOffsets {
                entries: entries.len(),
                span_len,
            };
        }

        let runs = Self::run_count(entries);
        if runs < entries.len() {
            ComputedWriteChunkPlanShape::RunRange {
                start,
                len: entries.len(),
                runs,
            }
        } else {
            ComputedWriteChunkPlanShape::DenseRange {
                start,
                len: entries.len(),
            }
        }
    }

    fn run_count(entries: &[ComputedWriteChunkEntryPlan]) -> usize {
        let mut runs = 0usize;
        let mut prev: Option<&OverlayValue> = None;
        for entry in entries {
            if prev != Some(&entry.value) {
                runs = runs.saturating_add(1);
                prev = Some(&entry.value);
            }
        }
        runs
    }
}

pub struct Engine<R> {
    pub(crate) graph: DependencyGraph,
    resolver: R,
    pub config: EvalConfig,
    workbook_load_limits: crate::engine::WorkbookLoadLimits,
    /// Clock for volatile date/time builtins, wrapped in a per-recalc
    /// snapshot: sampled once at the start of every evaluation request
    /// ([`Self::begin_evaluation_request`]) so all `NOW()`/`TODAY()` reads in
    /// one recalc — including SCC iteration passes — agree (spec §7.11).
    clock: crate::timezone::SnapshotClock,
    thread_pool: Option<Arc<rayon::ThreadPool>>,
    pub recalc_epoch: u64,
    snapshot_id: std::sync::atomic::AtomicU64,
    topology_epoch: u64,
    /// False after a structural axis operation. While #171 remains open we
    /// must not use relocated span read summaries to prove disconnection.
    legacy_island_structural_summaries_trusted: bool,
    cached_static_schedule: Option<CachedScheduleEntry>,
    cached_mixed_topology: Option<CachedMixedTopology>,
    mixed_topology_cache_builds: u64,
    mixed_topology_cache_hits: u64,
    mixed_topology_cache_overflows: u64,
    mixed_topology_cache_skip_streak: u64,
    spill_mgr: ShimSpillManager,
    /// Arrow-backed storage for sheet values (Phase A)
    arrow_sheets: SheetStore,
    /// True if any edit after bulk load; disables Arrow reads for parity
    has_edited: bool,
    /// Overlay compaction counter (Phase C instrumentation)
    overlay_compactions: u64,

    // Overlay memory observability / budget (ticket 503)
    computed_overlay_bytes_estimate: usize,
    computed_overlay_mirroring_disabled: bool,
    /// When true, RangeView resolution materializes from graph/Arrow base per-cell.
    /// This preserves correctness if we stop mirroring formula/spill outputs into computed overlays.
    pub(crate) force_materialize_range_views: bool,
    // Pass-scoped cache for Arrow used-row bounds per column
    row_bounds_cache: std::sync::RwLock<Option<RowBoundsCache>>,
    // Snapshot-scoped final used-axis bounds for open-ended references.
    used_axis_bounds_cache: std::sync::RwLock<Option<UsedAxisBoundsCache>>,
    lookup_index_cache: LookupIndexCache,
    source_cache: Arc<std::sync::RwLock<SourceCache>>,
    /// Identity binding for opaque source-family preparations.
    source_formula_token: Arc<()>,
    /// Dedicated identity binding for reusable recalculation plans.
    recalc_plan_token: Arc<()>,
    /// Staged formulas by sheet when `defer_graph_building` is enabled.
    staged_formulas: StagedFormulaMap,
    /// Presence and generation authority for ordinary staged formula discovery.
    staged_formula_index: StagedFormulaIndex,
    /// Per-sheet row visibility sidecar state.
    row_visibility: FxHashMap<SheetId, RowVisibilityState>,
    /// Cached row visibility masks keyed by sheet/span/mode/version.
    row_visibility_mask_cache: std::sync::RwLock<
        FxHashMap<VisibilityMaskCacheKey, std::sync::Arc<arrow_array::BooleanArray>>,
    >,
    /// Non-fatal malformed formula diagnostics captured during ingest/graph-build.
    formula_parse_diagnostics: Vec<FormulaParseDiagnostic>,
    /// Last centralized formula ingest report.
    last_formula_ingest_report: Option<FormulaIngestReport>,
    /// Aggregate centralized formula ingest report for this engine.
    formula_ingest_report_total: FormulaIngestReport,
    /// Count of FormulaPlane spans demoted to legacy because one or more of
    /// their member cells participate in a statically-cyclic SCC. A span member
    /// must never be span-evaluated (gotcha G8 of the cycle-architecture track,
    /// refs #112): under `CycleDetection::Static` the cycle stamping would race
    /// span writes, and under `Runtime` SCC members must be evaluated by the
    /// legacy `evaluate_scc_unit` path. Cyclic spans are demoted at
    /// schedule-build time (the earliest point cross-cell cycles through span
    /// producers become visible) so the cycle members land on the legacy graph
    /// path. Observational only.
    formula_plane_cycle_member_span_demotions: u64,
    /// Successfully completed non-cycle unsafe mixed requests. Incremented
    /// only after every scheduled span has committed demotion and the single
    /// legacy completion pass succeeds; failed attempts are not counted.
    /// Observational only.
    formula_plane_capacity_bailouts: u64,
    /// Exact span candidates classified across structural mutations.
    formula_plane_structural_span_candidates: u64,
    /// Transient cancellation flag used during evaluation
    active_cancel_flag: Option<crate::engine::CancelToken>,
    /// Transient absolute deadline used by composed target and plan requests.
    active_evaluation_deadline: Option<Instant>,

    /// Engine-level action depth.
    ///
    /// Ticket 614 introduces `Engine::action` as a stable, commit-only transaction surface.
    /// Nested actions are currently disallowed (deterministic rule) and will return an error.
    action_depth: u32,

    // Phase 3b virtual-dependency convergence telemetry
    last_virtual_dep_telemetry: VirtualDepTelemetry,
    virtual_dep_fallback_activations: u64,

    // Runtime-cycle SCC evaluation telemetry (RFC #112, Stage 2)
    last_cycle_telemetry: CycleTelemetry,

    // C0 evaluation-resource observability. IDs are never reset or reused.
    next_evaluation_resource_request_id: u64,
    evaluation_resource_request_depth: usize,
    active_evaluation_resource_request: Option<EvaluationResourceRequestStats>,
    last_evaluation_resource_request: Option<EvaluationResourceRequestStats>,
    evaluation_resource_baseline: EvaluationResourceBaselineStats,
    evaluation_resource_request_started_at: Option<crate::instant::FzInstant>,
    evaluation_resource_budgets: crate::engine::EvaluationBudgets,
    evaluation_resource_config_diagnostic:
        Option<crate::engine::EvaluationResourceConfigDiagnostic>,
    active_resource_ledger: Option<ResourceLedger>,

    /// SCC members that entered iterative calculation (`CyclePolicy::Iterate`
    /// with a witnessed live cycle) during the current evaluation request.
    ///
    /// Excel re-evaluates circular cells on EVERY recalc (the accumulator
    /// contract, spec §4/§7.6), but this engine's dirty model marks SCC
    /// members clean after a recalc and would otherwise skip them forever.
    /// Resolution: members of iterating SCCs are redirtied volatile-like at
    /// the end of the same recalc that iterated them
    /// ([`Self::redirty_for_next_recalc`], called wherever
    /// `redirty_volatiles` runs). The set is per-recalc, never persisted:
    /// if an edit breaks the cycle, the next recalc's SCC task either does
    /// not exist or settles as phantom, nothing re-registers, and the
    /// redirty chain stops by itself.
    pending_iterative_redirty: Vec<VertexId>,

    /// Final committed values of iterating-SCC members as of the end of the
    /// most recent recalc (spec §4 persistence). In canonical (value-cache
    /// disabled) mode the computed overlay is the ONLY home of a formula's
    /// value, and structural edits clear computed overlays wholesale
    /// (`clear_computed_overlay_after_row/_col`) — destroying iteration
    /// state (accumulators reset to 0; found by the iterate edge corpus).
    /// This snapshot, refreshed by [`Self::redirty_for_next_recalc`], lets
    /// the next SCC task re-seed members whose overlay entry vanished.
    /// Empty unless something iterated — zero cost otherwise.
    iterative_state_values: FxHashMap<VertexId, LiteralValue>,

    /// Global function-registry semantic epoch observed after the latest
    /// conservative FormulaPlane invalidation.
    function_semantic_epoch_seen: u64,
    /// Runtime-provider semantic revision observed after the latest conservative
    /// FormulaPlane invalidation.
    function_provider_revision_seen: Option<u64>,

    #[cfg(test)]
    last_formula_plane_span_eval_report: Option<SpanEvalReport>,
    #[cfg(test)]
    evaluation_request_begin_count_for_test: u64,
    #[cfg(any(test, feature = "test-support"))]
    before_prepared_span_commit_hook: Option<Box<dyn FnOnce() + Send + Sync>>,
    #[cfg(test)]
    before_target_preparation_commit_hook: Option<Box<dyn FnOnce() + Send + Sync>>,
    #[cfg(test)]
    before_target_planning_snapshot_hook: Option<Box<dyn FnOnce() + Send + Sync>>,
    #[cfg(test)]
    inject_target_semantic_stale_once_for_test: bool,
    #[cfg(test)]
    force_virtual_dep_changes_remaining_for_test: usize,
    #[cfg(test)]
    fail_evaluation_commit_preflight_once_for_test: bool,
    #[cfg(test)]
    force_source_family_fallback: bool,
    #[cfg(test)]
    rerecord_cycle_retry_span_after_lease_extension_for_test: bool,
    #[cfg(test)]
    fragmented_commit_fault_for_test:
        Option<crate::engine::fragmented_transaction::FragmentedCommitFault>,
    #[cfg(test)]
    formula_span_demotion_fault_for_test: Option<FormulaSpanDemotionFault>,
    #[cfg(test)]
    target_preparation_fault_for_test:
        Option<crate::engine::target_preparation::TargetPreparationFault>,
    #[cfg(test)]
    force_non_cycle_schedule_fallback_for_test: bool,
    #[cfg(test)]
    mixed_topology_index_builds_for_test: u64,
    #[cfg(test)]
    before_legacy_fallback_final_provider_sample_hook: Option<Box<dyn FnOnce() + Send + Sync>>,
    #[cfg(test)]
    after_eager_proposal_commit_hook: Option<Box<dyn FnOnce() + Send + Sync>>,
}

/// Minimal edit surface used by `Engine::action`.
///
fn substitute_formula_plane_literal_slots(ast: &ASTNode, binding: &[LiteralValue]) -> ASTNode {
    fn visit(ast: &ASTNode, binding: &[LiteralValue], next: &mut usize, in_array: bool) -> ASTNode {
        let node_type = match &ast.node_type {
            ASTNodeType::Literal(_) if !in_array => {
                let value = binding.get(*next).cloned().unwrap_or(LiteralValue::Empty);
                *next = next.saturating_add(1);
                ASTNodeType::Literal(value)
            }
            ASTNodeType::Literal(value) => ASTNodeType::Literal(value.clone()),
            ASTNodeType::Omitted => ASTNodeType::Omitted,
            ASTNodeType::Reference {
                original,
                reference,
            } => ASTNodeType::Reference {
                original: original.clone(),
                reference: reference.clone(),
            },
            ASTNodeType::UnaryOp { op, expr } => ASTNodeType::UnaryOp {
                op: op.clone(),
                expr: Box::new(visit(expr, binding, next, in_array)),
            },
            ASTNodeType::BinaryOp { op, left, right } => ASTNodeType::BinaryOp {
                op: op.clone(),
                left: Box::new(visit(left, binding, next, in_array)),
                right: Box::new(visit(right, binding, next, in_array)),
            },
            ASTNodeType::Function { name, args } => ASTNodeType::Function {
                name: name.clone(),
                args: args
                    .iter()
                    .map(|arg| visit(arg, binding, next, in_array))
                    .collect(),
            },
            ASTNodeType::Call { callee, args } => ASTNodeType::Call {
                callee: Box::new(visit(callee, binding, next, in_array)),
                args: args
                    .iter()
                    .map(|arg| visit(arg, binding, next, in_array))
                    .collect(),
            },
            ASTNodeType::Array(rows) => ASTNodeType::Array(
                rows.iter()
                    .map(|row| {
                        row.iter()
                            .map(|cell| visit(cell, binding, next, true))
                            .collect()
                    })
                    .collect(),
            ),
        };
        ASTNode::new(node_type, ast.source_token.clone())
    }

    let mut next = 0;
    visit(ast, binding, &mut next, false)
}

/// This wrapper is intentionally thin for ticket 614 (commit-only): it delegates to existing
/// `Engine` edit methods and does not create changelog boundaries or implement rollback.
impl<R: EvaluationContext> Engine<R> {
    pub(crate) fn ingest_pipeline(&mut self) -> crate::engine::ingest_pipeline::IngestPipeline<'_> {
        self.graph.ingest_pipeline(&self.resolver)
    }
}

pub struct EngineAction<'a, R>
where
    R: EvaluationContext,
{
    engine: &'a mut Engine<R>,
    name: String,
    // Optional external ChangeLog pointer used by `Engine::action_with_logger`.
    // Stored as a raw pointer to avoid creating aliasing `&mut` borrows alongside `&mut Engine`.
    log: Option<*mut crate::engine::ChangeLog>,
    // Optional Arrow undo journal used by `Engine::action_atomic`.
    // Stored as a raw pointer to avoid aliasing issues with `&mut Engine`.
    arrow_undo: Option<*mut crate::engine::ArrowUndoBatch>,
    // True when this EngineAction must enforce conservative atomic transaction policy.
    atomic_policy: bool,
}

impl<'a, R> EngineAction<'a, R>
where
    R: EvaluationContext,
{
    #[inline]
    fn addr_for(&mut self, sheet: &str, row: u32, col: u32) -> crate::reference::CellRef {
        let sheet_id = self.engine.graph.sheet_id_mut(sheet);
        let coord = crate::reference::Coord::from_excel(row, col, true, true);
        crate::reference::CellRef::new(sheet_id, coord)
    }

    #[inline]
    pub fn name(&self) -> &str {
        &self.name
    }

    #[inline]
    pub fn set_cell_value(
        &mut self,
        sheet: &str,
        row: u32,
        col: u32,
        value: LiteralValue,
    ) -> Result<(), crate::engine::EditorError> {
        if self.log.is_some() {
            let old_value = self.engine.read_cell_value(sheet, row, col);
            let mut old_formula = self.engine.read_cell_formula_ast(sheet, row, col);
            let addr = self.addr_for(sheet, row, col);
            let Some(log_ptr) = self.log else {
                return Err(crate::engine::EditorError::TransactionFailed {
                    reason: "action_with_logger: missing ChangeLog".to_string(),
                });
            };

            // For atomic journal mode, record computed overlay effects for this cell.
            // Delta-overlay undo is recorded semantically based on old_value/old_formula.
            let old_comp = if self.arrow_undo.is_some() {
                self.engine.read_computed_overlay_cell(sheet, row, col)
            } else {
                None
            };

            if self.engine.graph_admission_enabled() {
                let admission =
                    self.engine
                        .graph
                        .preview_value_mutation(addr.sheet_id, row, col)?;
                self.engine.preflight_graph_admission(admission)?;
            }
            self.engine.demote_span_containing_cell_for_write(
                addr.sheet_id,
                addr.coord.row(),
                addr.coord.col(),
            )?;
            if old_formula.is_none() {
                old_formula = self.engine.read_cell_formula_ast(sheet, row, col);
            }

            let delta_old_sem = if old_formula.is_some() {
                None
            } else {
                Some(old_value.clone().unwrap_or(LiteralValue::Empty))
            };

            let start_len = unsafe { (&*log_ptr).len() };

            // Safety: `log_ptr` comes from a unique `&mut ChangeLog` in `Engine::action_with_logger`.
            let log = unsafe { &mut *log_ptr };
            self.engine.edit_with_logger(log, |editor| {
                editor.set_cell_value_with_old_state(
                    addr,
                    value.clone(),
                    old_value.clone(),
                    old_formula.clone(),
                );
            })?;
            self.engine
                .record_formula_plane_structural_change(StructuralScope::Cell {
                    sheet: addr.sheet_id,
                    row: addr.coord.row(),
                    col: addr.coord.col(),
                });

            if let Some(undo_ptr) = self.arrow_undo {
                // 1) Spill snapshot operations (computed overlay rect restore).
                let new_events = &unsafe { (&*log_ptr).events() }[start_len..];
                let undo = unsafe { &mut *undo_ptr };
                self.engine
                    .record_spill_ops_into_arrow_undo(undo, new_events);

                // 2) Delta/computed overlay single-cell deltas.
                let new_comp = self.engine.read_computed_overlay_cell(sheet, row, col);
                let sheet_id = self.engine.graph.sheet_id_mut(sheet);
                let row0 = row.saturating_sub(1);
                let col0 = col.saturating_sub(1);
                let delta_new_sem = Some(value.clone());
                undo.record_delta_cell(sheet_id, row0, col0, delta_old_sem, delta_new_sem);
                undo.record_computed_cell(sheet_id, row0, col0, old_comp, new_comp);
            }
            Ok(())
        } else {
            self.engine
                .set_cell_value(sheet, row, col, value)
                .map_err(crate::engine::EditorError::from)
        }
    }

    #[inline]
    pub fn set_cell_formula(
        &mut self,
        sheet: &str,
        row: u32,
        col: u32,
        ast: ASTNode,
    ) -> Result<(), crate::engine::EditorError> {
        if self.log.is_some() {
            let old_value = self.engine.read_cell_value(sheet, row, col);
            let mut old_formula = self.engine.read_cell_formula_ast(sheet, row, col);
            let addr = self.addr_for(sheet, row, col);
            let Some(log_ptr) = self.log else {
                return Err(crate::engine::EditorError::TransactionFailed {
                    reason: "action_with_logger: missing ChangeLog".to_string(),
                });
            };

            let admitted_formula = if self.engine.graph_admission_enabled() {
                let placement =
                    CellRef::new(addr.sheet_id, Coord::from_excel(row, col, true, true));
                let ingested = self.engine.ingest_pipeline().ingest_formula(
                    FormulaAstInput::Tree(ast.clone()),
                    placement,
                    None,
                )?;
                let admission = self.engine.graph.preview_formula_mutations(&[(
                    addr.sheet_id,
                    row,
                    col,
                    ingested.dep_plan.clone(),
                )])?;
                self.engine.preflight_graph_admission(admission)?;
                Some((ingested.ast_id, ingested.dep_plan))
            } else {
                None
            };
            self.engine.demote_span_containing_cell_for_write(
                addr.sheet_id,
                addr.coord.row(),
                addr.coord.col(),
            )?;
            if old_formula.is_none() {
                old_formula = self.engine.read_cell_formula_ast(sheet, row, col);
            }
            let delta_old = if self.arrow_undo.is_some() {
                if old_formula.is_some() {
                    None
                } else {
                    Some(old_value.clone().unwrap_or(LiteralValue::Empty))
                }
            } else {
                None
            };
            let start_len = unsafe { (&*log_ptr).len() };

            // Safety: `log_ptr` comes from a unique `&mut ChangeLog` in `Engine::action_with_logger`.
            let log = unsafe { &mut *log_ptr };
            self.engine.edit_with_logger(log, |editor| {
                if let Some((ast_id, plan)) = admitted_formula {
                    editor.set_cell_formula_with_prepared_plan(
                        addr,
                        ast.clone(),
                        old_value,
                        old_formula,
                        ast_id,
                        plan,
                    );
                } else {
                    editor.set_cell_formula_with_old_state(
                        addr,
                        ast.clone(),
                        old_value,
                        old_formula,
                    );
                }
            })?;
            self.engine
                .record_formula_plane_structural_change(StructuralScope::Cell {
                    sheet: addr.sheet_id,
                    row: addr.coord.row(),
                    col: addr.coord.col(),
                });

            if let Some(undo_ptr) = self.arrow_undo {
                let new_events = &unsafe { (&*log_ptr).events() }[start_len..];
                let undo = unsafe { &mut *undo_ptr };
                self.engine
                    .record_spill_ops_into_arrow_undo(undo, new_events);
                let delta_new: Option<LiteralValue> = None;
                let sheet_id = self.engine.graph.sheet_id_mut(sheet);
                let row0 = row.saturating_sub(1);
                let col0 = col.saturating_sub(1);
                undo.record_delta_cell(sheet_id, row0, col0, delta_old, delta_new);
            }
            Ok(())
        } else {
            self.engine
                .set_cell_formula(sheet, row, col, ast)
                .map_err(crate::engine::EditorError::from)
        }
    }

    #[inline]
    pub fn set_row_hidden(
        &mut self,
        sheet: &str,
        row_1based: u32,
        hidden: bool,
        source: RowVisibilitySource,
    ) -> Result<(), crate::engine::EditorError> {
        if self.log.is_some() {
            let sheet_id = self.engine.ensure_known_sheet_id(sheet)?;
            let row0 = Engine::<R>::normalize_row_1based(row_1based)?;
            let old_hidden = self
                .engine
                .row_visibility
                .get(&sheet_id)
                .map(|state| state.is_row_hidden(row0, Some(source)))
                .unwrap_or(false);
            if old_hidden == hidden {
                return Ok(());
            }

            let _ = self
                .engine
                .set_row_hidden_by_sheet_id(sheet_id, row0, hidden, source);

            let Some(log_ptr) = self.log else {
                return Err(crate::engine::EditorError::TransactionFailed {
                    reason: "action_with_logger: missing ChangeLog".to_string(),
                });
            };
            unsafe { &mut *log_ptr }.record(crate::engine::ChangeEvent::SetRowVisibility {
                sheet_id,
                row0,
                source,
                old_hidden,
                new_hidden: hidden,
            });

            Ok(())
        } else {
            self.engine
                .set_row_hidden(sheet, row_1based, hidden, source)
        }
    }

    #[inline]
    pub fn set_rows_hidden(
        &mut self,
        sheet: &str,
        start_row_1based: u32,
        end_row_1based: u32,
        hidden: bool,
        source: RowVisibilitySource,
    ) -> Result<(), crate::engine::EditorError> {
        if self.log.is_some() {
            let sheet_id = self.engine.ensure_known_sheet_id(sheet)?;
            let (start_row0, end_row0) =
                Engine::<R>::normalize_row_range_1based(start_row_1based, end_row_1based)?;

            let Some(log_ptr) = self.log else {
                return Err(crate::engine::EditorError::TransactionFailed {
                    reason: "action_with_logger: missing ChangeLog".to_string(),
                });
            };
            let log = unsafe { &mut *log_ptr };

            for row0 in start_row0..=end_row0 {
                let old_hidden = self
                    .engine
                    .row_visibility
                    .get(&sheet_id)
                    .map(|state| state.is_row_hidden(row0, Some(source)))
                    .unwrap_or(false);
                if old_hidden == hidden {
                    continue;
                }

                let _ = self
                    .engine
                    .set_row_hidden_by_sheet_id(sheet_id, row0, hidden, source);

                log.record(crate::engine::ChangeEvent::SetRowVisibility {
                    sheet_id,
                    row0,
                    source,
                    old_hidden,
                    new_hidden: hidden,
                });
            }

            Ok(())
        } else {
            self.engine
                .set_rows_hidden(sheet, start_row_1based, end_row_1based, hidden, source)
        }
    }

    #[inline]
    pub fn insert_rows(
        &mut self,
        sheet: &str,
        before: u32,
        count: u32,
    ) -> Result<crate::engine::ShiftSummary, crate::engine::EditorError> {
        if count == 0 {
            return Ok(crate::engine::ShiftSummary::default());
        }
        if self.log.is_some() {
            let Some(log_ptr) = self.log else {
                return Err(crate::engine::EditorError::TransactionFailed {
                    reason: "action_atomic: missing ChangeLog".to_string(),
                });
            };

            let sheet_id = self.engine.graph.sheet_id_mut(sheet);
            let before0 = before.saturating_sub(1);
            let affected_region = Engine::<R>::structural_row_region(sheet_id, before0);
            // Authority geometry is not journaled. Materialize affected spans
            // before the logged graph shift so undo/redo remains exact instead
            // of leaving an unlogged shifted span behind.
            self.engine
                .demote_spans_preserving_computed_overlays(sheet_id, affected_region)?;

            // Graph structural insert (logged) - no snapshot bump.
            let summary = {
                let log = unsafe { &mut *log_ptr };
                let mut out: Result<crate::engine::ShiftSummary, crate::engine::EditorError> =
                    Ok(crate::engine::ShiftSummary::default());
                self.engine.edit_with_logger(log, |editor| {
                    out = editor.insert_rows(sheet_id, before0, count);
                })?;
                out?
            };

            // Arrow insert (truth) + undo op.
            self.engine.ensure_arrow_sheet(sheet);
            if let Some(asheet) = self.engine.arrow_sheets.sheet_mut(sheet) {
                asheet.insert_rows(before0 as usize, count as usize);
            }
            self.engine
                .shift_row_visibility_insert(sheet_id, before0, count);
            self.engine.mark_moved_formula_vertices_dirty(&summary);
            self.engine
                .clear_computed_overlay_after_row(sheet, before0 as usize);
            self.engine
                .record_formula_plane_structural_change(StructuralScope::Region(affected_region));
            self.engine.mark_topology_edited();
            if let Some(undo_ptr) = self.arrow_undo {
                unsafe { &mut *undo_ptr }.record_insert_rows(sheet_id, before0, count);
            }
            Ok(summary)
        } else {
            self.engine.insert_rows(sheet, before, count)
        }
    }

    #[inline]
    pub fn delete_rows(
        &mut self,
        sheet: &str,
        start: u32,
        count: u32,
    ) -> Result<crate::engine::ShiftSummary, crate::engine::EditorError> {
        if count == 0 {
            return Ok(crate::engine::ShiftSummary::default());
        }
        if self.atomic_policy {
            return Err(crate::engine::EditorError::TransactionUnsupported {
                reason:
                    "delete_rows is not supported inside atomic actions (conservative rollback policy)"
                        .to_string(),
            });
        }
        self.engine.delete_rows(sheet, start, count)
    }

    #[inline]
    pub fn insert_columns(
        &mut self,
        sheet: &str,
        before: u32,
        count: u32,
    ) -> Result<crate::engine::ShiftSummary, crate::engine::EditorError> {
        if count == 0 {
            return Ok(crate::engine::ShiftSummary::default());
        }
        if self.log.is_some() {
            let Some(log_ptr) = self.log else {
                return Err(crate::engine::EditorError::TransactionFailed {
                    reason: "action_atomic: missing ChangeLog".to_string(),
                });
            };

            let sheet_id = self.engine.graph.sheet_id_mut(sheet);
            let before0 = before.saturating_sub(1);
            let affected_region = Engine::<R>::structural_col_region(sheet_id, before0);
            self.engine
                .demote_spans_preserving_computed_overlays(sheet_id, affected_region)?;

            let summary = {
                let log = unsafe { &mut *log_ptr };
                let mut out: Result<crate::engine::ShiftSummary, crate::engine::EditorError> =
                    Ok(crate::engine::ShiftSummary::default());
                self.engine.edit_with_logger(log, |editor| {
                    out = editor.insert_columns(sheet_id, before0, count);
                })?;
                out?
            };

            self.engine.ensure_arrow_sheet(sheet);
            if let Some(asheet) = self.engine.arrow_sheets.sheet_mut(sheet) {
                asheet.insert_columns(before0 as usize, count as usize);
            }
            self.engine.mark_moved_formula_vertices_dirty(&summary);
            self.engine
                .clear_computed_overlay_after_col(sheet, before0 as usize);
            self.engine
                .record_formula_plane_structural_change(StructuralScope::Region(affected_region));
            self.engine.mark_topology_edited();
            if let Some(undo_ptr) = self.arrow_undo {
                unsafe { &mut *undo_ptr }.record_insert_cols(sheet_id, before0, count);
            }
            Ok(summary)
        } else {
            self.engine.insert_columns(sheet, before, count)
        }
    }

    #[inline]
    pub fn delete_columns(
        &mut self,
        sheet: &str,
        start: u32,
        count: u32,
    ) -> Result<crate::engine::ShiftSummary, crate::engine::EditorError> {
        if count == 0 {
            return Ok(crate::engine::ShiftSummary::default());
        }
        if self.atomic_policy {
            return Err(crate::engine::EditorError::TransactionUnsupported {
                reason:
                    "delete_columns is not supported inside atomic actions (conservative rollback policy)"
                        .to_string(),
            });
        }
        self.engine.delete_columns(sheet, start, count)
    }

    /// Start an action from within an action.
    ///
    /// Nested actions are currently disallowed (ticket 614), so this will return a
    /// `EditorError::TransactionFailed` while an outer action is active.
    #[inline]
    pub fn action<T>(
        &mut self,
        name: impl AsRef<str>,
        f: impl FnOnce(&mut EngineAction<'_, R>) -> Result<T, crate::engine::EditorError>,
    ) -> Result<T, crate::engine::EditorError> {
        self.engine.action(name, f)
    }
}

struct ActionDepthGuard<'a, R> {
    engine: *mut Engine<R>,
    _marker: std::marker::PhantomData<&'a mut Engine<R>>,
}

impl<'a, R> Drop for ActionDepthGuard<'a, R> {
    fn drop(&mut self) {
        // Safety: the guard is created from a unique `&mut Engine` borrow and lives no longer
        // than the surrounding `Engine::action` call.
        unsafe {
            let e = &mut *self.engine;
            e.action_depth = e.action_depth.saturating_sub(1);
        }
    }
}

#[derive(Default)]
struct SourceCache {
    scalars: FxHashMap<(String, Option<u64>), LiteralValue>,
    tables: FxHashMap<(String, Option<u64>), Arc<dyn crate::traits::Table>>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
struct VisibilityMaskCacheKey {
    sheet_id: SheetId,
    start_row0: u32,
    end_row0: u32,
    mode: VisibilityMaskMode,
    version: u64,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum StructuralScope {
    Cell { sheet: SheetId, row: u32, col: u32 },
    Region(Region),
    Sheet(SheetId),
    RemovedSheet(SheetId),
    OpaqueGlobal,
    AllSheets,
}

struct SourceCacheSession {
    cache: Arc<std::sync::RwLock<SourceCache>>,
}

impl Drop for SourceCacheSession {
    fn drop(&mut self) {
        if let Ok(mut g) = self.cache.write() {
            *g = SourceCache::default();
        }
    }
}

#[derive(Debug)]
#[non_exhaustive]
pub struct EvalResult {
    pub computed_vertices: usize,
    pub cycle_errors: usize,
    pub elapsed: std::time::Duration,
}

#[derive(Clone, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct TableMetadata {
    pub name: String,
    pub sheet: String,
    pub start_row: u32,
    pub start_col: u32,
    pub end_row: u32,
    pub end_col: u32,
    pub header_row: bool,
    pub headers: Vec<String>,
    pub totals_row: bool,
}

/// Read-only engine counters used by benchmark/instrumentation tooling.
///
/// These counters are deliberately observational: collecting them must not mutate engine state or
/// alter formula evaluation semantics.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct EngineBaselineStats {
    pub graph_vertex_count: usize,
    pub graph_formula_vertex_count: usize,
    pub graph_edge_count: usize,
    pub dirty_vertex_count: usize,
    pub evaluation_vertex_count: usize,
    pub formula_ast_root_count: usize,
    pub formula_ast_node_count: usize,
    pub staged_formula_count: usize,
    pub formula_plane_active_span_count: usize,
    pub formula_plane_producer_result_entries: usize,
    pub formula_plane_consumer_read_entries: usize,
    pub formula_plane_mixed_topology_cache_builds: u64,
    pub formula_plane_mixed_topology_cache_hits: u64,
    pub formula_plane_mixed_topology_cache_overflows: u64,
    pub formula_plane_dirty_pending_events: usize,
    pub formula_plane_dirty_region_events_recorded: u64,
    pub formula_plane_dirty_span_region_events_recorded: u64,
    pub formula_plane_dirty_whole_span_seeds_recorded: u64,
    pub formula_plane_dirty_global_invalidations: u64,
    pub formula_plane_structural_span_candidates: u64,
    /// Number of spans demoted to legacy because a member participated in a
    /// statically-cyclic SCC (gotcha G8, refs #112).
    pub formula_plane_cycle_member_span_demotions: u64,
}

#[derive(Debug, Clone, Default)]
#[non_exhaustive]
pub struct VirtualDepTelemetry {
    pub candidate_vertices_total: usize,
    pub vdeps_vertices_total: usize,
    pub vdeps_edges_total: usize,
    pub builder_elapsed_ms_total: u128,
    pub schedule_virtual_passes: usize,
    pub schedule_static_passes: usize,
    pub schedule_cache_hits: usize,
    pub schedule_cache_misses: usize,
    pub reused_schedule_vertices_total: usize,
    pub replan_iterations: usize,
    pub changed_vdeps_total: usize,
    pub bailout_reason: Option<&'static str>,
    pub fallback_mode_activations: u64,
}

/// Per-recalc telemetry for SCC evaluation under `CycleDetection::Runtime`
/// (spec `formualizer-cycle-semantics-spec.md` §10).
///
/// Collection is unconditional: SCC tasks are rare relative to ordinary
/// vertex evaluation and the counters are a handful of integer adds per
/// task, so no config flag gates them (unlike [`VirtualDepTelemetry`],
/// which pays per-schedule costs). Counters reset at the start of every
/// evaluation request.
#[derive(Debug, Clone, Default, PartialEq)]
#[non_exhaustive]
pub struct CycleTelemetry {
    /// SCC tasks executed (static SCCs that reached Runtime evaluation).
    pub static_sccs: usize,
    /// SCC tasks whose live subgraph was acyclic — values produced.
    pub phantom_sccs: usize,
    /// Distinct live cycles witnessed across all SCC tasks.
    pub live_cycles_witnessed: usize,
    /// Cells stamped `#CIRC!` by Runtime SCC tasks.
    pub circ_cells_stamped: usize,
    /// Evaluation sweeps over (subsets of) SCC members, totalled across tasks
    /// (pass 1 included).
    pub settle_passes_total: usize,
    /// Largest pass count any single SCC task needed.
    pub max_passes_single_scc: usize,
    /// SCC tasks that entered iterative calculation (`CyclePolicy::Iterate`
    /// with a witnessed live cycle). RFC #113, Stage 3.
    pub iterated_sccs: usize,
    /// Iterating SCC tasks that stopped because every member passed the
    /// spec-§6 convergence test.
    pub converged_sccs: usize,
    /// SCC tasks that stopped at a pass cap. Under `CyclePolicy::Iterate`
    /// this is the Excel `max_iterations` cap (NOT an error — last values
    /// are kept; includes the no-convergence-test `max_iterations: 1`
    /// contract). Under `CyclePolicy::Error` it is the defensive acyclic
    /// settle cap (|SCC| + 2), which only a bug can hit.
    pub capped_sccs: usize,
    /// Largest `|Δ|` observed in any member's final-pass convergence
    /// comparison across iterating SCC tasks (numeric-class members only).
    /// `0.0` when no comparison ran (e.g. `max_iterations: 1`).
    pub max_abs_delta_at_stop: f64,
    /// Identical-bit NaN vs NaN member comparisons that were treated as
    /// converged (spec §6 NaN rule).
    pub nan_converged: usize,
    /// Total wall-clock time spent inside Runtime SCC tasks.
    pub elapsed_ms: u128,
}

#[derive(Debug, Clone, Copy)]
struct ScheduleBuildMeta {
    candidate_vertices: usize,
    vdeps_vertices: usize,
    vdeps_edges: usize,
    builder_elapsed_ms: u128,
    used_virtual_schedule: bool,
    schedule_cache_hit: bool,
    schedule_cache_eligible: bool,
}

#[derive(Debug, Clone)]
struct CachedScheduleEntry {
    topology_epoch: u64,
    candidate_vertices: Vec<VertexId>,
    schedule: crate::engine::scheduler::Schedule,
}

#[derive(Clone, Debug, PartialEq, Eq)]
struct MixedTopologyCacheKey {
    engine_topology_epoch: u64,
    graph_topology_revision: u64,
    authority_indexes_epoch: u64,
    /// Explicit revisions for retained island membership and boundary views.
    /// They currently share the authoritative graph/index clocks but remain
    /// distinct key fields so future independent indexes cannot omit them.
    legacy_island_revision: u64,
    boundary_index_revision: u64,
    function_semantic_epoch: u64,
    function_provider_revision: Option<u64>,
    max_candidates: usize,
    max_edges: usize,
    max_memory_bytes: usize,
}

#[derive(Debug)]
struct CachedMixedTopology {
    key: MixedTopologyCacheKey,
    topology: MixedTopology,
    producer_results: FormulaProducerResultIndex,
    consumer_reads: FormulaConsumerReadIndex,
    span_refs_by_id: BTreeMap<FormulaSpanId, FormulaSpanRef>,
    plane_epoch: u64,
    island: LegacyIslandPlan,
}

#[derive(Debug)]
struct SkippedMixedTopology {
    reason: MixedScheduleFallbackReason,
    observed: MixedTopologyCompileStats,
    producer_results: FormulaProducerResultIndex,
    consumer_reads: FormulaConsumerReadIndex,
    span_refs_by_id: BTreeMap<FormulaSpanId, FormulaSpanRef>,
    plane_epoch: u64,
    island: LegacyIslandPlan,
}

#[derive(Debug)]
enum FormulaPlaneTopologyCompileResult {
    Cached(CachedMixedTopology),
    CacheSkipped(SkippedMixedTopology),
}

#[derive(Clone, Copy, Debug)]
struct ExactDemandScratchEstimates {
    paged: u64,
    runs: u64,
    native: u64,
    repeated: u64,
}

fn exact_demand_scratch_estimates(
    read_count: usize,
    closure_base: u64,
) -> ExactDemandScratchEstimates {
    let read_count = read_count as u64;
    let page_count = read_count.div_ceil(128);
    let run_count = read_count.div_ceil(256);
    let pointer_bytes = std::mem::size_of::<usize>() as u64;
    let keyed_entry_bytes = (std::mem::size_of::<FormulaProducerId>()
        + std::mem::size_of::<Vec<usize>>()
        + 12 * std::mem::size_of::<usize>()) as u64;
    let paged_memory = read_count.saturating_mul(keyed_entry_bytes).saturating_add(
        page_count.saturating_mul((2 * std::mem::size_of::<BTreeMap<(), ()>>()) as u64),
    );
    let runs_memory = read_count
        .saturating_mul(pointer_bytes)
        .saturating_add(run_count.saturating_mul((2 * std::mem::size_of::<Vec<usize>>()) as u64));
    ExactDemandScratchEstimates {
        paged: closure_base.saturating_add(paged_memory),
        runs: closure_base.saturating_add(runs_memory),
        native: closure_base
            .saturating_add(crate::formula_plane::scheduler::NATIVE_EXACT_DEMAND_SCRATCH_BYTES),
        repeated: closure_base.saturating_add(512),
    }
}

fn native_exact_demand_allowed(
    policy: Option<crate::engine::DiskScratchPolicy>,
    target_supports_native: bool,
) -> bool {
    target_supports_native && policy == Some(crate::engine::DiskScratchPolicy::NativeTemporary)
}

fn select_exact_demand_strategy(
    estimates: ExactDemandScratchEstimates,
    native_allowed: bool,
    mut can_reserve: impl FnMut(u64) -> bool,
) -> (FormulaPlaneTopologyStrategy, u64) {
    if can_reserve(estimates.paged) {
        (
            FormulaPlaneTopologyStrategy::ExactPagedIndexed,
            estimates.paged,
        )
    } else if can_reserve(estimates.runs) {
        (
            FormulaPlaneTopologyStrategy::ExactInMemoryRuns,
            estimates.runs,
        )
    } else if native_allowed && can_reserve(estimates.native) {
        (
            FormulaPlaneTopologyStrategy::ExactNativeScratch,
            estimates.native,
        )
    } else {
        (
            FormulaPlaneTopologyStrategy::ExactRepeatedPasses,
            estimates.repeated,
        )
    }
}

#[cfg(test)]
mod exact_demand_strategy_tests {
    use super::*;

    #[test]
    fn every_exact_demand_strategy_is_selected_by_its_scratch_rung() {
        let estimates = exact_demand_scratch_estimates(4_096, 4_096);
        assert!(estimates.paged > estimates.runs);
        assert!(estimates.runs > estimates.native);
        assert!(estimates.native > estimates.repeated);
        for (limit, native_allowed, expected) in [
            (
                estimates.paged,
                true,
                FormulaPlaneTopologyStrategy::ExactPagedIndexed,
            ),
            (
                estimates.runs,
                true,
                FormulaPlaneTopologyStrategy::ExactInMemoryRuns,
            ),
            (
                estimates.native,
                true,
                FormulaPlaneTopologyStrategy::ExactNativeScratch,
            ),
            (
                estimates.repeated,
                true,
                FormulaPlaneTopologyStrategy::ExactRepeatedPasses,
            ),
        ] {
            assert_eq!(
                select_exact_demand_strategy(estimates, native_allowed, |bytes| bytes <= limit).0,
                expected
            );
        }
    }

    #[cfg(not(target_arch = "wasm32"))]
    #[test]
    fn native_topology_scratch_drop_removes_primary_and_auxiliary_files() {
        let scratch = NativeTopologyScratch::create(u64::MAX).unwrap();
        let path = scratch.path.clone();
        let auxiliary_path = scratch.auxiliary_path.clone();
        assert!(path.exists());
        assert!(auxiliary_path.exists());
        drop(scratch);
        assert!(!path.exists());
        assert!(!auxiliary_path.exists());
    }

    #[test]
    fn native_policy_and_wasm_target_support_gate_native_rung() {
        let estimates = exact_demand_scratch_estimates(4_096, 4_096);
        assert!(!native_exact_demand_allowed(
            Some(crate::engine::DiskScratchPolicy::MemoryOnly),
            true,
        ));
        assert!(!native_exact_demand_allowed(
            Some(crate::engine::DiskScratchPolicy::NativeTemporary),
            false,
        ));
        let native_allowed = native_exact_demand_allowed(
            Some(crate::engine::DiskScratchPolicy::NativeTemporary),
            !cfg!(target_arch = "wasm32"),
        );
        let expected = if cfg!(target_arch = "wasm32") {
            FormulaPlaneTopologyStrategy::ExactRepeatedPasses
        } else {
            FormulaPlaneTopologyStrategy::ExactNativeScratch
        };
        assert_eq!(
            select_exact_demand_strategy(estimates, native_allowed, |bytes| {
                bytes <= estimates.native
            })
            .0,
            expected
        );
    }
}

#[cfg(not(target_arch = "wasm32"))]
struct NativeTopologyScratch {
    path: std::path::PathBuf,
    file: Option<std::fs::File>,
    auxiliary_path: std::path::PathBuf,
    auxiliary_file: Option<std::fs::File>,
}

#[cfg(not(target_arch = "wasm32"))]
impl NativeTopologyScratch {
    fn create(request_id: u64) -> std::io::Result<Self> {
        use std::fs::OpenOptions;
        for attempt in 0..32_u64 {
            let path = std::env::temp_dir().join(format!(
                "formualizer-topology-{request_id}-{attempt}-{}.tmp",
                std::process::id()
            ));
            match OpenOptions::new()
                .read(true)
                .write(true)
                .create_new(true)
                .open(&path)
            {
                Ok(file) => {
                    let auxiliary_path = path.with_extension("aux.tmp");
                    match OpenOptions::new()
                        .read(true)
                        .write(true)
                        .create_new(true)
                        .open(&auxiliary_path)
                    {
                        Ok(auxiliary_file) => {
                            return Ok(Self {
                                path,
                                file: Some(file),
                                auxiliary_path,
                                auxiliary_file: Some(auxiliary_file),
                            });
                        }
                        Err(error) => {
                            drop(file);
                            let _ = std::fs::remove_file(&path);
                            if error.kind() == std::io::ErrorKind::AlreadyExists {
                                continue;
                            }
                            return Err(error);
                        }
                    }
                }
                Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => continue,
                Err(error) => return Err(error),
            }
        }
        Err(std::io::Error::new(
            std::io::ErrorKind::AlreadyExists,
            "could not allocate unique topology scratch file",
        ))
    }
}

#[cfg(not(target_arch = "wasm32"))]
impl Drop for NativeTopologyScratch {
    fn drop(&mut self) {
        drop(self.file.take());
        drop(self.auxiliary_file.take());
        let _ = std::fs::remove_file(&self.path);
        let _ = std::fs::remove_file(&self.auxiliary_path);
    }
}

fn estimated_span_bindings_bytes(
    bindings: &BTreeMap<FormulaSpanId, FormulaSpanRef>,
) -> Option<usize> {
    const TREE_ENTRY_OVERHEAD: usize = 4 * std::mem::size_of::<usize>();
    bindings.len().checked_mul(
        std::mem::size_of::<FormulaSpanId>()
            .checked_add(std::mem::size_of::<FormulaSpanRef>())?
            .checked_add(TREE_ENTRY_OVERHEAD)?,
    )
}

type ScheduleBuildOutput = (
    crate::engine::scheduler::Schedule,
    FxHashMap<VertexId, Vec<VertexId>>,
    ScheduleBuildMeta,
);

/// Opaque, revision-bound recalculation recipe.
#[derive(Debug)]
pub struct RecalcPlan {
    key: RecalcPlanKey,
    kind: RecalcPlanKind,
}

#[derive(Debug)]
struct RecalcPlanKey {
    engine_token: Arc<()>,
    revisions: PlanningRevisionSnapshot,
}

#[derive(Clone, Debug, PartialEq, Eq)]
struct PlanningRevisionSnapshot {
    engine_topology_epoch: u64,
    graph_topology_revision: u64,
    authority: u64,
    authority_indexes: u64,
    authority_indexed_plane: u64,
    staged: u64,
    symbols: u64,
    semantic: u64,
    provider: Option<u64>,
    formula_plane_mode: FormulaPlaneMode,
    deterministic_mode: crate::engine::DeterministicMode,
    budgets: crate::engine::EvaluationBudgets,
    span_refs: Vec<FormulaSpanRef>,
}

#[derive(Debug)]
enum RecalcPlanKind {
    CompatibilityFull {
        schedule: crate::engine::Schedule,
        has_dynamic_refs: bool,
    },
    Target {
        targets: Vec<crate::engine::EvaluationTarget>,
        scope: crate::engine::PrepareScope,
        topology: RecalcTopology,
        dynamic_policy: DynamicPlanPolicy,
    },
}

#[derive(Debug)]
enum RecalcTopology {
    RunLocalRecipe,
    Workbook,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum DynamicPlanPolicy {
    BoundedTargetReplan,
}

impl RecalcPlan {
    /// Returns the retained compatibility schedule depth. Target plans retain a
    /// run-local recipe rather than a schedule, so their layer count is zero.
    pub fn layer_count(&self) -> usize {
        match &self.kind {
            RecalcPlanKind::CompatibilityFull { schedule, .. } => schedule.layers.len(),
            RecalcPlanKind::Target { .. } => 0,
        }
    }

    pub fn has_dynamic_refs(&self) -> bool {
        match &self.kind {
            RecalcPlanKind::CompatibilityFull {
                has_dynamic_refs, ..
            } => *has_dynamic_refs,
            RecalcPlanKind::Target { .. } => false,
        }
    }

    #[cfg(test)]
    pub(crate) fn force_stale_reasons_for_test(
        &mut self,
        reasons: &[formualizer_common::PlanStaleReason],
    ) {
        use formualizer_common::PlanStaleReason;
        for reason in reasons {
            match reason {
                PlanStaleReason::Engine => {
                    self.key.engine_token = Arc::new(());
                }
                PlanStaleReason::Provider => {
                    self.key.revisions.provider = Some(
                        self.key
                            .revisions
                            .provider
                            .unwrap_or_default()
                            .wrapping_add(1),
                    );
                }
                PlanStaleReason::Semantic => {
                    self.key.revisions.semantic = self.key.revisions.semantic.wrapping_add(1);
                }
                PlanStaleReason::Budget => {
                    let current = self.key.revisions.budgets.work.max_work_units;
                    self.key.revisions.budgets.work.max_work_units =
                        Some(current.unwrap_or_default().wrapping_add(1));
                }
                PlanStaleReason::Staged => {
                    self.key.revisions.staged = self.key.revisions.staged.wrapping_add(1);
                }
                PlanStaleReason::Symbols => {
                    self.key.revisions.symbols = self.key.revisions.symbols.wrapping_add(1);
                }
                PlanStaleReason::Authority => {
                    self.key.revisions.authority = self.key.revisions.authority.wrapping_add(1);
                }
                PlanStaleReason::SpanGeneration => {
                    self.key.revisions.span_refs.push(FormulaSpanRef {
                        id: crate::formula_plane::runtime::FormulaSpanId(u32::MAX),
                        generation: u32::MAX,
                        version: u32::MAX,
                    });
                }
                PlanStaleReason::Graph => {
                    self.key.revisions.graph_topology_revision =
                        self.key.revisions.graph_topology_revision.wrapping_add(1);
                }
                _ => {}
            }
        }
    }
}

#[cfg(test)]
pub(crate) mod criteria_mask_test_hooks {
    use std::cell::Cell;

    thread_local! {
        static TEXT_SEGMENTS_TOTAL: Cell<usize> = const { Cell::new(0) };
        static TEXT_SEGMENTS_ALL_NULL: Cell<usize> = const { Cell::new(0) };
    }

    pub fn reset_text_segment_counters() {
        TEXT_SEGMENTS_TOTAL.with(|c| c.set(0));
        TEXT_SEGMENTS_ALL_NULL.with(|c| c.set(0));
    }

    pub fn text_segment_counters() -> (usize, usize) {
        let a = TEXT_SEGMENTS_TOTAL.with(|c| c.get());
        let b = TEXT_SEGMENTS_ALL_NULL.with(|c| c.get());
        (a, b)
    }

    pub(crate) fn inc_total() {
        TEXT_SEGMENTS_TOTAL.with(|c| c.set(c.get() + 1));
    }
    pub(crate) fn inc_all_null() {
        TEXT_SEGMENTS_ALL_NULL.with(|c| c.set(c.get() + 1));
    }
}

#[cfg(test)]
pub(crate) mod visibility_mask_test_hooks {
    use std::cell::Cell;

    thread_local! {
        static HITS: Cell<usize> = const { Cell::new(0) };
        static MISSES: Cell<usize> = const { Cell::new(0) };
        static EVICTIONS: Cell<usize> = const { Cell::new(0) };
    }

    pub fn reset() {
        HITS.with(|c| c.set(0));
        MISSES.with(|c| c.set(0));
        EVICTIONS.with(|c| c.set(0));
    }

    pub fn counters() -> (usize, usize, usize) {
        let hits = HITS.with(|c| c.get());
        let misses = MISSES.with(|c| c.get());
        let evictions = EVICTIONS.with(|c| c.get());
        (hits, misses, evictions)
    }

    pub(crate) fn inc_hit() {
        HITS.with(|c| c.set(c.get() + 1));
    }

    pub(crate) fn inc_miss() {
        MISSES.with(|c| c.set(c.get() + 1));
    }

    pub(crate) fn inc_eviction() {
        EVICTIONS.with(|c| c.set(c.get() + 1));
    }
}

fn compute_criteria_mask(
    view: &RangeView<'_>,
    col_in_view: usize,
    pred: &crate::args::CriteriaPredicate,
) -> Option<std::sync::Arc<arrow_array::BooleanArray>> {
    use crate::compute_prelude::{boolean, cmp, concat_arrays};
    use arrow::compute::kernels::comparison::{ilike, nilike};
    use arrow_array::{
        Array as _, ArrayRef, BooleanArray, Float64Array, StringArray, builder::BooleanBuilder,
    };

    // Helper: apply a numeric predicate to a single Float64Array chunk
    fn apply_numeric_pred(
        chunk: &Float64Array,
        pred: &crate::args::CriteriaPredicate,
    ) -> Option<BooleanArray> {
        match pred {
            crate::args::CriteriaPredicate::Gt(n) => {
                cmp::gt(chunk, &Float64Array::new_scalar(*n)).ok()
            }
            crate::args::CriteriaPredicate::Ge(n) => {
                cmp::gt_eq(chunk, &Float64Array::new_scalar(*n)).ok()
            }
            crate::args::CriteriaPredicate::Lt(n) => {
                cmp::lt(chunk, &Float64Array::new_scalar(*n)).ok()
            }
            crate::args::CriteriaPredicate::Le(n) => {
                cmp::lt_eq(chunk, &Float64Array::new_scalar(*n)).ok()
            }
            crate::args::CriteriaPredicate::Eq(v) => match v {
                formualizer_common::LiteralValue::Number(x) => {
                    cmp::eq(chunk, &Float64Array::new_scalar(*x)).ok()
                }
                formualizer_common::LiteralValue::Int(i) => {
                    cmp::eq(chunk, &Float64Array::new_scalar(*i as f64)).ok()
                }
                _ => None,
            },
            crate::args::CriteriaPredicate::Ne(v) => match v {
                formualizer_common::LiteralValue::Number(x) => {
                    cmp::neq(chunk, &Float64Array::new_scalar(*x)).ok()
                }
                formualizer_common::LiteralValue::Int(i) => {
                    cmp::neq(chunk, &Float64Array::new_scalar(*i as f64)).ok()
                }
                _ => None,
            },
            _ => None,
        }
    }

    // Check if this is a numeric predicate that can be applied per-chunk
    let is_numeric_pred = matches!(
        pred,
        crate::args::CriteriaPredicate::Gt(_)
            | crate::args::CriteriaPredicate::Ge(_)
            | crate::args::CriteriaPredicate::Lt(_)
            | crate::args::CriteriaPredicate::Le(_)
            | crate::args::CriteriaPredicate::Eq(formualizer_common::LiteralValue::Number(_))
            | crate::args::CriteriaPredicate::Eq(formualizer_common::LiteralValue::Int(_))
            | crate::args::CriteriaPredicate::Ne(formualizer_common::LiteralValue::Number(_))
            | crate::args::CriteriaPredicate::Ne(formualizer_common::LiteralValue::Int(_))
    );

    // OPTIMIZED PATH: For numeric predicates, apply per-chunk and concatenate boolean masks.
    // This avoids materializing the full numeric column (64-bit per element) and instead
    // concatenates boolean masks (1-bit per element) - a 64x memory reduction.
    if is_numeric_pred {
        let mut bool_parts: Vec<BooleanArray> = Vec::new();
        for res in view.numbers_slices() {
            let (_rs, _rl, cols_seg) = res.ok()?;
            if col_in_view < cols_seg.len() {
                let chunk = cols_seg[col_in_view].as_ref();
                let mask = apply_numeric_pred(chunk, pred)?;
                bool_parts.push(mask);
            }
        }

        if bool_parts.is_empty() {
            return None;
        } else if bool_parts.len() == 1 {
            return Some(std::sync::Arc::new(bool_parts.remove(0)));
        } else {
            // Concatenate boolean masks (much cheaper than concatenating Float64 arrays)
            let anys: Vec<&dyn arrow_array::Array> = bool_parts
                .iter()
                .map(|a| a as &dyn arrow_array::Array)
                .collect();
            let conc: ArrayRef = concat_arrays(&anys).ok()?;
            let ba = conc.as_any().downcast_ref::<BooleanArray>()?.clone();
            return Some(std::sync::Arc::new(ba));
        }
    }

    // TEXT PATH: build masks per row-chunk using lowered text slices.
    // This avoids concatenating full-string columns just to compute a boolean mask.
    let (text_kind, text_pat, empty_special) = match pred {
        crate::args::CriteriaPredicate::Eq(formualizer_common::LiteralValue::Text(t)) => {
            (0u8, t.to_lowercase(), t.is_empty())
        }
        crate::args::CriteriaPredicate::Ne(formualizer_common::LiteralValue::Text(t)) => {
            (1u8, t.to_lowercase(), false)
        }
        crate::args::CriteriaPredicate::TextLike {
            pattern,
            case_insensitive,
        } => {
            let p = if *case_insensitive {
                pattern.to_lowercase()
            } else {
                pattern.clone()
            };
            (2u8, p.replace('*', "%").replace('?', "_"), false)
        }
        _ => return None,
    };

    let ne_matches_blank = text_kind == 1 && !text_pat.is_empty();
    let pat = StringArray::new_scalar(text_pat);
    let mut bool_parts: Vec<BooleanArray> = Vec::new();

    for res in view.iter_row_chunks() {
        let cs = res.ok()?;
        if cs.row_len == 0 {
            continue;
        }
        #[cfg(test)]
        criteria_mask_test_hooks::inc_total();

        let slices = view.slice_lowered_text(cs.row_start, cs.row_len);
        if col_in_view >= slices.len() {
            return None;
        }

        let seg_opt = slices[col_in_view].as_ref().map(|a| a.as_ref());
        let seg = match seg_opt {
            Some(s) => s,
            None => {
                #[cfg(test)]
                criteria_mask_test_hooks::inc_all_null();
                if (text_kind == 0 && empty_special) || ne_matches_blank {
                    // Eq("") treats nulls (Empty) as equal.
                    let mut bb = BooleanBuilder::with_capacity(cs.row_len);
                    bb.append_n(cs.row_len, true);
                    bool_parts.push(bb.finish());
                } else {
                    // For non-empty patterns, ilike/nilike return null on null inputs.
                    bool_parts.push(BooleanArray::new_null(cs.row_len));
                }
                continue;
            }
        };

        let seg_sa = seg.as_any().downcast_ref::<StringArray>()?;
        let mut m = match text_kind {
            0 => ilike(seg_sa, &pat).ok()?,
            1 => nilike(seg_sa, &pat).ok()?,
            2 => ilike(seg_sa, &pat).ok()?,
            _ => return None,
        };

        // Only fold blank/Empty (null) cells into the mask when the segment
        // actually contains any. The null-fill loop + or_kleene are pure
        // overhead on blank-free chunks, so a `<>text` (or `=""`) aggregation
        // over a column with no blanks stays fully vectorized on the ilike/
        // nilike result.
        if ((text_kind == 0 && empty_special) || ne_matches_blank) && seg_sa.null_count() > 0 {
            // Treat nulls as equal to empty string
            let mut bb = BooleanBuilder::with_capacity(seg_sa.len());
            for i in 0..seg_sa.len() {
                bb.append_value(seg_sa.is_null(i));
            }
            let nulls = bb.finish();
            m = boolean::or_kleene(&m, &nulls).ok()?;
        }

        bool_parts.push(m);
    }

    if bool_parts.is_empty() {
        None
    } else if bool_parts.len() == 1 {
        Some(std::sync::Arc::new(bool_parts.remove(0)))
    } else {
        let anys: Vec<&dyn arrow_array::Array> = bool_parts
            .iter()
            .map(|a| a as &dyn arrow_array::Array)
            .collect();
        let conc: ArrayRef = concat_arrays(&anys).ok()?;
        let ba = conc.as_any().downcast_ref::<BooleanArray>()?.clone();
        Some(std::sync::Arc::new(ba))
    }
}

#[derive(Debug, Clone)]
pub struct LayerInfo {
    pub vertex_count: usize,
    pub parallel_eligible: bool,
    pub sample_cells: Vec<String>, // Sample of up to 5 cell addresses
}

#[derive(Debug, Clone)]
pub struct EvalPlan {
    pub total_vertices_to_evaluate: usize,
    pub layers: Vec<LayerInfo>,
    pub cycles_detected: usize,
    pub dirty_count: usize,
    pub volatile_count: usize,
    pub parallel_enabled: bool,
    pub estimated_parallel_layers: usize,
    pub target_cells: Vec<String>,
}

impl<R> Engine<R>
where
    R: EvaluationContext,
{
    /// # Panics
    /// Panics when `config.cycle` is invalid ([`CycleConfig::validate`],
    /// spec §2): `Iterate` with `detection: Static`, `max_iterations == 0`,
    /// or a negative/non-finite `max_change`. `EvalConfig::with_cycle`
    /// rejects these at build; this re-validates configs assembled via
    /// struct literals.
    pub fn new(resolver: R, config: EvalConfig) -> Self {
        if let Err(msg) = config.cycle.validate() {
            panic!("invalid CycleConfig: {msg}");
        }
        crate::builtins::load_builtins();
        let resolved_resources = crate::engine::resource_ledger::resolve_evaluation_budgets(
            &config.evaluation_budgets,
            config.max_vertices,
            config.max_memory_mb,
            config.max_eval_time,
        );

        let clock = config.deterministic_mode.build_clock().unwrap_or_else(|_| {
            #[cfg(feature = "system-clock")]
            {
                Arc::new(crate::timezone::SystemClock::new(
                    crate::timezone::TimeZoneSpec::default(),
                ))
            }
            #[cfg(not(feature = "system-clock"))]
            {
                Arc::new(crate::timezone::FixedClock::new(
                    chrono::DateTime::UNIX_EPOCH,
                    crate::timezone::TimeZoneSpec::Utc,
                ))
            }
        });

        // Initialize thread pool based on config
        let thread_pool = if config.enable_parallel {
            let mut builder = ThreadPoolBuilder::new();
            if let Some(max_threads) = config.max_threads {
                builder = builder.num_threads(max_threads);
            }

            match builder.build() {
                Ok(pool) => Some(Arc::new(pool)),
                Err(_) => {
                    // Fall back to sequential evaluation if thread pool creation fails
                    None
                }
            }
        } else {
            None
        };

        // C1a retained/cache budgets are observational; cache defaults stay explicit.
        let lookup_cache_max_bytes = config.lookup_index_cache_max_bytes;
        let function_provider_revision_seen = resolver.planning_semantic_revision();
        let mut engine = Self {
            graph: DependencyGraph::new_with_config(config.clone()),
            resolver,
            config,
            workbook_load_limits: crate::engine::WorkbookLoadLimits::default(),
            clock: crate::timezone::SnapshotClock::new(clock),
            thread_pool,
            recalc_epoch: 0,
            snapshot_id: std::sync::atomic::AtomicU64::new(1),
            topology_epoch: 0,
            legacy_island_structural_summaries_trusted: true,
            cached_static_schedule: None,
            cached_mixed_topology: None,
            mixed_topology_cache_builds: 0,
            mixed_topology_cache_hits: 0,
            mixed_topology_cache_overflows: 0,
            mixed_topology_cache_skip_streak: 0,
            spill_mgr: ShimSpillManager::default(),
            arrow_sheets: SheetStore::default(),
            has_edited: false,
            overlay_compactions: 0,
            computed_overlay_bytes_estimate: 0,
            computed_overlay_mirroring_disabled: false,
            force_materialize_range_views: false,
            row_bounds_cache: std::sync::RwLock::new(None),
            used_axis_bounds_cache: std::sync::RwLock::new(None),
            lookup_index_cache: LookupIndexCache::new(lookup_cache_max_bytes),
            source_cache: Arc::new(std::sync::RwLock::new(SourceCache::default())),
            source_formula_token: Arc::new(()),
            recalc_plan_token: Arc::new(()),
            staged_formulas: std::collections::HashMap::new(),
            staged_formula_index: StagedFormulaIndex::default(),
            row_visibility: FxHashMap::default(),
            row_visibility_mask_cache: std::sync::RwLock::new(FxHashMap::default()),
            formula_parse_diagnostics: Vec::new(),
            last_formula_ingest_report: None,
            formula_ingest_report_total: FormulaIngestReport::default(),
            formula_plane_cycle_member_span_demotions: 0,
            formula_plane_capacity_bailouts: 0,
            formula_plane_structural_span_candidates: 0,
            active_cancel_flag: None,
            active_evaluation_deadline: None,
            action_depth: 0,
            last_virtual_dep_telemetry: VirtualDepTelemetry::default(),
            virtual_dep_fallback_activations: 0,
            last_cycle_telemetry: CycleTelemetry::default(),
            next_evaluation_resource_request_id: 1,
            evaluation_resource_request_depth: 0,
            active_evaluation_resource_request: None,
            last_evaluation_resource_request: None,
            evaluation_resource_baseline: EvaluationResourceBaselineStats::default(),
            evaluation_resource_request_started_at: None,
            evaluation_resource_budgets: resolved_resources.budgets,
            evaluation_resource_config_diagnostic: resolved_resources.diagnostic,
            active_resource_ledger: None,
            pending_iterative_redirty: Vec::new(),
            iterative_state_values: FxHashMap::default(),
            function_semantic_epoch_seen: crate::function_registry::semantic_epoch(),
            function_provider_revision_seen,
            #[cfg(test)]
            last_formula_plane_span_eval_report: None,
            #[cfg(test)]
            evaluation_request_begin_count_for_test: 0,
            #[cfg(any(test, feature = "test-support"))]
            before_prepared_span_commit_hook: None,
            #[cfg(test)]
            before_target_preparation_commit_hook: None,
            #[cfg(test)]
            before_target_planning_snapshot_hook: None,
            #[cfg(test)]
            inject_target_semantic_stale_once_for_test: false,
            #[cfg(test)]
            force_virtual_dep_changes_remaining_for_test: 0,
            #[cfg(test)]
            fail_evaluation_commit_preflight_once_for_test: false,
            #[cfg(test)]
            force_source_family_fallback: false,
            #[cfg(test)]
            rerecord_cycle_retry_span_after_lease_extension_for_test: false,
            #[cfg(test)]
            fragmented_commit_fault_for_test: None,
            #[cfg(test)]
            formula_span_demotion_fault_for_test: None,
            #[cfg(test)]
            target_preparation_fault_for_test: None,
            #[cfg(test)]
            force_non_cycle_schedule_fallback_for_test: false,
            #[cfg(test)]
            mixed_topology_index_builds_for_test: 0,
            #[cfg(test)]
            before_legacy_fallback_final_provider_sample_hook: None,
            #[cfg(test)]
            after_eager_proposal_commit_hook: None,
        };
        // Phase 1 (ticket 610): Arrow-truth is the only supported mode.
        engine.config.arrow_storage_enabled = true;
        engine.config.delta_overlay_enabled = true;
        engine.config.write_formula_overlay_enabled = true;
        let default_sheet = engine.graph.default_sheet_name().to_string();
        engine.ensure_arrow_sheet(&default_sheet);
        engine
    }

    /// Create an Engine with a custom thread pool (for shared thread pool scenarios)
    ///
    /// # Panics
    /// Panics when `config.cycle` is invalid, exactly like [`Engine::new`].
    pub fn with_thread_pool(
        resolver: R,
        config: EvalConfig,
        thread_pool: Arc<rayon::ThreadPool>,
    ) -> Self {
        if let Err(msg) = config.cycle.validate() {
            panic!("invalid CycleConfig: {msg}");
        }
        crate::builtins::load_builtins();
        let resolved_resources = crate::engine::resource_ledger::resolve_evaluation_budgets(
            &config.evaluation_budgets,
            config.max_vertices,
            config.max_memory_mb,
            config.max_eval_time,
        );
        let clock = config.deterministic_mode.build_clock().unwrap_or_else(|_| {
            #[cfg(feature = "system-clock")]
            {
                Arc::new(crate::timezone::SystemClock::new(
                    crate::timezone::TimeZoneSpec::default(),
                ))
            }
            #[cfg(not(feature = "system-clock"))]
            {
                Arc::new(crate::timezone::FixedClock::new(
                    chrono::DateTime::UNIX_EPOCH,
                    crate::timezone::TimeZoneSpec::Utc,
                ))
            }
        });
        // C1a retained/cache budgets are observational; cache defaults stay explicit.
        let lookup_cache_max_bytes = config.lookup_index_cache_max_bytes;
        let function_provider_revision_seen = resolver.planning_semantic_revision();
        let mut engine = Self {
            graph: DependencyGraph::new_with_config(config.clone()),
            resolver,
            config,
            workbook_load_limits: crate::engine::WorkbookLoadLimits::default(),
            clock: crate::timezone::SnapshotClock::new(clock),
            thread_pool: Some(thread_pool),
            recalc_epoch: 0,
            snapshot_id: std::sync::atomic::AtomicU64::new(1),
            topology_epoch: 0,
            legacy_island_structural_summaries_trusted: true,
            cached_static_schedule: None,
            cached_mixed_topology: None,
            mixed_topology_cache_builds: 0,
            mixed_topology_cache_hits: 0,
            mixed_topology_cache_overflows: 0,
            mixed_topology_cache_skip_streak: 0,
            spill_mgr: ShimSpillManager::default(),
            arrow_sheets: SheetStore::default(),
            has_edited: false,
            overlay_compactions: 0,
            computed_overlay_bytes_estimate: 0,
            computed_overlay_mirroring_disabled: false,
            force_materialize_range_views: false,
            row_bounds_cache: std::sync::RwLock::new(None),
            used_axis_bounds_cache: std::sync::RwLock::new(None),
            lookup_index_cache: LookupIndexCache::new(lookup_cache_max_bytes),
            source_cache: Arc::new(std::sync::RwLock::new(SourceCache::default())),
            source_formula_token: Arc::new(()),
            recalc_plan_token: Arc::new(()),
            staged_formulas: std::collections::HashMap::new(),
            staged_formula_index: StagedFormulaIndex::default(),
            row_visibility: FxHashMap::default(),
            row_visibility_mask_cache: std::sync::RwLock::new(FxHashMap::default()),
            formula_parse_diagnostics: Vec::new(),
            last_formula_ingest_report: None,
            formula_ingest_report_total: FormulaIngestReport::default(),
            formula_plane_cycle_member_span_demotions: 0,
            formula_plane_capacity_bailouts: 0,
            formula_plane_structural_span_candidates: 0,
            active_cancel_flag: None,
            active_evaluation_deadline: None,
            action_depth: 0,
            last_virtual_dep_telemetry: VirtualDepTelemetry::default(),
            virtual_dep_fallback_activations: 0,
            last_cycle_telemetry: CycleTelemetry::default(),
            next_evaluation_resource_request_id: 1,
            evaluation_resource_request_depth: 0,
            active_evaluation_resource_request: None,
            last_evaluation_resource_request: None,
            evaluation_resource_baseline: EvaluationResourceBaselineStats::default(),
            evaluation_resource_request_started_at: None,
            evaluation_resource_budgets: resolved_resources.budgets,
            evaluation_resource_config_diagnostic: resolved_resources.diagnostic,
            active_resource_ledger: None,
            pending_iterative_redirty: Vec::new(),
            iterative_state_values: FxHashMap::default(),
            function_semantic_epoch_seen: crate::function_registry::semantic_epoch(),
            function_provider_revision_seen,
            #[cfg(test)]
            last_formula_plane_span_eval_report: None,
            #[cfg(test)]
            evaluation_request_begin_count_for_test: 0,
            #[cfg(any(test, feature = "test-support"))]
            before_prepared_span_commit_hook: None,
            #[cfg(test)]
            before_target_preparation_commit_hook: None,
            #[cfg(test)]
            before_target_planning_snapshot_hook: None,
            #[cfg(test)]
            inject_target_semantic_stale_once_for_test: false,
            #[cfg(test)]
            force_virtual_dep_changes_remaining_for_test: 0,
            #[cfg(test)]
            fail_evaluation_commit_preflight_once_for_test: false,
            #[cfg(test)]
            force_source_family_fallback: false,
            #[cfg(test)]
            rerecord_cycle_retry_span_after_lease_extension_for_test: false,
            #[cfg(test)]
            fragmented_commit_fault_for_test: None,
            #[cfg(test)]
            formula_span_demotion_fault_for_test: None,
            #[cfg(test)]
            target_preparation_fault_for_test: None,
            #[cfg(test)]
            force_non_cycle_schedule_fallback_for_test: false,
            #[cfg(test)]
            mixed_topology_index_builds_for_test: 0,
            #[cfg(test)]
            before_legacy_fallback_final_provider_sample_hook: None,
            #[cfg(test)]
            after_eager_proposal_commit_hook: None,
        };
        // Phase 1 (ticket 610): Arrow-truth is the only supported mode.
        engine.config.arrow_storage_enabled = true;
        engine.config.delta_overlay_enabled = true;
        engine.config.write_formula_overlay_enabled = true;
        let default_sheet = engine.graph.default_sheet_name().to_string();
        engine.ensure_arrow_sheet(&default_sheet);
        engine
    }

    pub fn workbook_load_limits(&self) -> &crate::engine::WorkbookLoadLimits {
        &self.workbook_load_limits
    }

    pub fn set_workbook_load_limits(&mut self, limits: crate::engine::WorkbookLoadLimits) {
        self.workbook_load_limits = limits;
    }

    fn clear_source_cache(&self) {
        if let Ok(mut g) = self.source_cache.write() {
            *g = SourceCache::default();
        }
    }

    pub fn last_virtual_dep_telemetry(&self) -> &VirtualDepTelemetry {
        &self.last_virtual_dep_telemetry
    }

    /// Telemetry from Runtime SCC evaluation during the most recent
    /// evaluation request (always default-zero under `CycleDetection::Static`
    /// or when `enable_virtual_dep_telemetry` is off).
    pub fn last_cycle_telemetry(&self) -> &CycleTelemetry {
        &self.last_cycle_telemetry
    }

    /// Resource observations for the most recently completed public evaluation request.
    pub fn last_evaluation_resource_request_stats(
        &self,
    ) -> Option<&EvaluationResourceRequestStats> {
        self.last_evaluation_resource_request.as_ref()
    }

    /// Cumulative resource observations since engine creation or the last telemetry reset.
    pub fn evaluation_resource_baseline_stats(&self) -> EvaluationResourceBaselineStats {
        self.evaluation_resource_baseline
    }

    pub fn evaluation_resource_budgets(&self) -> &crate::engine::EvaluationBudgets {
        &self.evaluation_resource_budgets
    }

    /// At most one diagnostic is emitted for deprecated resource fields.
    pub fn evaluation_resource_config_diagnostic(
        &self,
    ) -> Option<&crate::engine::EvaluationResourceConfigDiagnostic> {
        self.evaluation_resource_config_diagnostic.as_ref()
    }

    /// Reset accumulated and last-request observations without reusing request IDs.
    pub fn reset_evaluation_resource_telemetry(&mut self) {
        self.evaluation_resource_baseline = EvaluationResourceBaselineStats::default();
        self.last_evaluation_resource_request = None;
    }

    fn duration_ns(duration: std::time::Duration) -> u64 {
        u64::try_from(duration.as_nanos()).unwrap_or(u64::MAX)
    }

    fn observe_evaluation_resource_request<T>(
        &mut self,
        kind: EvaluationRequestKind,
        evaluate: impl FnOnce(&mut Self) -> Result<T, ExcelError>,
    ) -> Result<T, ExcelError> {
        let outermost = self.evaluation_resource_request_depth == 0;
        if outermost {
            let request_id = self.next_evaluation_resource_request_id;
            self.next_evaluation_resource_request_id = request_id
                .checked_add(1)
                .expect("evaluation resource request ID exhausted");
            self.active_evaluation_resource_request = Some(EvaluationResourceRequestStats::new(
                request_id,
                kind,
                self.config.formula_plane_mode,
                self.staged_formula_count(),
            ));
            self.evaluation_resource_baseline.record_started(request_id);
            self.evaluation_resource_request_started_at = Some(crate::instant::FzInstant::now());
            self.active_resource_ledger = Some(ResourceLedger::new(
                Some(request_id),
                self.evaluation_resource_budgets.clone(),
            ));
        }
        self.evaluation_resource_request_depth =
            self.evaluation_resource_request_depth.saturating_add(1);
        let result = if outermost {
            self.resource_checkpoint(0).and_then(|()| evaluate(self))
        } else {
            evaluate(self)
        };
        self.evaluation_resource_request_depth =
            self.evaluation_resource_request_depth.saturating_sub(1);

        if outermost {
            let total_ns = self
                .evaluation_resource_request_started_at
                .take()
                .map(|start| Self::duration_ns(start.elapsed()))
                .unwrap_or(0);
            let mut stats = self
                .active_evaluation_resource_request
                .take()
                .expect("outer evaluation resource request has active stats");
            let mut ledger = self
                .active_resource_ledger
                .take()
                .expect("outer evaluation resource request has active ledger");
            ledger.release_all_scratch();
            stats.ledger.update(ledger.snapshot());
            stats.outcome = match &result {
                Ok(_) => EvaluationRequestOutcome::Success,
                Err(error) if error.kind == ExcelErrorKind::Cancelled => {
                    EvaluationRequestOutcome::Cancelled
                }
                Err(_) => EvaluationRequestOutcome::Error,
            };
            if stats.dirty_lease == FormulaDirtyLeaseOutcome::Acquired {
                stats.dirty_lease = if stats.outcome == EvaluationRequestOutcome::Cancelled {
                    FormulaDirtyLeaseOutcome::RetainedOnCancellation
                } else {
                    FormulaDirtyLeaseOutcome::RetainedOnError
                };
            }
            stats.phases.total_ns = total_ns;
            let attributed = stats
                .phases
                .staged_prepare_ns
                .saturating_add(stats.phases.topology_ns)
                .saturating_add(stats.phases.materialization_ns);
            stats.phases.evaluation_ns = total_ns.saturating_sub(attributed);
            self.evaluation_resource_baseline.record_finished(&stats);
            self.last_evaluation_resource_request = Some(stats);
        }
        result
    }

    pub fn set_evaluation_resource_budgets(&mut self, budgets: crate::engine::EvaluationBudgets) {
        self.evaluation_resource_budgets = budgets.clone();
        self.config.evaluation_budgets = budgets.clone();
        self.graph.set_evaluation_budgets(budgets);
    }

    #[cfg(test)]
    pub(crate) fn set_evaluation_budgets_for_test(
        &mut self,
        budgets: crate::engine::EvaluationBudgets,
    ) {
        self.set_evaluation_resource_budgets(budgets);
    }

    fn resource_loop_checkpoint(
        ledger: &mut Option<ResourceLedger>,
        work_units: u64,
    ) -> Result<(), ExcelError> {
        ledger
            .as_mut()
            .map_or(Ok(()), |ledger| {
                ledger
                    .charge_work(work_units)
                    .and_then(|()| ledger.checkpoint_deadline())
            })
            .map_err(crate::engine::ResourceLedgerError::into_excel_error)
    }

    fn preflight_evaluation_commit_window(
        &mut self,
        bounded_writes: usize,
    ) -> Result<crate::instant::FzInstant, ExcelError> {
        #[cfg(test)]
        if std::mem::take(&mut self.fail_evaluation_commit_preflight_once_for_test) {
            return Err(crate::engine::ResourceLedgerError::Exhausted(
                formualizer_common::ResourceExhaustionDetail {
                    reason: formualizer_common::ResourceExhaustionReason::Deadline,
                    limit: 0,
                    observed: 1,
                    request_id: self
                        .active_evaluation_resource_request
                        .as_ref()
                        .map(|stats| stats.request_id),
                },
            )
            .into_excel_error());
        }
        let estimate = std::time::Duration::from_nanos(
            u64::try_from(bounded_writes)
                .unwrap_or(u64::MAX)
                .saturating_mul(100),
        );
        if let Some(ledger) = self.active_resource_ledger.as_mut() {
            ledger
                .preflight_commit_window(estimate)
                .map_err(crate::engine::ResourceLedgerError::into_excel_error)?;
        }
        if let Some(stats) = self.active_evaluation_resource_request.as_mut() {
            stats.evaluation_commit_preflight_count =
                stats.evaluation_commit_preflight_count.saturating_add(1);
            stats.evaluation_commit_estimated_ns = stats
                .evaluation_commit_estimated_ns
                .saturating_add(Self::duration_ns(estimate));
        }
        Ok(crate::instant::FzInstant::now())
    }

    fn observe_evaluation_commit_window(&mut self, started: crate::instant::FzInstant) {
        if let Some(stats) = self.active_evaluation_resource_request.as_mut() {
            stats.evaluation_commit_actual_ns = stats
                .evaluation_commit_actual_ns
                .saturating_add(Self::duration_ns(started.elapsed()));
        }
    }

    fn cancellation_checkpoint(&self, message: &'static str) -> Result<(), ExcelError> {
        if self
            .active_cancel_flag
            .as_ref()
            .is_some_and(|cancel| cancel.is_cancelled())
        {
            return Err(ExcelError::new(ExcelErrorKind::Cancelled).with_message(message));
        }
        if self
            .active_evaluation_deadline
            .is_some_and(|deadline| Instant::now() >= deadline)
        {
            return Err(crate::engine::ResourceLedgerError::Exhausted(
                formualizer_common::ResourceExhaustionDetail {
                    reason: formualizer_common::ResourceExhaustionReason::Deadline,
                    limit: 0,
                    observed: 1,
                    request_id: self
                        .active_evaluation_resource_request
                        .as_ref()
                        .map(|request| request.request_id),
                },
            )
            .into_excel_error()
            .with_message(message));
        }
        Ok(())
    }

    fn resource_checkpoint(&mut self, work_units: u64) -> Result<(), ExcelError> {
        let Some(ledger) = self.active_resource_ledger.as_mut() else {
            return Ok(());
        };
        ledger
            .charge_work(work_units)
            .and_then(|()| ledger.checkpoint_deadline())
            .map_err(crate::engine::ResourceLedgerError::into_excel_error)
    }

    fn charge_bounded_work(&mut self, mut work_units: u64) -> Result<(), ExcelError> {
        if work_units == 0 {
            return self.resource_checkpoint(0);
        }
        while work_units > 0 {
            let chunk = work_units.min(256);
            self.resource_checkpoint(chunk)?;
            work_units -= chunk;
        }
        Ok(())
    }

    fn reserve_request_scratch(&mut self, bytes: u64) -> Result<(), ExcelError> {
        if let Some(ledger) = self.active_resource_ledger.as_mut() {
            // Exact request topology and activation of the scratch cap are C1b. C1a records
            // scoped ownership but must not introduce a new skip or terminal path.
            ledger.observe_scratch(bytes);
        }
        Ok(())
    }

    fn release_request_scratch(&mut self, bytes: u64) {
        if let Some(ledger) = self.active_resource_ledger.as_mut() {
            let released = ledger.release_scratch(bytes);
            debug_assert!(
                released.is_ok(),
                "request scratch release exceeded the outstanding reservation"
            );
        }
    }

    fn can_reserve_topology_scratch(&self, bytes: u64) -> bool {
        self.active_resource_ledger
            .as_ref()
            .is_none_or(|ledger| ledger.can_reserve_schedule_discovery(bytes))
    }

    fn reserve_topology_scratch(&mut self, bytes: u64) -> Result<(), ExcelError> {
        self.active_resource_ledger
            .as_mut()
            .map_or(Ok(()), |ledger| ledger.reserve_schedule_discovery(bytes))
            .map_err(crate::engine::ResourceLedgerError::into_excel_error)
    }

    fn reserve_graph_source_scratch(&mut self, bytes: u64) -> Result<(), ExcelError> {
        self.active_resource_ledger
            .as_mut()
            .map_or(Ok(()), |ledger| ledger.reserve_graph_source(bytes))
            .map_err(crate::engine::ResourceLedgerError::into_excel_error)
    }

    fn with_request_scratch<T>(
        &mut self,
        bytes: u64,
        work: impl FnOnce(&mut Self) -> Result<T, ExcelError>,
    ) -> Result<T, ExcelError> {
        self.reserve_request_scratch(bytes)?;
        let result = work(self);
        self.release_request_scratch(bytes);
        result
    }

    fn observe_staged_preparation(
        &mut self,
        selected: usize,
        retained: usize,
        elapsed: std::time::Duration,
    ) {
        if let Some(stats) = self.active_evaluation_resource_request.as_mut() {
            stats.staged_selected = stats.staged_selected.saturating_add(selected as u64);
            stats.staged_retained = retained as u64;
            stats.phases.staged_prepare_ns = stats
                .phases
                .staged_prepare_ns
                .saturating_add(Self::duration_ns(elapsed));
        }
    }

    fn graph_admission_enabled(&self) -> bool {
        crate::engine::resource_ledger::graph_admission_enabled(&self.evaluation_resource_budgets)
    }

    fn preflight_graph_admission(
        &mut self,
        usage: crate::engine::resource_ledger::GraphAdmission,
    ) -> Result<(), ExcelError> {
        let request_id = self
            .active_evaluation_resource_request
            .as_ref()
            .map(|stats| stats.request_id);
        crate::engine::resource_ledger::preflight_graph_admission(
            &self.evaluation_resource_budgets,
            usage,
            request_id,
        )
        .map_err(crate::engine::ResourceLedgerError::into_excel_error)
    }

    fn prepared_legacy_admission(
        &mut self,
        plan: &PreparedLegacyGraphPlan,
        materialization_cells: u64,
    ) -> Result<(), ExcelError> {
        if !self.graph_admission_enabled() {
            return Ok(());
        }
        let stats = self.graph.baseline_stats();
        let added_edges = plan.planned_edge_count().ok_or_else(|| {
            ExcelError::new(ExcelErrorKind::NImpl).with_message("graph edge count overflow")
        })?;
        let removed_edges = plan.removed_edge_count().ok_or_else(|| {
            ExcelError::new(ExcelErrorKind::NImpl).with_message("graph edge count overflow")
        })?;
        self.preflight_graph_admission(crate::engine::resource_ledger::GraphAdmission {
            final_vertices: stats
                .graph_vertex_count
                .checked_add(plan.new_vertex_count())
                .ok_or_else(|| {
                    ExcelError::new(ExcelErrorKind::NImpl)
                        .with_message("graph vertex count overflow")
                })?,
            final_edges: stats
                .graph_edge_count
                .checked_sub(removed_edges)
                .and_then(|count| count.checked_add(added_edges))
                .ok_or_else(|| {
                    ExcelError::new(ExcelErrorKind::NImpl).with_message("graph edge count overflow")
                })?,
            materialization_cells,
            added_vertices: plan.new_vertex_count(),
            added_edges,
        })
    }

    fn observe_target_admission_failure(
        &mut self,
        reason: formualizer_common::ResourceExhaustionReason,
    ) {
        if let Some(stats) = self.active_evaluation_resource_request.as_mut() {
            stats.target_admission_failure = Some(reason);
        }
    }

    fn observe_target_preparation_report(
        &mut self,
        report: &crate::engine::PreparedTargetGraphReport,
    ) {
        let reason_bit = |reason: crate::engine::OpaqueReason| -> u64 {
            let index = match reason {
                crate::engine::OpaqueReason::DynamicReference => 0,
                crate::engine::OpaqueReason::RuntimeTextReference => 1,
                crate::engine::OpaqueReason::UnknownFunction => 2,
                crate::engine::OpaqueReason::UnknownCustomFunction => 3,
                crate::engine::OpaqueReason::UnresolvedCrossSheetBinding => 4,
                crate::engine::OpaqueReason::UnresolvedName => 5,
                crate::engine::OpaqueReason::UnresolvedTable => 6,
                crate::engine::OpaqueReason::FormulaName => 7,
                crate::engine::OpaqueReason::DeferredSourcePackage => 8,
                crate::engine::OpaqueReason::UnsupportedSourceSemantics => 9,
                crate::engine::OpaqueReason::UncertainDefaultSheetBinding => 10,
            };
            1u64 << index
        };
        if let Some(stats) = self.active_evaluation_resource_request.as_mut() {
            stats.staged_selected = report.selected_staged_cells as u64;
            stats.staged_retained = report.retained_staged_cells as u64;
            stats.target_requested = report.requested_targets as u64;
            stats.target_normalized_regions = report.normalized_regions as u64;
            stats.target_scope_level = match &report.widened_scope {
                crate::engine::PrepareScope::Exact => 0,
                crate::engine::PrepareScope::Sheets(_) => 1,
                crate::engine::PrepareScope::Workbook => 2,
            };
            stats.target_widening_reason_bits = report
                .widening_reasons
                .iter()
                .copied()
                .fold(0, |bits, reason| bits | reason_bit(reason));
            stats.graph_source_scratch_estimated = report.estimated_scratch_bytes;
            stats.graph_source_scratch_observed = report.observed_scratch_bytes;
            stats.target_commit_estimated_work = report.estimated_commit_work;
            stats.target_commit_actual_work = report.actual_commit_work;
            stats.target_commit_window_ns = Self::duration_ns(report.commit_window);
            stats.phases.staged_prepare_ns = stats
                .phases
                .staged_prepare_ns
                .saturating_add(Self::duration_ns(report.commit_window));
        }
    }

    fn observe_topology(
        &mut self,
        outcome: FormulaPlaneTopologyCacheOutcome,
        strategy: FormulaPlaneTopologyStrategy,
        observed: &MixedTopologyCompileStats,
        elapsed: std::time::Duration,
    ) {
        if let Some(stats) = self.active_evaluation_resource_request.as_mut() {
            if outcome.severity() > stats.topology.cache_outcome.severity() {
                stats.topology.cache_outcome = outcome;
            }
            if strategy.severity() > stats.topology.strategy.severity() {
                stats.topology.strategy = strategy;
            }
            match outcome {
                FormulaPlaneTopologyCacheOutcome::Hit => {
                    stats.topology.cache_hit_events =
                        stats.topology.cache_hit_events.saturating_add(1);
                }
                FormulaPlaneTopologyCacheOutcome::Built => {
                    stats.topology.cache_build_events =
                        stats.topology.cache_build_events.saturating_add(1);
                }
                FormulaPlaneTopologyCacheOutcome::SkippedOverflow
                | FormulaPlaneTopologyCacheOutcome::SkippedDynamicLegacy => {
                    stats.topology.cache_build_events =
                        stats.topology.cache_build_events.saturating_add(1);
                    stats.topology.cache_skip_events =
                        stats.topology.cache_skip_events.saturating_add(1);
                }
                FormulaPlaneTopologyCacheOutcome::NotUsed => {}
            }
            if matches!(
                outcome,
                FormulaPlaneTopologyCacheOutcome::Built
                    | FormulaPlaneTopologyCacheOutcome::SkippedOverflow
                    | FormulaPlaneTopologyCacheOutcome::SkippedDynamicLegacy
            ) {
                stats.topology.producers_observed = stats
                    .topology
                    .producers_observed
                    .saturating_add(observed.producers as u64);
                stats.topology.candidates_observed = stats
                    .topology
                    .candidates_observed
                    .saturating_add(observed.candidates as u64);
                stats.topology.edges_observed = stats
                    .topology
                    .edges_observed
                    .saturating_add(observed.relationships as u64);
                stats.topology.candidate_cap_hits = stats
                    .topology
                    .candidate_cap_hits
                    .saturating_add(observed.candidate_overflow_count as u64);
                stats.topology.edge_cap_hits = stats
                    .topology
                    .edge_cap_hits
                    .saturating_add(observed.edge_overflow_count as u64);
                stats.topology.byte_cap_hits = stats
                    .topology
                    .byte_cap_hits
                    .saturating_add(observed.memory_overflow_count as u64);
                stats.topology.overflow_reason = if stats.topology.byte_cap_hits > 0 {
                    Some(EvaluationResourceReason::FormulaPlaneTopologyRetainedBytes)
                } else if stats.topology.edge_cap_hits > 0 {
                    Some(EvaluationResourceReason::FormulaPlaneTopologyEdges)
                } else if stats.topology.candidate_cap_hits > 0 {
                    Some(EvaluationResourceReason::FormulaPlaneTopologyCandidates)
                } else {
                    None
                };
                stats.topology.incomplete_reason = if stats.topology.byte_cap_hits > 0 {
                    Some(crate::engine::EvaluationIncompleteReason::FormulaPlaneTopologyRetainedBytes)
                } else if stats.topology.edge_cap_hits > 0 {
                    Some(crate::engine::EvaluationIncompleteReason::FormulaPlaneTopologyEdges)
                } else if stats.topology.candidate_cap_hits > 0 {
                    Some(crate::engine::EvaluationIncompleteReason::FormulaPlaneTopologyCandidates)
                } else {
                    None
                };
            }
            stats.topology.retained_bytes_observed = stats
                .topology
                .retained_bytes_observed
                .max(observed.estimated_memory_bytes as u64);
            stats.phases.topology_ns = stats
                .phases
                .topology_ns
                .saturating_add(Self::duration_ns(elapsed));
        }
    }

    fn observe_topology_strategy(&mut self, strategy: FormulaPlaneTopologyStrategy) {
        if let Some(stats) = self.active_evaluation_resource_request.as_mut()
            && strategy.severity() > stats.topology.strategy.severity()
        {
            stats.topology.strategy = strategy;
        }
    }

    fn observe_formula_plane_route(
        &mut self,
        plan: &LegacyIslandPlan,
        phase: FormulaPlaneRoutePhase,
        reason: FormulaPlaneRouteTransitionReason,
        demotion_generation: usize,
        replan_generation: usize,
    ) {
        if plan.is_empty() {
            return;
        }
        let mut sheet_ids = [0_u16;
            crate::engine::resource_observability::FORMULA_PLANE_ROUTE_EVENT_SHEET_CAPACITY];
        let sheet_count = plan.sheet_ids.len().min(sheet_ids.len());
        sheet_ids[..sheet_count].copy_from_slice(&plan.sheet_ids[..sheet_count]);
        let authority = self.graph.formula_authority();
        let event = FormulaPlaneRouteEvent {
            island_id: plan.island_id,
            phase,
            route: FormulaPlaneRoute::ContractedLegacyIsland,
            sheet_ids,
            sheet_count: sheet_count as u8,
            authority_epoch: authority.plane.epoch().0,
            index_epoch: authority.indexes_epoch(),
            transition_reason: reason,
            demotion_generation: demotion_generation.min(u32::MAX as usize) as u32,
            replan_generation: replan_generation.min(u32::MAX as usize) as u32,
        };
        if let Some(stats) = self.active_evaluation_resource_request.as_mut() {
            let index = usize::from(stats.topology.route_event_count);
            if index < stats.topology.route_events.len() {
                stats.topology.route_events[index] = event;
                stats.topology.route_event_count =
                    stats.topology.route_event_count.saturating_add(1);
            } else {
                stats.topology.route_events_dropped =
                    stats.topology.route_events_dropped.saturating_add(1);
            }
            stats.topology.route_event_bytes_observed = stats
                .topology
                .route_event_bytes_observed
                .saturating_add(std::mem::size_of::<FormulaPlaneRouteEvent>() as u64);
            stats.topology.island_membership_vertices = plan.membership.len() as u64;
            stats.topology.island_membership_retained_bytes = plan.retained_bytes as u64;
            stats.topology.legacy_relationships_omitted = plan.omitted_relationships as u64;
            stats.topology.boundary_relationships_retained = plan.boundary_relationships as u64;
        }
    }

    fn observe_materialization(
        &mut self,
        placements: usize,
        cycle: bool,
        elapsed: std::time::Duration,
    ) {
        if let Some(stats) = self.active_evaluation_resource_request.as_mut() {
            if cycle {
                stats.cycle_materialized_cells = stats
                    .cycle_materialized_cells
                    .saturating_add(placements as u64);
            } else {
                stats.fallback_materialized_cells = stats
                    .fallback_materialized_cells
                    .saturating_add(placements as u64);
                stats.topology.strategy =
                    FormulaPlaneTopologyStrategy::CapacityFallbackMaterialization;
            }
            stats.phases.materialization_ns = stats
                .phases
                .materialization_ns
                .saturating_add(Self::duration_ns(elapsed));
        }
    }

    fn observe_dirty_lease_acquired(&mut self, empty: bool) {
        if let Some(stats) = self.active_evaluation_resource_request.as_mut() {
            stats.dirty_lease = if empty {
                FormulaDirtyLeaseOutcome::Empty
            } else {
                FormulaDirtyLeaseOutcome::Acquired
            };
        }
    }

    fn ack_formula_dirty_observed(&mut self, lease: FormulaDirtyLease) {
        let empty = lease.is_empty();
        let _ = self.graph.ack_formula_dirty(lease);
        if let Some(stats) = self.active_evaluation_resource_request.as_mut() {
            stats.dirty_lease = if empty {
                FormulaDirtyLeaseOutcome::AcknowledgedEmpty
            } else {
                FormulaDirtyLeaseOutcome::Acknowledged
            };
        }
    }

    fn checked_ack_formula_dirty_observed(
        &mut self,
        lease: FormulaDirtyLease,
    ) -> Result<(), ExcelError> {
        self.resource_checkpoint(0)?;
        self.ack_formula_dirty_observed(lease);
        Ok(())
    }

    fn checked_ack_formula_dirty_sublease_observed(
        &mut self,
        lease: FormulaDirtyLease,
        owned_events: &[usize],
    ) -> Result<(), ExcelError> {
        self.resource_checkpoint(owned_events.len() as u64)?;
        let empty = lease.is_empty();
        let partial = owned_events.len() < lease.len();
        let sublease = lease.sublease(owned_events.iter().copied());
        if !self.graph.ack_formula_dirty_sublease(sublease) {
            return Err(ExcelError::new(ExcelErrorKind::NImpl)
                .with_message("FormulaPlane dirty sublease became stale"));
        }
        if let Some(stats) = self.active_evaluation_resource_request.as_mut() {
            stats.dirty_lease = if empty {
                FormulaDirtyLeaseOutcome::AcknowledgedEmpty
            } else if partial {
                FormulaDirtyLeaseOutcome::AcknowledgedPartial
            } else {
                FormulaDirtyLeaseOutcome::Acknowledged
            };
        }
        Ok(())
    }

    /// Begin a new evaluation request: reset per-recalc cycle telemetry and
    /// take the per-recalc volatile clock sample. Called at the start of
    /// every evaluation request that walks schedule units.
    fn begin_evaluation_request(&mut self) {
        #[cfg(test)]
        {
            self.evaluation_request_begin_count_for_test = self
                .evaluation_request_begin_count_for_test
                .saturating_add(1);
        }
        self.last_cycle_telemetry = CycleTelemetry::default();
        // Defensive: consumed at the end of the previous request; a request
        // that errored out mid-walk must not leak its members into this one.
        self.pending_iterative_redirty.clear();
        // Spec §7.11: NOW()/TODAY() sample the clock ONCE per recalc; every
        // read within this request (including SCC iteration passes) observes
        // this sample.
        self.clock.refresh();
    }

    /// End-of-recalc redirty: volatile vertices (as always) plus members of
    /// SCCs that iterated this recalc (`CyclePolicy::Iterate`), so circular
    /// cells re-evaluate on every recalc exactly like Excel's iterative
    /// calculation (spec §4 persistence / §7.6 accumulator / §7.11 volatile
    /// redirty). Replaces the bare `graph.redirty_volatiles()` call at every
    /// evaluation-flow exit; must run AFTER the flow's `clear_dirty_flags`.
    fn redirty_for_next_recalc(&mut self) {
        self.graph.redirty_volatiles();
        let pending = std::mem::take(&mut self.pending_iterative_redirty);
        // Refresh the §4-persistence snapshot: these final values survive
        // structural edits that clear the computed overlay (the only value
        // home in canonical mode) so the next SCC task can re-seed from them
        // (see `iterative_state_values`). Replaced wholesale each recalc —
        // when nothing iterates the map empties and stays free.
        self.iterative_state_values.clear();
        for &vertex in &pending {
            if !self.graph.vertex_exists(vertex) {
                continue;
            }
            if let Some(cell) = self.graph.get_cell_ref(vertex) {
                let sheet_name = self.graph.sheet_name(cell.sheet_id);
                if let Some(value) =
                    self.get_cell_value(sheet_name, cell.coord.row() + 1, cell.coord.col() + 1)
                    && !matches!(value, LiteralValue::Empty)
                {
                    self.iterative_state_values.insert(vertex, value);
                }
            }
        }
        if !pending.is_empty() {
            self.graph.redirty_iterative_members(&pending);
        }
    }

    pub fn virtual_dep_fallback_activations(&self) -> u64 {
        self.virtual_dep_fallback_activations
    }

    pub(crate) fn last_lookup_index_cache_report(&self) -> LookupIndexCacheReport {
        self.lookup_index_cache.report()
    }

    fn lookup_view_contains_volatile(&self, view: &RangeView<'_>, sheet_id: SheetId) -> bool {
        let start_row = view.start_row();
        let end_row = view.end_row();
        let start_col = view.start_col();
        let end_col = view.end_col();
        for row in start_row..=end_row {
            let Ok(row_u32) = u32::try_from(row) else {
                return true;
            };
            for col in start_col..=end_col {
                let Ok(col_u32) = u32::try_from(col) else {
                    return true;
                };
                let cell_ref = self
                    .graph
                    .make_cell_ref_internal(sheet_id, row_u32, col_u32);
                if let Some(vertex_id) = self.graph.get_vertex_id_for_address(&cell_ref)
                    && self.graph.is_volatile(*vertex_id)
                {
                    return true;
                }
            }
        }
        false
    }

    fn build_lookup_index_impl(
        &self,
        view: &RangeView<'_>,
        axis: LookupAxis,
    ) -> Option<Arc<LookupIndex>> {
        let (rows, cols) = view.dims();
        if rows == 0 || cols == 0 {
            self.lookup_index_cache.note_skipped_tiny();
            return None;
        }
        let len = match axis {
            LookupAxis::ColumnInView(col) => {
                if col >= cols {
                    self.lookup_index_cache.note_skipped_tiny();
                    return None;
                }
                rows
            }
            LookupAxis::RowInView(row) => {
                if row >= rows {
                    self.lookup_index_cache.note_skipped_tiny();
                    return None;
                }
                cols
            }
        };
        if len < 64 {
            self.lookup_index_cache.note_skipped_tiny();
            return None;
        }

        let sheet_id = self.graph.sheet_id(view.sheet_name())?;
        let key = LookupIndexKey {
            sheet_id,
            start_row: u32::try_from(view.start_row()).ok()?,
            start_col: u32::try_from(view.start_col()).ok()?,
            end_row: u32::try_from(view.end_row()).ok()?,
            end_col: u32::try_from(view.end_col()).ok()?,
            axis,
            snapshot_id: self.data_snapshot_id(),
        };
        if let Some(index) = self.lookup_index_cache.get(&key) {
            return Some(index);
        }
        if self
            .lookup_index_cache
            .would_exceed_cap(estimate_bytes(len, 0))
        {
            self.lookup_index_cache.note_skipped_cap();
            return None;
        }
        if !self.lookup_index_cache.should_build(key) {
            return None;
        }
        if self.lookup_index_cache.is_known_volatile(&key) {
            self.lookup_index_cache.note_skipped_volatile();
            return None;
        }
        if self.lookup_view_contains_volatile(view, sheet_id) {
            self.lookup_index_cache.note_volatile_key(key);
            self.lookup_index_cache.note_skipped_volatile();
            return None;
        }
        match LookupIndex::build(view, axis, self.config.date_system).ok()? {
            BuildOutcome::Built(index) => self.lookup_index_cache.insert_if_room(key, index),
            BuildOutcome::ErrorInLookupAxis => {
                self.lookup_index_cache.note_skipped_error();
                None
            }
            BuildOutcome::Degenerate => {
                self.lookup_index_cache.note_skipped_tiny();
                None
            }
        }
    }

    fn reset_virtual_dep_telemetry_if_disabled(&mut self) {
        if !self.config.enable_virtual_dep_telemetry {
            self.last_virtual_dep_telemetry = VirtualDepTelemetry {
                fallback_mode_activations: self.virtual_dep_fallback_activations,
                ..VirtualDepTelemetry::default()
            };
        }
    }

    fn source_cache_session(&self) -> SourceCacheSession {
        self.clear_source_cache();
        SourceCacheSession {
            cache: self.source_cache.clone(),
        }
    }

    fn resolve_source_scalar_cached(
        &self,
        name: &str,
        version: Option<u64>,
    ) -> Result<LiteralValue, ExcelError> {
        let key = (name.to_string(), version);
        if let Ok(mut g) = self.source_cache.write() {
            if let Some(v) = g.scalars.get(&key) {
                return Ok(v.clone());
            }

            let v = self.resolver.resolve_source_scalar(name).map_err(|err| {
                if matches!(err.kind, ExcelErrorKind::Name | ExcelErrorKind::NImpl) {
                    ExcelError::new(ExcelErrorKind::Ref)
                        .with_message(format!("Unresolved source scalar: {name}"))
                } else {
                    err
                }
            })?;
            g.scalars.insert(key, v.clone());
            Ok(v)
        } else {
            self.resolver.resolve_source_scalar(name).map_err(|err| {
                if matches!(err.kind, ExcelErrorKind::Name | ExcelErrorKind::NImpl) {
                    ExcelError::new(ExcelErrorKind::Ref)
                        .with_message(format!("Unresolved source scalar: {name}"))
                } else {
                    err
                }
            })
        }
    }

    fn resolve_source_table_cached(
        &self,
        name: &str,
        version: Option<u64>,
    ) -> Result<Arc<dyn crate::traits::Table>, ExcelError> {
        let key = (name.to_string(), version);
        if let Ok(mut g) = self.source_cache.write() {
            if let Some(t) = g.tables.get(&key) {
                return Ok(t.clone());
            }

            let t = self.resolver.resolve_source_table(name).map_err(|err| {
                if matches!(err.kind, ExcelErrorKind::Name | ExcelErrorKind::NImpl) {
                    ExcelError::new(ExcelErrorKind::Ref)
                        .with_message(format!("Unresolved source table: {name}"))
                } else {
                    err
                }
            })?;
            let t: Arc<dyn crate::traits::Table> = Arc::from(t);
            g.tables.insert(key, t.clone());
            Ok(t)
        } else {
            self.resolver
                .resolve_source_table(name)
                .map_err(|err| {
                    if matches!(err.kind, ExcelErrorKind::Name | ExcelErrorKind::NImpl) {
                        ExcelError::new(ExcelErrorKind::Ref)
                            .with_message(format!("Unresolved source table: {name}"))
                    } else {
                        err
                    }
                })
                .map(Arc::from)
        }
    }

    fn source_table_to_range_view(
        &self,
        table: &dyn crate::traits::Table,
        spec: &Option<formualizer_parse::parser::TableSpecifier>,
    ) -> Result<RangeView<'static>, ExcelError> {
        use formualizer_parse::parser::{SpecialItem, TableSpecifier};

        let owned = match spec {
            Some(TableSpecifier::Column(c)) => {
                let c = c.trim();
                if c == "@" || c.contains('[') || c.contains(']') || c.contains(',') {
                    return Err(ExcelError::new(ExcelErrorKind::NImpl).with_message(
                        "Complex structured references not yet supported".to_string(),
                    ));
                }
                table.get_column(c)?.materialise().into_owned()
            }
            Some(TableSpecifier::ColumnRange(start, end)) => {
                let cols = table.columns();
                let start = start.trim();
                let end = end.trim();
                let start_key = start.to_lowercase();
                let end_key = end.to_lowercase();
                let start_idx = cols.iter().position(|n| n.to_lowercase() == start_key);
                let end_idx = cols.iter().position(|n| n.to_lowercase() == end_key);
                if let (Some(mut si), Some(mut ei)) = (start_idx, end_idx) {
                    if si > ei {
                        std::mem::swap(&mut si, &mut ei);
                    }
                    let h = table.data_height();
                    let w = ei - si + 1;
                    let mut rows = vec![vec![LiteralValue::Empty; w]; h];
                    for (offset, ci) in (si..=ei).enumerate() {
                        let cname = &cols[ci];
                        let col_range = table.get_column(cname)?;
                        let (rh, _) = col_range.dimensions();
                        for (r, row) in rows.iter_mut().enumerate().take(h.min(rh)) {
                            row[offset] = col_range.get(r, 0)?;
                        }
                    }
                    rows
                } else {
                    return Err(ExcelError::new(ExcelErrorKind::Ref)
                        .with_message("Column range refers to unknown column(s)".to_string()));
                }
            }
            Some(TableSpecifier::SpecialItem(SpecialItem::Headers))
            | Some(TableSpecifier::Headers) => table
                .headers_row()
                .map(|r| r.materialise().into_owned())
                .unwrap_or_default(),
            Some(TableSpecifier::SpecialItem(SpecialItem::Totals))
            | Some(TableSpecifier::Totals) => table
                .totals_row()
                .map(|r| r.materialise().into_owned())
                .unwrap_or_default(),
            Some(TableSpecifier::SpecialItem(SpecialItem::Data)) | Some(TableSpecifier::Data) => {
                table
                    .data_body()
                    .map(|r| r.materialise().into_owned())
                    .unwrap_or_default()
            }
            Some(TableSpecifier::SpecialItem(SpecialItem::All)) | Some(TableSpecifier::All) => {
                let mut out: Vec<Vec<LiteralValue>> = Vec::new();
                if let Some(h) = table.headers_row() {
                    out.extend(h.iter_rows());
                }
                if let Some(body) = table.data_body() {
                    out.extend(body.iter_rows());
                }
                if let Some(tr) = table.totals_row() {
                    out.extend(tr.iter_rows());
                }
                out
            }
            Some(TableSpecifier::SpecialItem(SpecialItem::ThisRow)) => {
                return Err(ExcelError::new(ExcelErrorKind::NImpl).with_message(
                    "@ (This Row) requires table-aware context; not yet supported".to_string(),
                ));
            }
            Some(TableSpecifier::Row(_)) | Some(TableSpecifier::Combination(_)) => {
                return Err(ExcelError::new(ExcelErrorKind::NImpl)
                    .with_message("Complex structured references not yet supported".to_string()));
            }
            None => {
                return Err(ExcelError::new(ExcelErrorKind::NImpl)
                    .with_message("Table reference without specifier is unsupported".to_string()));
            }
        };

        Ok(RangeView::from_owned_rows(owned, self.config.date_system))
    }

    pub fn default_sheet_id(&self) -> SheetId {
        self.graph.default_sheet_id()
    }

    pub fn default_sheet_name(&self) -> &str {
        self.graph.default_sheet_name()
    }

    /// Update the workbook seed for deterministic RNGs in functions.
    pub fn set_workbook_seed(&mut self, seed: u64) {
        self.config.workbook_seed = seed;
    }

    /// Set the volatile level policy (Always/OnRecalc/OnOpen)
    pub fn set_volatile_level(&mut self, level: crate::traits::VolatileLevel) {
        self.config.volatile_level = level;
    }

    /// Enable/disable deterministic evaluation mode (fixed clock + timezone).
    pub fn set_deterministic_mode(
        &mut self,
        mode: crate::engine::DeterministicMode,
    ) -> Result<(), ExcelError> {
        let clock = mode.build_clock()?;
        self.config.deterministic_mode = mode;
        self.clock = crate::timezone::SnapshotClock::new(clock);
        Ok(())
    }

    /// Inject a custom [`ClockProvider`](crate::timezone::ClockProvider) for
    /// volatile date/time builtins (`NOW()`, `TODAY()`).
    ///
    /// The provider is the clock *source*; per spec §7.11 the engine samples
    /// it once at the start of every evaluation request and all reads within
    /// that recalc (including SCC iteration passes) observe the frozen
    /// sample.
    pub fn set_clock(&mut self, clock: Arc<dyn crate::timezone::ClockProvider>) {
        self.clock = crate::timezone::SnapshotClock::new(clock);
    }

    fn validate_deterministic_mode(&self) -> Result<(), ExcelError> {
        self.config.deterministic_mode.validate()
    }

    pub fn sheet_id(&self, name: &str) -> Option<SheetId> {
        self.graph.sheet_id(name)
    }

    pub fn sheet_id_mut(&mut self, name: &str) -> SheetId {
        self.add_sheet(name)
            .unwrap_or_else(|_| self.graph.sheet_id_mut(name))
    }

    pub fn sheet_name(&self, id: SheetId) -> &str {
        self.graph.sheet_name(id)
    }

    pub fn add_sheet(&mut self, name: &str) -> Result<SheetId, ExcelError> {
        let id = self.graph.add_sheet(name)?;
        self.ensure_arrow_sheet(name);
        // Adding a sheet does not change any existing span result or dependency.
        self.mark_topology_edited();
        Ok(id)
    }

    pub fn duplicate_sheet(&mut self, source: &str, new_name: &str) -> Result<SheetId, ExcelError> {
        let source_id = self.graph.sheet_id(source).ok_or_else(|| {
            ExcelError::new(ExcelErrorKind::Value).with_message("Source sheet does not exist")
        })?;
        if new_name.is_empty() || new_name.len() > 255 {
            return Err(ExcelError::new(ExcelErrorKind::Value).with_message("Invalid sheet name"));
        }
        if self.graph.sheet_id(new_name).is_some() {
            return Err(ExcelError::new(ExcelErrorKind::Value)
                .with_message(format!("Sheet '{new_name}' already exists")));
        }
        // Materialize only spans on the source sheet so graph duplication sees
        // the formulas being copied. Spans on unrelated sheets remain active.
        self.demote_spans_preserving_computed_overlays(source_id, Region::whole_sheet(source_id))
            .map_err(Self::editor_error_to_excel)?;
        let new_id = self.graph.duplicate_sheet(source_id, new_name)?;

        if let Some(source_sheet) = self.arrow_sheets.sheet(source).cloned() {
            let mut copied_sheet = source_sheet;
            copied_sheet.name = Arc::<str>::from(new_name);
            self.arrow_sheets.sheets.push(copied_sheet);
        } else {
            self.ensure_arrow_sheet(new_name);
        }

        let duplicated_formulas = self
            .graph
            .formula_vertices()
            .into_iter()
            .filter(|vertex| {
                self.graph
                    .get_cell_ref(*vertex)
                    .is_some_and(|cell| cell.sheet_id == new_id)
            })
            .collect::<Vec<_>>();
        self.graph.mark_vertices_dirty_batch(&duplicated_formulas);
        self.mark_topology_edited();
        Ok(new_id)
    }

    fn ensure_arrow_sheet(&mut self, name: &str) {
        if self.arrow_sheets.sheet(name).is_some() {
            return;
        }
        self.arrow_sheets
            .sheets
            .push(crate::arrow_store::ArrowSheet {
                name: std::sync::Arc::<str>::from(name),
                date_system: self.config.date_system,
                columns: Vec::new(),
                nrows: 0,
                chunk_starts: Vec::new(),
                chunk_rows: 32 * 1024,
            });
    }

    pub fn remove_sheet(&mut self, sheet_id: SheetId) -> Result<(), ExcelError> {
        let name = self.graph.sheet_name(sheet_id).to_string();
        // Removing a sheet only affects spans on that sheet and spans reading
        // from that sheet. Preserve spans on unrelated sheets so sheet
        // lifecycle operations do not collapse the whole FormulaPlane.
        self.demote_spans_preserving_computed_overlays(sheet_id, Region::whole_sheet(sheet_id))
            .map_err(Self::editor_error_to_excel)?;
        self.graph.remove_sheet(sheet_id)?;
        self.arrow_sheets.sheets.retain(|s| s.name.as_ref() != name);
        // Sheet removal can change cross-sheet refs, names, and default-sheet
        // resolution. Until those domains have a complete exact dependency
        // proof, retain the documented graph-owned global invalidation.
        self.clear_all_computed_overlays();
        self.mark_all_formula_vertices_dirty();
        self.clear_staged_formulas_for_sheet(&name);
        if self.row_visibility.remove(&sheet_id).is_some() {
            self.invalidate_row_visibility_mask_cache();
        }
        self.record_formula_plane_structural_change(StructuralScope::RemovedSheet(sheet_id));
        self.mark_topology_edited();
        Ok(())
    }

    /// Helper to synchronize the Arrow-backed storage layer.
    fn rename_sheet_in_arrow_store(&mut self, target_name: &str, new_name: &str) -> bool {
        if let Some(asheet) = self
            .arrow_sheets
            .sheets
            .iter_mut()
            .find(|s| s.name.as_ref() == target_name)
        {
            asheet.name = std::sync::Arc::<str>::from(new_name);
            return true;
        }
        false
    }

    pub fn rename_sheet(&mut self, sheet_id: SheetId, new_name: &str) -> Result<(), ExcelError> {
        let old_name = self.graph.sheet_name(sheet_id).to_string();

        // Speculative Storage Update
        // Update name in storage FIRST so the Evaluator can find it during Graph rescue.
        self.rename_sheet_in_arrow_store(&old_name, new_name);

        // Graph Update (Metadata + Rescue Logic)
        match self.graph.rename_sheet(sheet_id, new_name) {
            Ok(_) => {
                self.rename_staged_formula_sheet(&old_name, new_name);
                // Success! Invalidate cache for the moved sheet
                let sheet_vertices: Vec<VertexId> =
                    self.graph.vertices_in_sheet(sheet_id).collect();
                for v_id in sheet_vertices {
                    self.graph.mark_vertex_dirty(v_id);
                }
                // Sheet rename preserves SheetId and therefore formula dependencies.
                self.mark_topology_edited();
                Ok(())
            }
            Err(e) => {
                // ROLLBACK: Revert storage if graph rejected the name
                self.rename_sheet_in_arrow_store(new_name, &old_name);
                Err(e)
            }
        }
    }

    pub fn named_ranges_iter(
        &self,
    ) -> impl Iterator<Item = (&String, &crate::engine::named_range::NamedRange)> {
        self.graph.named_ranges_iter()
    }

    pub fn sheet_named_ranges_iter(
        &self,
    ) -> impl Iterator<Item = (&(SheetId, String), &crate::engine::named_range::NamedRange)> {
        self.graph.sheet_named_ranges_iter()
    }

    pub fn resolve_name_entry(
        &self,
        name: &str,
        current_sheet: SheetId,
    ) -> Option<&crate::engine::named_range::NamedRange> {
        self.graph.resolve_name_entry(name, current_sheet)
    }

    pub fn has_name(&self, name: &str, scope_sheet: Option<&str>) -> bool {
        let current_sheet = scope_sheet
            .and_then(|sheet| self.graph.sheet_id(sheet))
            .unwrap_or_else(|| self.graph.default_sheet_id());
        self.graph.resolve_name_entry(name, current_sheet).is_some()
    }

    pub fn resolved_name_value(
        &self,
        name: &str,
        scope_sheet: Option<&str>,
    ) -> Option<LiteralValue> {
        let current_sheet = scope_sheet
            .and_then(|sheet| self.graph.sheet_id(sheet))
            .unwrap_or_else(|| self.graph.default_sheet_id());
        let entry = self.graph.resolve_name_entry(name, current_sheet)?;
        self.graph.get_value(entry.vertex)
    }

    pub fn table_metadata(&self, name: &str) -> Option<TableMetadata> {
        let entry = self.graph.resolve_table_entry(name)?;
        Some(TableMetadata {
            name: entry.name.clone(),
            sheet: self.graph.sheet_name(entry.sheet_id()).to_string(),
            start_row: entry.range.start.coord.row() + 1,
            start_col: entry.range.start.coord.col() + 1,
            end_row: entry.range.end.coord.row() + 1,
            end_col: entry.range.end.coord.col() + 1,
            header_row: entry.header_row,
            headers: entry.headers.clone(),
            totals_row: entry.totals_row,
        })
    }

    /// Metadata for every defined table, ordered by name.
    pub fn tables(&self) -> Vec<TableMetadata> {
        self.graph
            .table_names()
            .into_iter()
            .filter_map(|name| self.table_metadata(&name))
            .collect()
    }

    pub fn named_ranges_snapshot(&self) -> Vec<crate::engine::named_range::NamedRangeSnapshot> {
        let mut out: Vec<crate::engine::named_range::NamedRangeSnapshot> = Vec::new();

        for (name, named) in self.graph.named_ranges_iter() {
            out.push(crate::engine::named_range::NamedRangeSnapshot {
                name: name.clone(),
                scope: NameScope::Workbook,
                definition: named.definition.clone(),
            });
        }

        for ((sheet_id, name), named) in self.graph.sheet_named_ranges_iter() {
            out.push(crate::engine::named_range::NamedRangeSnapshot {
                name: name.clone(),
                scope: NameScope::Sheet(*sheet_id),
                definition: named.definition.clone(),
            });
        }

        out.sort_by(|a, b| {
            let a_scope = match a.scope {
                NameScope::Workbook => (0u8, 0u32),
                NameScope::Sheet(id) => (1u8, u32::from(id)),
            };
            let b_scope = match b.scope {
                NameScope::Workbook => (0u8, 0u32),
                NameScope::Sheet(id) => (1u8, u32::from(id)),
            };
            a_scope.cmp(&b_scope).then_with(|| a.name.cmp(&b.name))
        });

        out
    }

    pub fn named_ranges_snapshot_for_sheet(
        &self,
        sheet_id: SheetId,
    ) -> Vec<crate::engine::named_range::NamedRangeSnapshot> {
        self.named_ranges_snapshot()
            .into_iter()
            .filter(|entry| match entry.scope {
                NameScope::Workbook => true,
                NameScope::Sheet(id) => id == sheet_id,
            })
            .collect()
    }

    pub fn define_name(
        &mut self,
        name: &str,
        definition: NamedDefinition,
        scope: NameScope,
    ) -> Result<(), ExcelError> {
        // A new define can flip resolution for spans that previously resolved
        // the same name through another scope (e.g. a sheet-scoped name
        // shadowing a workbook-scoped one). Demote those spans BEFORE the
        // registry changes so their cells re-ingest and re-resolve through
        // the normal legacy path.
        self.graph.validate_define_name(name, scope)?;
        let has_dependent_spans = !self.exact_name_dependent_span_refs([name]).is_empty();
        if has_dependent_spans && matches!(definition, NamedDefinition::Formula { .. }) {
            return Err(ExcelError::new(ExcelErrorKind::NImpl).with_message(
                "formula-name shadowing with active FormulaPlane dependents is not supported",
            ));
        }
        let prepared = self
            .prepare_name_dependent_span_demotion([name])
            .map_err(Self::editor_error_to_excel)?;
        let demoted = self
            .commit_name_dependent_span_demotion(prepared)
            .map_err(Self::editor_error_to_excel)?;
        self.graph.define_name(name, definition, scope)?;
        self.record_formula_plane_structural_change(StructuralScope::AllSheets);
        if !demoted {
            self.mark_topology_edited();
        }
        Ok(())
    }

    pub fn update_name(
        &mut self,
        name: &str,
        definition: NamedDefinition,
        scope: NameScope,
    ) -> Result<(), ExcelError> {
        // Demote name-dependent spans BEFORE the registry update: the demoted
        // cells re-materialize as legacy vertices attached to the name vertex
        // (via their resolved-name dep plans), so the registry update's
        // dependent dirtying reaches them exactly like long-lived legacy
        // formulas.
        self.graph.validate_existing_name(name, scope)?;
        let prepared = self
            .prepare_name_dependent_span_demotion([name])
            .map_err(Self::editor_error_to_excel)?;
        let demoted = self
            .commit_name_dependent_span_demotion(prepared)
            .map_err(Self::editor_error_to_excel)?;
        self.graph.update_name(name, definition, scope)?;
        self.record_formula_plane_structural_change(StructuralScope::AllSheets);
        if !demoted {
            self.mark_topology_edited();
        }
        Ok(())
    }

    pub fn delete_name(&mut self, name: &str, scope: NameScope) -> Result<(), ExcelError> {
        // Demote first (see update_name): the demoted legacy vertices become
        // dependents of the name vertex, so delete_name dirties them and they
        // re-evaluate to #NAME? exactly as legacy formulas do.
        self.graph.validate_existing_name(name, scope)?;
        let prepared = self
            .prepare_name_dependent_span_demotion([name])
            .map_err(Self::editor_error_to_excel)?;
        let demoted = self
            .commit_name_dependent_span_demotion(prepared)
            .map_err(Self::editor_error_to_excel)?;
        self.graph.delete_name(name, scope)?;
        self.record_formula_plane_structural_change(StructuralScope::AllSheets);
        if !demoted {
            self.mark_topology_edited();
        }
        Ok(())
    }

    fn exact_name_dependent_span_refs<'a>(
        &self,
        names: impl IntoIterator<Item = &'a str>,
    ) -> Vec<FormulaSpanRef> {
        let authority = self.graph.formula_authority();
        let mut refs = names
            .into_iter()
            .flat_map(|name| authority.plane.name_dependent_span_refs(name))
            .collect::<Vec<_>>();
        refs.sort_unstable_by_key(|span_ref| {
            (span_ref.id.0, span_ref.generation, span_ref.version)
        });
        refs.dedup();
        refs
    }

    fn name_event_names(events: &[ChangeEvent]) -> Vec<String> {
        events
            .iter()
            .filter_map(|event| match event {
                ChangeEvent::DefineName { name, .. }
                | ChangeEvent::UpdateName { name, .. }
                | ChangeEvent::DeleteName { name, .. }
                | ChangeEvent::NamedRangeAdjusted { name, .. } => Some(name.clone()),
                _ => None,
            })
            .collect()
    }

    fn prepare_name_dependent_span_demotion<'a>(
        &mut self,
        names: impl IntoIterator<Item = &'a str>,
    ) -> Result<Option<(PreparedFormulaSpanDemotion, Vec<CellRef>)>, crate::engine::EditorError>
    {
        if self.config.formula_plane_mode == FormulaPlaneMode::Off {
            return Ok(None);
        }
        let refs = self.exact_name_dependent_span_refs(names);
        if refs.is_empty() {
            return Ok(None);
        }

        // Exact demotion creates dirty legacy vertices. Preserve the old
        // span's clean/dirty state so the following name mutation remains the
        // sole authority that dirties formulas whose resolution changed.
        let dirty_coords = self.compute_current_formula_plane_dirty_result_coords()?;
        let clean_cells = {
            let authority = self.graph.formula_authority();
            refs.iter()
                .filter_map(|span_ref| authority.plane.spans.get(*span_ref))
                .flat_map(|span| span.domain.iter())
                .filter(|coord| !dirty_coords.contains(&(coord.sheet_id, coord.row, coord.col)))
                .map(|coord| {
                    CellRef::new(coord.sheet_id, Coord::new(coord.row, coord.col, true, true))
                })
                .collect::<Vec<_>>()
        };
        self.prepare_formula_span_demotion(&refs)
            .map(|prepared| Some((prepared, clean_cells)))
            .map_err(|error| match error {
                FormulaSpanDemotionError::Resource(error) => error.into(),
                error => crate::engine::EditorError::TransactionFailed {
                    reason: format!(
                        "FormulaPlane name-dependent demotion preparation failed: {error}"
                    ),
                },
            })
    }

    fn commit_name_dependent_span_demotion(
        &mut self,
        prepared: Option<(PreparedFormulaSpanDemotion, Vec<CellRef>)>,
    ) -> Result<bool, crate::engine::EditorError> {
        let Some((prepared, clean_cells)) = prepared else {
            return Ok(false);
        };
        self.commit_prepared_formula_span_demotion(prepared)
            .map_err(|error| crate::engine::EditorError::TransactionFailed {
                reason: format!("FormulaPlane name-dependent demotion commit failed: {error}"),
            })?;
        for cell in clean_cells {
            if let Some(&vertex_id) = self.graph.get_vertex_id_for_address(&cell) {
                self.graph.set_dirty(vertex_id, false);
            }
        }
        Ok(true)
    }

    pub fn define_table(
        &mut self,
        name: &str,
        range: crate::reference::RangeRef,
        header_row: bool,
        headers: Vec<String>,
        totals_row: bool,
    ) -> Result<(), ExcelError> {
        self.graph
            .define_table(name, range, header_row, headers, totals_row)?;
        self.record_formula_plane_structural_change(StructuralScope::AllSheets);
        self.mark_topology_edited();
        Ok(())
    }

    pub fn define_source_scalar(
        &mut self,
        name: &str,
        version: Option<u64>,
    ) -> Result<(), ExcelError> {
        self.graph.define_source_scalar(name, version)?;
        self.record_formula_plane_structural_change(StructuralScope::OpaqueGlobal);
        self.mark_topology_edited();
        Ok(())
    }

    pub fn define_source_table(
        &mut self,
        name: &str,
        version: Option<u64>,
    ) -> Result<(), ExcelError> {
        self.graph.define_source_table(name, version)?;
        self.record_formula_plane_structural_change(StructuralScope::OpaqueGlobal);
        self.mark_topology_edited();
        Ok(())
    }

    pub fn set_source_scalar_version(
        &mut self,
        name: &str,
        version: Option<u64>,
    ) -> Result<(), ExcelError> {
        self.graph.set_source_scalar_version(name, version)?;
        if self.config.formula_plane_mode != FormulaPlaneMode::Off {
            self.graph
                .mark_all_formula_spans_dirty(WholeSpanDirtyReason::GlobalInvalidation);
        }
        Ok(())
    }

    pub fn set_source_table_version(
        &mut self,
        name: &str,
        version: Option<u64>,
    ) -> Result<(), ExcelError> {
        self.graph.set_source_table_version(name, version)?;
        if self.config.formula_plane_mode != FormulaPlaneMode::Off {
            self.graph
                .mark_all_formula_spans_dirty(WholeSpanDirtyReason::GlobalInvalidation);
        }
        Ok(())
    }

    pub fn invalidate_source(&mut self, name: &str) -> Result<(), ExcelError> {
        self.graph.invalidate_source(name)?;
        if self.config.formula_plane_mode != FormulaPlaneMode::Off {
            self.graph
                .mark_all_formula_spans_dirty(WholeSpanDirtyReason::GlobalInvalidation);
        }
        Ok(())
    }

    pub fn vertex_value(&self, vertex: VertexId) -> Option<LiteralValue> {
        self.graph.get_value(vertex)
    }

    pub fn graph_cell_value(&self, sheet: &str, row: u32, col: u32) -> Option<LiteralValue> {
        self.graph.get_cell_value(sheet, row, col)
    }

    pub fn vertex_for_cell(&self, cell: &CellRef) -> Option<VertexId> {
        self.graph.get_vertex_for_cell(cell)
    }

    pub fn evaluation_vertices(&self) -> Vec<VertexId> {
        self.graph.get_evaluation_vertices()
    }

    /// Return read-only baseline counters for FormulaPlane/dispatch benchmarking.
    pub fn baseline_stats(&self) -> EngineBaselineStats {
        let graph = self.graph.baseline_stats();
        let formula_authority = self.graph.formula_authority();
        let formula_dirty = self.graph.formula_dirty_stats();
        EngineBaselineStats {
            graph_vertex_count: graph.graph_vertex_count,
            graph_formula_vertex_count: graph.graph_formula_vertex_count,
            graph_edge_count: graph.graph_edge_count,
            dirty_vertex_count: graph.dirty_vertex_count,
            evaluation_vertex_count: graph.evaluation_vertex_count,
            formula_ast_root_count: graph.formula_ast_root_count,
            formula_ast_node_count: graph.formula_ast_node_count,
            staged_formula_count: self.staged_formula_count(),
            formula_plane_active_span_count: formula_authority.active_span_count(),
            formula_plane_producer_result_entries: formula_authority.producer_results.len(),
            formula_plane_consumer_read_entries: formula_authority.consumer_reads.len(),
            formula_plane_mixed_topology_cache_builds: self.mixed_topology_cache_builds,
            formula_plane_mixed_topology_cache_hits: self.mixed_topology_cache_hits,
            formula_plane_mixed_topology_cache_overflows: self.mixed_topology_cache_overflows,
            formula_plane_dirty_pending_events: formula_dirty.pending_events,
            formula_plane_dirty_region_events_recorded: formula_dirty.region_events_recorded,
            formula_plane_dirty_span_region_events_recorded: formula_dirty
                .span_region_events_recorded,
            formula_plane_dirty_whole_span_seeds_recorded: formula_dirty.whole_span_seeds_recorded,
            formula_plane_dirty_global_invalidations: formula_dirty.global_whole_span_invalidations,
            formula_plane_structural_span_candidates: self.formula_plane_structural_span_candidates,
            formula_plane_cycle_member_span_demotions: self
                .formula_plane_cycle_member_span_demotions,
        }
    }

    /// Mutation revision captured by read-only engine reports.
    pub(crate) fn inspection_mutation_revision(&self) -> u64 {
        self.snapshot_id.load(std::sync::atomic::Ordering::Relaxed)
    }

    #[cfg(test)]
    pub(crate) fn used_axis_bounds_cache_stats(&self) -> (usize, usize, usize, usize) {
        self.used_axis_bounds_cache
            .read()
            .ok()
            .and_then(|guard| {
                guard.as_ref().map(|cache| {
                    (
                        cache.row_hits.load(Ordering::Relaxed),
                        cache.row_misses.load(Ordering::Relaxed),
                        cache.col_hits.load(Ordering::Relaxed),
                        cache.col_misses.load(Ordering::Relaxed),
                    )
                })
            })
            .unwrap_or((0, 0, 0, 0))
    }

    pub fn set_first_load_assume_new(&mut self, enabled: bool) {
        self.graph.set_first_load_assume_new(enabled);
    }

    pub fn first_load_assume_new(&self) -> bool {
        self.graph.first_load_assume_new()
    }

    pub fn reset_ensure_touched(&mut self) {
        self.graph.reset_ensure_touched();
    }

    pub fn finalize_sheet_index(&mut self, sheet: &str) {
        self.graph.finalize_sheet_index(sheet);
    }

    /// Execute a named Engine action.
    ///
    /// Ticket 614 introduces this as the stable Engine-level transaction surface.
    /// For now actions are commit-only: they do not create changelog boundaries and they do not
    /// provide rollback/atomicity.
    ///
    /// Nested actions are deterministically handled by *disallowing* nesting: calling
    /// `Engine::action` while another action is active returns `EditorError::TransactionFailed`.
    pub fn action<T>(
        &mut self,
        name: impl AsRef<str>,
        f: impl FnOnce(&mut EngineAction<'_, R>) -> Result<T, crate::engine::EditorError>,
    ) -> Result<T, crate::engine::EditorError> {
        if self.action_depth != 0 {
            return Err(crate::engine::EditorError::TransactionFailed {
                reason: "Nested Engine::action calls are not supported (ticket 614: commit-only surface)"
                    .to_string(),
            });
        }

        self.action_depth = 1;
        let engine_ptr: *mut Engine<R> = self;
        let _guard = ActionDepthGuard {
            engine: engine_ptr,
            _marker: std::marker::PhantomData,
        };

        let mut tx = EngineAction {
            engine: self,
            name: name.as_ref().to_string(),
            log: None,
            arrow_undo: None,
            atomic_policy: false,
        };
        f(&mut tx)
    }

    /// Execute a named Engine action with atomic commit/rollback semantics.
    ///
    /// This variant does not require a `ChangeLog` and uses an internal journal for rollback.
    pub fn action_atomic<T>(
        &mut self,
        name: impl Into<String>,
        f: impl FnOnce(&mut EngineAction<'_, R>) -> Result<T, crate::engine::EditorError>,
    ) -> Result<T, crate::engine::EditorError> {
        let (v, _j) = self.action_atomic_journal(name, f)?;
        Ok(v)
    }

    /// Like `action_atomic`, but returns the committed journal entry for undo/redo storage.
    pub fn action_atomic_journal<T>(
        &mut self,
        name: impl Into<String>,
        f: impl FnOnce(&mut EngineAction<'_, R>) -> Result<T, crate::engine::EditorError>,
    ) -> Result<(T, crate::engine::ActionJournal), crate::engine::EditorError> {
        if self.action_depth != 0 {
            return Err(crate::engine::EditorError::TransactionFailed {
                reason: "Nested Engine::action calls are not supported (deterministic rule)"
                    .to_string(),
            });
        }

        self.action_depth = 1;
        let engine_ptr: *mut Engine<R> = self;
        let _guard = ActionDepthGuard {
            engine: engine_ptr,
            _marker: std::marker::PhantomData,
        };

        let name_str = name.into();
        let mut log = crate::engine::ChangeLog::new();
        let start_len = log.len();
        self.action_atomic_impl(&mut log, start_len, name_str, f)
    }

    fn action_atomic_impl<T>(
        &mut self,
        log: &mut crate::engine::ChangeLog,
        start_len: usize,
        name: String,
        f: impl FnOnce(&mut EngineAction<'_, R>) -> Result<T, crate::engine::EditorError>,
    ) -> Result<(T, crate::engine::ActionJournal), crate::engine::EditorError> {
        let mut arrow_undo = crate::engine::ArrowUndoBatch::default();
        let arrow_ptr: *mut crate::engine::ArrowUndoBatch = &mut arrow_undo;

        let log_ptr: *mut crate::engine::ChangeLog = log;
        let mut tx = EngineAction {
            engine: self,
            name: name.clone(),
            log: Some(log_ptr),
            arrow_undo: Some(arrow_ptr),
            atomic_policy: true,
        };

        let res = f(&mut tx);

        // Capture graph structural delta for this action.
        let graph_events: Vec<crate::engine::ChangeEvent> =
            unsafe { (&*log_ptr).events() }[start_len..].to_vec();
        let graph_batch = crate::engine::GraphUndoBatch {
            events: graph_events,
        };
        let affected_cells = arrow_undo.ops.len();
        let journal = crate::engine::ActionJournal {
            name,
            graph: graph_batch,
            arrow: arrow_undo,
            affected_cells,
        };

        match res {
            Ok(v) => {
                if !journal.graph.is_empty() || !journal.arrow.is_empty() {
                    for event in &journal.graph.events {
                        self.record_formula_plane_change_for_event(event);
                    }
                    self.mark_data_edited();
                }
                Ok((v, journal))
            }
            Err(e) => {
                if let Err(rb) = self.rollback_from_action_journal(&journal) {
                    return Err(crate::engine::EditorError::TransactionFailed {
                        reason: format!(
                            "Engine::action_atomic rollback failed after error '{e}': {rb}"
                        ),
                    });
                }
                if !journal.graph.is_empty() || !journal.arrow.is_empty() {
                    for event in &journal.graph.events {
                        self.record_formula_plane_change_for_event(event);
                    }
                }
                Err(e)
            }
        }
    }

    /// Execute a named Engine action, logging graph changes into the provided ChangeLog.
    ///
    /// Ticket 615: this variant provides atomicity. If the action returns an error, it rolls back:
    /// - Dependency graph structural edits (via inverse ChangeEvents)
    /// - Arrow-truth overlay writes mirrored from ChangeEvents
    /// - ChangeLog entries (truncated back to the pre-action length)
    pub fn action_with_logger<T>(
        &mut self,
        log: &mut crate::engine::ChangeLog,
        name: impl AsRef<str>,
        f: impl FnOnce(&mut EngineAction<'_, R>) -> Result<T, crate::engine::EditorError>,
    ) -> Result<T, crate::engine::EditorError> {
        if self.action_depth != 0 {
            return Err(crate::engine::EditorError::TransactionFailed {
                reason: "Nested Engine::action calls are not supported (deterministic rule)"
                    .to_string(),
            });
        }

        self.action_depth = 1;
        let engine_ptr: *mut Engine<R> = self;
        let _guard = ActionDepthGuard {
            engine: engine_ptr,
            _marker: std::marker::PhantomData,
        };

        let start_len = log.len();
        let name_str = name.as_ref().to_string();
        log.begin_compound(name_str.clone());

        // Use the provided ChangeLog as an observability sink.
        // Correctness is provided by the internal `ActionJournal` returned from the atomic impl.
        let res = self.action_atomic_impl(log, start_len, name_str, f);

        match res {
            Ok((v, _journal)) => {
                log.end_compound();
                Ok(v)
            }
            Err(e) => {
                // Close compound and truncate log as cleanup only.
                log.end_compound();
                log.truncate(start_len);
                Err(e)
            }
        }
    }

    fn rollback_from_action_journal(
        &mut self,
        journal: &crate::engine::ActionJournal,
    ) -> Result<(), crate::engine::EditorError> {
        // 1) Roll back the dependency graph structure.
        journal.graph.undo(&mut self.graph)?;
        // 2) Roll back engine row-visibility sidecar events.
        self.apply_inverse_row_visibility_events(&journal.graph.events);
        // 3) Roll back Arrow-truth overlays.
        self.apply_arrow_undo_batch(&journal.arrow, /*undo=*/ true);
        Ok(())
    }

    fn rollback_from_change_events(
        &mut self,
        events: &[crate::engine::ChangeEvent],
    ) -> Result<(), crate::engine::EditorError> {
        use crate::engine::ChangeEvent;

        // 1) Roll back the dependency graph.
        {
            let mut editor = crate::engine::VertexEditor::new(&mut self.graph);
            let mut compound_stack: Vec<usize> = Vec::new();
            for ev in events.iter().rev() {
                match ev {
                    ChangeEvent::CompoundEnd { depth } => compound_stack.push(*depth),
                    ChangeEvent::CompoundStart { depth, .. } => {
                        if compound_stack.last() == Some(depth) {
                            compound_stack.pop();
                        }
                    }
                    ChangeEvent::SetRowVisibility { .. } => {
                        // Engine-side metadata handled after dropping graph editor borrow.
                    }
                    _ => {
                        editor.apply_inverse(ev.clone())?;
                    }
                }
            }
        }

        // 2) Roll back engine row-visibility metadata.
        for ev in events.iter().rev() {
            self.apply_inverse_row_visibility_event(ev);
        }

        // 3) Roll back Arrow-truth overlays mirrored from those ChangeEvents.
        for ev in events.iter().rev() {
            self.mirror_inverse_change_to_arrow(ev);
        }

        Ok(())
    }

    fn read_cell_formula_ast(&self, sheet: &str, row: u32, col: u32) -> Option<ASTNode> {
        let sheet_id = self.graph.sheet_id(sheet)?;
        let coord = Coord::from_excel(row, col, true, true);
        let cell = CellRef::new(sheet_id, coord);
        let vid = self.graph.get_vertex_for_cell(&cell)?;
        let ast_id = self.graph.get_formula_id(vid)?;
        self.graph
            .data_store()
            .retrieve_ast(ast_id, self.graph.sheet_reg())
    }

    pub fn define_name_with_logger(
        &mut self,
        log: &mut crate::engine::ChangeLog,
        name: &str,
        definition: NamedDefinition,
        scope: NameScope,
    ) -> Result<(), crate::engine::EditorError> {
        self.graph
            .validate_define_name(name, scope)
            .map_err(crate::engine::EditorError::Excel)?;
        let has_dependent_spans = !self.exact_name_dependent_span_refs([name]).is_empty();
        if has_dependent_spans && matches!(definition, NamedDefinition::Formula { .. }) {
            return Err(crate::engine::EditorError::TransactionUnsupported {
                reason: "logged formula-name shadowing with active FormulaPlane dependents is not supported"
                    .to_string(),
            });
        }
        let prepared = self.prepare_name_dependent_span_demotion([name])?;
        let demoted = self.commit_name_dependent_span_demotion(prepared)?;
        {
            let mut editor = crate::engine::VertexEditor::with_logger(&mut self.graph, log);
            editor.define_name(name, definition, scope)?;
        }
        self.record_formula_plane_structural_change(StructuralScope::AllSheets);
        if !demoted {
            self.mark_topology_edited();
        }
        Ok(())
    }

    pub fn update_name_with_logger(
        &mut self,
        log: &mut crate::engine::ChangeLog,
        name: &str,
        definition: NamedDefinition,
        scope: NameScope,
    ) -> Result<(), crate::engine::EditorError> {
        self.graph
            .validate_existing_name(name, scope)
            .map_err(crate::engine::EditorError::Excel)?;
        let prepared = self.prepare_name_dependent_span_demotion([name])?;
        let demoted = self.commit_name_dependent_span_demotion(prepared)?;
        {
            let mut editor = crate::engine::VertexEditor::with_logger(&mut self.graph, log);
            editor.update_name(name, definition, scope)?;
        }
        self.record_formula_plane_structural_change(StructuralScope::AllSheets);
        if !demoted {
            self.mark_topology_edited();
        }
        Ok(())
    }

    pub fn delete_name_with_logger(
        &mut self,
        log: &mut crate::engine::ChangeLog,
        name: &str,
        scope: NameScope,
    ) -> Result<(), crate::engine::EditorError> {
        self.graph
            .validate_existing_name(name, scope)
            .map_err(crate::engine::EditorError::Excel)?;
        let prepared = self.prepare_name_dependent_span_demotion([name])?;
        let demoted = self.commit_name_dependent_span_demotion(prepared)?;
        {
            let mut editor = crate::engine::VertexEditor::with_logger(&mut self.graph, log);
            editor.delete_name(name, scope)?;
        }
        self.record_formula_plane_structural_change(StructuralScope::AllSheets);
        if !demoted {
            self.mark_topology_edited();
        }
        Ok(())
    }

    pub fn edit_with_logger<T>(
        &mut self,
        log: &mut crate::engine::ChangeLog,
        f: impl FnOnce(&mut crate::engine::VertexEditor) -> T,
    ) -> Result<T, crate::engine::EditorError> {
        // Record starting log length so we can mirror only newly-recorded events.
        let start_len = log.len();

        // Provide a spill snapshot reader so VertexEditor can snapshot Arrow-truth spill values
        // (graph value cache is intentionally empty in canonical mode).
        struct ArrowSpillReader<'a> {
            sheets: &'a crate::arrow_store::SheetStore,
        }
        impl crate::engine::graph::editor::vertex_editor::SpillValueReader for ArrowSpillReader<'_> {
            fn read_cell_value(
                &self,
                sheet: &str,
                row: u32,
                col: u32,
            ) -> Option<formualizer_common::LiteralValue> {
                use formualizer_common::LiteralValue;
                let asheet = self.sheets.sheet(sheet)?;
                let r0 = row.saturating_sub(1) as usize;
                let c0 = col.saturating_sub(1) as usize;
                let v = asheet.get_cell_value(r0, c0);
                if matches!(v, LiteralValue::Empty) {
                    None
                } else {
                    Some(v)
                }
            }
        }

        let ret = {
            let spill_reader = ArrowSpillReader {
                sheets: &self.arrow_sheets,
            };
            let mut editor = crate::engine::VertexEditor::with_logger_and_spill_reader(
                &mut self.graph,
                log,
                &spill_reader,
            );
            f(&mut editor)
        };

        let new_events = log.events()[start_len..].to_vec();
        if new_events.iter().any(|event| {
            matches!(
                event,
                ChangeEvent::DefineName { .. }
                    | ChangeEvent::UpdateName { .. }
                    | ChangeEvent::DeleteName { .. }
            )
        }) {
            self.rollback_from_change_events(&new_events)?;
            log.truncate(start_len);
            return Err(crate::engine::EditorError::TransactionUnsupported {
                reason: "name mutations must use Engine's prepared logged-name APIs".to_string(),
            });
        }

        // Mirror value-impacting graph events to Arrow for forward edits.
        // This keeps Arrow overlays (delta + computed) consistent when edits clear/commit spills.
        for ev in &new_events {
            self.mirror_forward_change_to_arrow(ev);
        }
        for ev in &new_events {
            self.record_formula_plane_change_for_event(ev);
        }

        Ok(ret)
    }

    pub(crate) fn preflight_replay_admission(
        &mut self,
        events: &[ChangeEvent],
        forward: bool,
    ) -> Result<(), crate::engine::EditorError> {
        if !self.graph_admission_enabled() {
            return Ok(());
        }
        let mut vertex_delta = 0i128;
        let mut edge_delta = 0i128;
        let mut added_vertices = 0usize;
        let mut added_edges = 0usize;
        let mut formula_cells = BTreeSet::new();
        for event in events {
            match event {
                ChangeEvent::AddVertex {
                    formula,
                    coord,
                    sheet_id,
                    ..
                } => {
                    let delta = if forward { 1 } else { -1 };
                    vertex_delta += delta;
                    if forward {
                        added_vertices = added_vertices.saturating_add(1);
                        if formula.is_some() {
                            formula_cells.insert((*sheet_id, coord.row(), coord.col()));
                        }
                    }
                }
                ChangeEvent::RemoveVertex {
                    old_formula,
                    coord,
                    sheet_id,
                    ..
                } => {
                    let delta = if forward { -1 } else { 1 };
                    vertex_delta += delta;
                    if !forward {
                        added_vertices = added_vertices.saturating_add(1);
                        if old_formula.is_some()
                            && let (Some(sheet_id), Some(coord)) = (sheet_id, coord)
                        {
                            formula_cells.insert((*sheet_id, coord.row(), coord.col()));
                        }
                    }
                }
                ChangeEvent::EdgeAdded { .. } => {
                    let delta = if forward { 1 } else { -1 };
                    edge_delta += delta;
                    if forward {
                        added_edges = added_edges.saturating_add(1);
                    }
                }
                ChangeEvent::EdgeRemoved { .. } => {
                    let delta = if forward { -1 } else { 1 };
                    edge_delta += delta;
                    if !forward {
                        added_edges = added_edges.saturating_add(1);
                    }
                }
                ChangeEvent::SetFormula {
                    addr, old_formula, ..
                } => {
                    if forward || old_formula.is_some() {
                        formula_cells.insert((addr.sheet_id, addr.coord.row(), addr.coord.col()));
                    }
                }
                _ => {}
            }
        }
        let stats = self.graph.baseline_stats();
        let final_vertices = i128::try_from(stats.graph_vertex_count)
            .ok()
            .and_then(|count| count.checked_add(vertex_delta))
            .and_then(|count| usize::try_from(count).ok())
            .ok_or_else(|| {
                crate::engine::EditorError::Excel(
                    ExcelError::new(ExcelErrorKind::NImpl)
                        .with_message("replay vertex count overflow"),
                )
            })?;
        let final_edges = i128::try_from(stats.graph_edge_count)
            .ok()
            .and_then(|count| count.checked_add(edge_delta))
            .and_then(|count| usize::try_from(count).ok())
            .ok_or_else(|| {
                crate::engine::EditorError::Excel(
                    ExcelError::new(ExcelErrorKind::NImpl)
                        .with_message("replay edge count overflow"),
                )
            })?;
        self.preflight_graph_admission(crate::engine::resource_ledger::GraphAdmission {
            final_vertices,
            final_edges,
            materialization_cells: formula_cells.len() as u64,
            added_vertices,
            added_edges,
        })
        .map_err(crate::engine::EditorError::Excel)
    }

    pub fn undo_logged(
        &mut self,
        undo: &mut crate::engine::graph::editor::undo_engine::UndoEngine,
        log: &mut crate::engine::ChangeLog,
    ) -> Result<(), crate::engine::EditorError> {
        let pending_events = log
            .last_group_indices()
            .into_iter()
            .map(|index| log.events()[index].clone())
            .collect::<Vec<_>>();
        self.preflight_replay_admission(&pending_events, false)?;
        let names = Self::name_event_names(&pending_events);
        let prepared =
            self.prepare_name_dependent_span_demotion(names.iter().map(String::as_str))?;
        let demoted = self.commit_name_dependent_span_demotion(prepared)?;
        let batch = undo.undo(&mut self.graph, log)?;
        for item in batch.iter().rev() {
            self.apply_inverse_row_visibility_event(&item.event);
            self.apply_inverse_staged_formula_event(&item.event);
        }
        self.mirror_undo_batch_to_arrow(&batch);
        if !batch.is_empty() {
            for item in &batch {
                self.record_formula_plane_change_for_event(&item.event);
            }
            if !demoted && !names.is_empty() {
                self.mark_topology_edited();
            }
        }
        Ok(())
    }

    pub fn redo_logged(
        &mut self,
        undo: &mut crate::engine::graph::editor::undo_engine::UndoEngine,
        log: &mut crate::engine::ChangeLog,
    ) -> Result<(), crate::engine::EditorError> {
        let pending_events = undo.pending_redo_events();
        self.preflight_replay_admission(&pending_events, true)?;
        let names = Self::name_event_names(&pending_events);
        let prepared =
            self.prepare_name_dependent_span_demotion(names.iter().map(String::as_str))?;
        let demoted = self.commit_name_dependent_span_demotion(prepared)?;
        let batch = undo.redo(&mut self.graph, log)?;
        for item in &batch {
            self.apply_forward_row_visibility_event(&item.event);
            self.apply_forward_staged_formula_event(&item.event);
        }
        self.mirror_redo_batch_to_arrow(&batch);
        if !batch.is_empty() {
            for item in &batch {
                self.record_formula_plane_change_for_event(&item.event);
            }
            if !demoted && !names.is_empty() {
                self.mark_topology_edited();
            }
        }
        Ok(())
    }

    /// Undo the last committed atomic action using the journal stack.
    ///
    /// This path does not require a `ChangeLog`.
    pub fn undo_action(
        &mut self,
        undo: &mut crate::engine::graph::editor::undo_engine::UndoEngine,
    ) -> Result<(), crate::engine::EditorError> {
        let Some(journal) = undo.pop_undo_action() else {
            return Ok(());
        };
        if let Err(error) = self.preflight_replay_admission(&journal.graph.events, false) {
            undo.push_done_action(journal);
            return Err(error);
        }
        let names = Self::name_event_names(&journal.graph.events);
        let prepared =
            match self.prepare_name_dependent_span_demotion(names.iter().map(String::as_str)) {
                Ok(prepared) => prepared,
                Err(error) => {
                    undo.push_done_action(journal);
                    return Err(error);
                }
            };
        let demoted = match self.commit_name_dependent_span_demotion(prepared) {
            Ok(demoted) => demoted,
            Err(error) => {
                undo.push_done_action(journal);
                return Err(error);
            }
        };

        journal.graph.undo(&mut self.graph)?;
        self.apply_inverse_row_visibility_events(&journal.graph.events);
        self.apply_arrow_undo_batch(&journal.arrow, /*undo=*/ true);
        if !journal.graph.is_empty() || !journal.arrow.is_empty() {
            for event in &journal.graph.events {
                self.record_formula_plane_change_for_event(event);
            }
            if !demoted && !names.is_empty() {
                self.mark_topology_edited();
            } else {
                self.mark_data_edited();
            }
        }

        undo.push_redo_action(journal);
        Ok(())
    }

    /// Redo the last undone atomic action using the journal stack.
    ///
    /// This path does not require a `ChangeLog`.
    pub fn redo_action(
        &mut self,
        undo: &mut crate::engine::graph::editor::undo_engine::UndoEngine,
    ) -> Result<(), crate::engine::EditorError> {
        let Some(journal) = undo.pop_redo_action() else {
            return Ok(());
        };
        if let Err(error) = self.preflight_replay_admission(&journal.graph.events, true) {
            undo.push_redo_action(journal);
            return Err(error);
        }
        let names = Self::name_event_names(&journal.graph.events);
        let prepared =
            match self.prepare_name_dependent_span_demotion(names.iter().map(String::as_str)) {
                Ok(prepared) => prepared,
                Err(error) => {
                    undo.push_redo_action(journal);
                    return Err(error);
                }
            };
        let demoted = match self.commit_name_dependent_span_demotion(prepared) {
            Ok(demoted) => demoted,
            Err(error) => {
                undo.push_redo_action(journal);
                return Err(error);
            }
        };

        journal.graph.redo(&mut self.graph)?;
        self.apply_forward_row_visibility_events(&journal.graph.events);
        self.apply_arrow_undo_batch(&journal.arrow, /*undo=*/ false);
        if !journal.graph.is_empty() || !journal.arrow.is_empty() {
            for event in &journal.graph.events {
                self.record_formula_plane_change_for_event(event);
            }
            if !demoted && !names.is_empty() {
                self.mark_topology_edited();
            } else {
                self.mark_data_edited();
            }
        }

        undo.push_done_action(journal);
        Ok(())
    }

    fn cellref_to_sheet_row_col(&self, addr: &crate::reference::CellRef) -> (String, u32, u32) {
        let sheet = self.graph.sheet_name(addr.sheet_id).to_string();
        // Coord stores 0-based indices.
        let row = addr.coord.row() + 1;
        let col = addr.coord.col() + 1;
        (sheet, row, col)
    }

    fn mirror_undo_batch_to_arrow(
        &mut self,
        batch: &[crate::engine::graph::editor::undo_engine::UndoBatchItem],
    ) {
        // Undo applies inverses in reverse order.
        for item in batch.iter().rev() {
            self.mirror_inverse_change_to_arrow(&item.event);
        }
    }

    fn mirror_redo_batch_to_arrow(
        &mut self,
        batch: &[crate::engine::graph::editor::undo_engine::UndoBatchItem],
    ) {
        // Redo applies events in forward order.
        for item in batch.iter() {
            self.mirror_forward_change_to_arrow(&item.event);
        }
    }

    fn mirror_inverse_change_to_arrow(&mut self, ev: &crate::engine::ChangeEvent) {
        use crate::engine::ChangeEvent;
        use formualizer_common::LiteralValue;

        match ev {
            ChangeEvent::SetValue {
                addr,
                old_value,
                old_formula,
                ..
            } => {
                let (sheet, row, col) = self.cellref_to_sheet_row_col(addr);
                if old_formula.is_some() {
                    self.clear_delta_overlay_cell(&sheet, row, col);
                } else {
                    let v = old_value.clone().unwrap_or(LiteralValue::Empty);
                    self.mirror_value_to_overlay(&sheet, row, col, &v);
                }
            }
            ChangeEvent::SetFormula {
                addr,
                old_value,
                old_formula,
                ..
            } => {
                let (sheet, row, col) = self.cellref_to_sheet_row_col(addr);
                if old_formula.is_some() {
                    self.clear_delta_overlay_cell(&sheet, row, col);
                } else {
                    let v = old_value.clone().unwrap_or(LiteralValue::Empty);
                    self.mirror_value_to_overlay(&sheet, row, col, &v);
                }
            }
            ChangeEvent::SpillCommitted { old, new, .. } => {
                // Inverse: restore `old` (or clear if none).
                self.mirror_spill_snapshot(new, /*clear_only=*/ true);
                if let Some(snap) = old {
                    self.mirror_spill_snapshot(snap, /*clear_only=*/ false);
                }
            }
            ChangeEvent::SpillCleared { old, .. } => {
                // Inverse: restore prior spill.
                self.mirror_spill_snapshot(old, /*clear_only=*/ false);
            }
            ChangeEvent::SetRowVisibility { .. } => {
                // Engine-side metadata only; no Arrow overlay effect.
            }
            _ => {}
        }
    }

    fn mirror_forward_change_to_arrow(&mut self, ev: &crate::engine::ChangeEvent) {
        use crate::engine::ChangeEvent;

        match ev {
            ChangeEvent::SetValue { addr, new, .. } => {
                let (sheet, row, col) = self.cellref_to_sheet_row_col(addr);
                self.mirror_value_to_overlay(&sheet, row, col, new);
            }
            ChangeEvent::SetFormula { addr, .. } => {
                let (sheet, row, col) = self.cellref_to_sheet_row_col(addr);
                self.clear_delta_overlay_cell(&sheet, row, col);
                // Keep any computed overlay for this cell as-is; it will be recomputed on demand.
            }
            ChangeEvent::SpillCommitted { old, new, .. } => {
                if let Some(snap) = old {
                    self.mirror_spill_snapshot(snap, /*clear_only=*/ true);
                }
                self.mirror_spill_snapshot(new, /*clear_only=*/ false);
            }
            ChangeEvent::SpillCleared { old, .. } => {
                self.mirror_spill_snapshot(old, /*clear_only=*/ true);
            }
            ChangeEvent::SetRowVisibility { .. } => {
                // Engine-side metadata only; no Arrow overlay effect.
            }
            _ => {
                // Other graph structural operations do not have direct value effects in Arrow.
            }
        }
    }

    fn mirror_spill_snapshot(
        &mut self,
        snap: &crate::engine::graph::editor::change_log::SpillSnapshot,
        clear_only: bool,
    ) {
        use formualizer_common::LiteralValue;

        let mut i = 0usize;
        for row in &snap.values {
            for v in row {
                if let Some(cell) = snap.target_cells.get(i) {
                    let (sheet, r, c) = self.cellref_to_sheet_row_col(cell);
                    let out = if clear_only {
                        LiteralValue::Empty
                    } else {
                        v.clone()
                    };
                    self.mirror_value_to_computed_overlay(&sheet, r, c, &out);
                }
                i += 1;
            }
        }
        // If target_cells is longer than values (should not happen), clear remaining cells.
        if clear_only {
            for cell in snap.target_cells.iter().skip(i) {
                let (sheet, r, c) = self.cellref_to_sheet_row_col(cell);
                self.mirror_value_to_computed_overlay(&sheet, r, c, &LiteralValue::Empty);
            }
        }
    }

    pub fn set_default_sheet_by_name(&mut self, name: &str) {
        self.graph.set_default_sheet_by_name(name);
    }

    pub fn set_default_sheet_by_id(&mut self, id: SheetId) {
        self.graph.set_default_sheet_by_id(id);
    }

    pub fn set_sheet_index_mode(&mut self, mode: crate::engine::SheetIndexMode) {
        self.graph.set_sheet_index_mode(mode);
    }

    fn clear_cached_static_schedule(&mut self) {
        self.cached_static_schedule = None;
    }

    /// Mark data edited: bump snapshot and set edited flag.
    /// Value-only edits keep the stable-topology schedule cache alive.
    pub fn mark_data_edited(&mut self) {
        self.snapshot_id
            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        self.has_edited = true;
    }

    /// Mark a topology-changing edit: bump snapshot + topology epoch and invalidate cached schedules.
    pub fn mark_topology_edited(&mut self) {
        self.snapshot_id
            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        self.topology_epoch = self.topology_epoch.wrapping_add(1);
        self.graph.bump_topology_revision();
        self.clear_cached_static_schedule();
        self.cached_mixed_topology = None;
        if let Some(ledger) = self.active_resource_ledger.as_mut() {
            let released = ledger.account_mixed_cache(0);
            debug_assert!(released.is_ok());
        }
        self.has_edited = true;
    }

    fn mark_all_formula_vertices_dirty(&mut self) {
        let vertices: Vec<VertexId> = self.graph.vertices_with_formulas().collect();
        for vertex in vertices {
            self.graph.mark_vertex_dirty(vertex);
        }
    }

    fn mark_moved_formula_vertices_dirty(
        &mut self,
        summary: &crate::engine::graph::editor::vertex_editor::ShiftSummary,
    ) {
        for vertex in &summary.vertices_moved {
            if self.graph.get_formula_id(*vertex).is_some() {
                self.graph.mark_vertex_dirty(*vertex);
            }
        }
    }

    /// Access Arrow sheet store (read-only)
    pub fn sheet_store(&self) -> &SheetStore {
        &self.arrow_sheets
    }

    /// Access Arrow sheet store (mutable)
    pub fn sheet_store_mut(&mut self) -> &mut SheetStore {
        &mut self.arrow_sheets
    }

    pub fn has_staged_formulas(&self) -> bool {
        !self.staged_formulas.is_empty()
    }

    pub fn staged_formula_count(&self) -> usize {
        self.staged_formulas.values().map(StagedSheet::len).sum()
    }

    /// Stage a formula text instead of inserting into the graph (used when deferring is enabled).
    pub fn stage_formula_text(&mut self, sheet: &str, row: u32, col: u32, text: String) {
        self.staged_formulas
            .entry(sheet.to_string())
            .or_default()
            .stage(row, col, text);
        self.staged_formula_index.stage(sheet, row, col);
    }

    fn index_removed_staged_sheet(&mut self, sheet: &str, staged: &StagedSheet) {
        for (row, col, _) in &staged.entries {
            self.staged_formula_index.remove(sheet, *row, *col);
        }
        if staged.deferred_package.is_some() {
            self.staged_formula_index.set_package(sheet, None);
        }
    }

    fn restore_staged_sheet(&mut self, sheet: String, staged: StagedSheet) {
        self.staged_formulas.insert(sheet, staged);
    }

    #[doc(hidden)]
    pub fn source_formula_ingress(&mut self) -> SourceFormulaIngress<'_, R> {
        SourceFormulaIngress { engine: self }
    }

    #[doc(hidden)]
    /// Test-only fault-injection seam. Not part of the supported API; it exists so
    /// integration tests in sibling crates can fail a commit at an exact point.
    #[doc(hidden)]
    #[cfg(any(test, feature = "test-support"))]
    pub fn set_before_prepared_span_commit_hook(
        &mut self,
        hook: impl FnOnce() + Send + Sync + 'static,
    ) {
        self.before_prepared_span_commit_hook = Some(Box::new(hook));
    }

    #[doc(hidden)]
    /// Test-only fault-injection seam, matching `set_after_eager_proposal_commit_hook`.
    #[cfg(test)]
    pub(crate) fn set_before_target_preparation_commit_hook(
        &mut self,
        hook: impl FnOnce() + Send + Sync + 'static,
    ) {
        self.before_target_preparation_commit_hook = Some(Box::new(hook));
    }

    fn stage_deferred_formula_package(&mut self, package: crate::engine::DeferredFormulaPackage) {
        let sheet = package.sheet_name.clone();
        let staged = self.staged_formulas.entry(sheet.clone()).or_default();
        debug_assert!(staged.deferred_package.is_none());
        staged.deferred_package = Some(package);
        staged.reconcile_attached_deferred_package();
        self.staged_formula_index
            .set_package(&sheet, staged.deferred_package.as_ref());
    }

    pub fn clear_staged_formula_text(&mut self, sheet: &str, row: u32, col: u32) -> Option<String> {
        let mut removed = None;
        let mut remove_sheet = false;
        let mut had_package = false;
        if let Some(entries) = self.staged_formulas.get_mut(sheet) {
            had_package = entries.deferred_package.is_some();
            removed = entries.remove(row, col);
            remove_sheet = entries.is_empty();
        }
        let ordinary_removed = self.staged_formula_index.remove(sheet, row, col);
        if !ordinary_removed && had_package {
            self.staged_formula_index.touch_package(sheet);
        }
        if remove_sheet {
            self.staged_formulas.remove(sheet);
            self.staged_formula_index.set_package(sheet, None);
        }
        removed
    }

    pub fn clear_staged_formulas_for_sheet(&mut self, sheet: &str) {
        if self.staged_formulas.remove(sheet).is_some() {
            self.staged_formula_index.clear_sheet(sheet);
        }
    }

    pub fn rename_staged_formula_sheet(&mut self, old: &str, new: &str) {
        let Some(entries) = self.staged_formulas.remove(old) else {
            return;
        };
        self.staged_formula_index.clear_sheet(old);
        let (formulas, mut package) = entries.into_parts();
        for (row, col, text) in formulas {
            self.stage_formula_text(new, row, col, text);
        }
        if let Some(package) = package.as_mut() {
            package.sheet_name = new.to_string();
        }
        if let Some(package) = package {
            self.stage_deferred_formula_package(package);
        }
    }

    /// Get a staged formula text for a given cell if present (cloned).
    pub fn get_staged_formula_text(&self, sheet: &str, row: u32, col: u32) -> Option<String> {
        self.staged_formulas
            .get(sheet)
            .and_then(|v| v.get(row, col))
    }

    pub fn formula_parse_diagnostics(&self) -> &[FormulaParseDiagnostic] {
        &self.formula_parse_diagnostics
    }

    pub fn take_formula_parse_diagnostics(&mut self) -> Vec<FormulaParseDiagnostic> {
        std::mem::take(&mut self.formula_parse_diagnostics)
    }

    pub fn clear_formula_parse_diagnostics(&mut self) {
        self.formula_parse_diagnostics.clear();
    }

    pub fn last_formula_ingest_report(&self) -> Option<&FormulaIngestReport> {
        self.last_formula_ingest_report.as_ref()
    }

    pub fn formula_ingest_report_total(&self) -> &FormulaIngestReport {
        &self.formula_ingest_report_total
    }

    #[cfg(test)]
    pub(crate) fn set_before_target_planning_snapshot_hook_for_test(
        &mut self,
        hook: impl FnOnce() + Send + Sync + 'static,
    ) {
        self.before_target_planning_snapshot_hook = Some(Box::new(hook));
    }

    #[cfg(test)]
    pub(crate) fn inject_target_semantic_stale_once_for_test(&mut self) {
        self.inject_target_semantic_stale_once_for_test = true;
    }

    #[cfg(test)]
    pub(crate) fn force_virtual_dep_changes_for_test(&mut self, rounds: usize) {
        self.force_virtual_dep_changes_remaining_for_test = rounds;
    }

    #[cfg(test)]
    pub(crate) fn fail_evaluation_commit_preflight_once_for_test(&mut self) {
        self.fail_evaluation_commit_preflight_once_for_test = true;
    }

    #[cfg(test)]
    pub(crate) fn set_target_preparation_fault_for_test(
        &mut self,
        fault: crate::engine::target_preparation::TargetPreparationFault,
    ) {
        self.target_preparation_fault_for_test = Some(fault);
    }

    #[cfg(test)]
    pub(crate) fn staged_formula_index_revision_for_test(&self) -> u64 {
        self.staged_formula_index.revision()
    }

    #[cfg(test)]
    pub(crate) fn staged_formula_index_is_consistent_for_test(&self) -> bool {
        let ordinary_storage = self
            .staged_formulas
            .values()
            .map(|sheet| sheet.entries.len())
            .sum::<usize>();
        let package_storage = self
            .staged_formulas
            .values()
            .filter(|sheet| sheet.deferred_package.is_some())
            .count();
        ordinary_storage == self.staged_formula_index.ordinary_count()
            && package_storage == self.staged_formula_index.package_count()
            && self.staged_formulas.iter().all(|(name, sheet)| {
                sheet.entries.iter().all(|(row, col, _)| {
                    let leases = self
                        .staged_formula_index
                        .leases_in_region(name, *row, *col, *row, *col);
                    leases.len() == 1 && leases[0].row == *row && leases[0].col == *col
                })
            })
    }

    #[cfg(test)]
    pub(crate) fn last_formula_plane_span_eval_report(&self) -> Option<&SpanEvalReport> {
        self.last_formula_plane_span_eval_report.as_ref()
    }

    #[cfg(test)]
    pub(crate) fn evaluation_request_begin_count_for_test(&self) -> u64 {
        self.evaluation_request_begin_count_for_test
    }

    #[cfg(test)]
    pub(crate) fn force_source_family_fallback_for_test(&mut self, force: bool) {
        self.force_source_family_fallback = force;
    }

    #[cfg(test)]
    pub(crate) fn rerecord_cycle_retry_span_after_lease_extension_for_test(&mut self) {
        self.rerecord_cycle_retry_span_after_lease_extension_for_test = true;
    }

    #[cfg(test)]
    pub(crate) fn set_fragmented_commit_fault_for_test(
        &mut self,
        fault: crate::engine::fragmented_transaction::FragmentedCommitFault,
    ) {
        self.fragmented_commit_fault_for_test = Some(fault);
    }

    #[cfg(test)]
    pub(crate) fn set_before_legacy_fallback_final_provider_sample_hook(
        &mut self,
        hook: impl FnOnce() + Send + Sync + 'static,
    ) {
        self.before_legacy_fallback_final_provider_sample_hook = Some(Box::new(hook));
    }

    #[cfg(test)]
    pub(crate) fn set_after_eager_proposal_commit_hook(
        &mut self,
        hook: impl FnOnce() + Send + Sync + 'static,
    ) {
        self.after_eager_proposal_commit_hook = Some(Box::new(hook));
    }

    #[cfg(test)]
    pub(crate) fn formula_plane_indexes_epoch(&self) -> u64 {
        self.graph.formula_authority().indexes_epoch()
    }

    #[cfg(test)]
    pub(crate) fn formula_plane_capacity_bailouts(&self) -> u64 {
        self.formula_plane_capacity_bailouts
    }

    #[cfg(test)]
    pub(crate) fn topology_epoch_for_test(&self) -> u64 {
        self.topology_epoch
    }

    #[cfg(test)]
    pub(crate) fn graph_topology_revision_for_test(&self) -> u64 {
        self.graph.topology_revision()
    }

    #[cfg(test)]
    pub(crate) fn mixed_topology_cache_present_for_test(&self) -> bool {
        self.cached_mixed_topology.is_some()
    }

    fn record_formula_ingest_report(&mut self, report: FormulaIngestReport) {
        self.formula_ingest_report_total.mode = report.mode;
        self.formula_ingest_report_total.accumulate(&report);
        self.last_formula_ingest_report = Some(report);
    }

    fn prepare_source_formula_family(
        &mut self,
        sheet_id: SheetId,
        family: &crate::engine::SourceFormulaFamily,
        allow_function_closure: bool,
        planning_provider: Option<&dyn crate::traits::FunctionProvider>,
    ) -> Result<
        (
            crate::formula_plane::placement::PreparedAnchorOncePlacement,
            bool,
        ),
        SourceFamilyPreparationError,
    > {
        let transport = family
            .validated_complete_domain(&self.workbook_load_limits)
            .map_err(SourceFamilyPreparationError::contract)?;
        let domain = match transport {
            crate::engine::PlacementDomainTransport::RowRun {
                row_start,
                row_end,
                col,
            } => PlacementDomain::row_run(sheet_id, row_start, row_end, col),
            crate::engine::PlacementDomainTransport::ColRun {
                row,
                col_start,
                col_end,
            } => PlacementDomain::col_run(sheet_id, row, col_start, col_end),
            crate::engine::PlacementDomainTransport::Rect(rect) => PlacementDomain::rect(
                sheet_id,
                rect.start.row,
                rect.end.row,
                rect.start.col,
                rect.end.col,
            ),
        };
        let formula = if family.anchor_text.starts_with('=') {
            family.anchor_text.to_string()
        } else {
            format!("={}", family.anchor_text)
        };
        let ast = formualizer_parse::parser::parse(&formula)
            .map_err(|_| SourceFamilyPreparationError::parse("AnchorParseRejected"))?;
        let relocation = if allow_function_closure {
            validate_anchor_once_shadow_relocation(
                &ast,
                family.anchor_coord0.row,
                family.anchor_coord0.col,
                &domain,
                planning_provider.unwrap_or(&self.resolver),
            )
        } else {
            validate_anchor_once_syntax(
                &ast,
                family.anchor_coord0.row,
                family.anchor_coord0.col,
                &domain,
            )
        };
        relocation.map_err(SourceFamilyPreparationError::ast)?;
        let ast_id = self.intern_formula_ast(&ast);
        let placement = CellRef::new(
            sheet_id,
            Coord::from_excel(
                family.anchor_coord0.row + 1,
                family.anchor_coord0.col + 1,
                true,
                true,
            ),
        );
        let ingested = {
            let mut pipeline = match planning_provider {
                Some(provider) => self.graph.ingest_pipeline(provider),
                None => self.ingest_pipeline(),
            };
            if allow_function_closure {
                pipeline = pipeline.enable_function_semantics();
            }
            pipeline.ingest_formula(
                FormulaAstInput::RawArena(ast_id),
                placement,
                Some(family.anchor_text.clone()),
            )
        }
        .map_err(|_| SourceFamilyPreparationError::ast("UnsupportedCanonicalTemplate"))?;
        let function_semantics_used = ingested
            .labels
            .has_flag(crate::engine::arena::ast::CanonicalLabels::FLAG_CONTAINS_FUNCTION);
        let candidate = FormulaPlacementCandidate::new(
            sheet_id,
            family.anchor_coord0.row,
            family.anchor_coord0.col,
            ingested.ast_id,
            Some(family.anchor_text.clone()),
        );
        let analysis = CandidateAnalysis::from_ingested(&candidate, &ingested)
            .map_err(|reason| SourceFamilyPreparationError::ast(format!("{reason:?}")))?;
        prepare_anchor_once_family(candidate, analysis, domain, family.member_count)
            .map(|prepared| (prepared, function_semantics_used))
            .map_err(|reason| SourceFamilyPreparationError::analysis(format!("{reason:?}")))
    }

    fn placement_domain_from_transport(
        sheet_id: SheetId,
        transport: crate::engine::PlacementDomainTransport,
    ) -> PlacementDomain {
        match transport {
            crate::engine::PlacementDomainTransport::RowRun {
                row_start,
                row_end,
                col,
            } => PlacementDomain::row_run(sheet_id, row_start, row_end, col),
            crate::engine::PlacementDomainTransport::ColRun {
                row,
                col_start,
                col_end,
            } => PlacementDomain::col_run(sheet_id, row, col_start, col_end),
            crate::engine::PlacementDomainTransport::Rect(rect) => PlacementDomain::rect(
                sheet_id,
                rect.start.row,
                rect.end.row,
                rect.start.col,
                rect.end.col,
            ),
        }
    }

    #[cfg(test)]
    pub(crate) fn analyze_fragmented_exact_replay_record_for_test(
        &mut self,
        sheet_name: &str,
        source_id: crate::engine::SourceFamilyId,
        expected: crate::engine::PartitionLegacyMember,
        replay: crate::engine::DeferredReplayFormula,
    ) -> Result<crate::engine::fragmented_transaction::PreparedFragmentedLegacyFormula, String>
    {
        let sheet_id = self.graph.sheet_id_mut(sheet_name);
        self.graph
            .analyze_fragmented_exact_replay_record(
                &self.resolver,
                sheet_id,
                source_id,
                expected,
                replay,
            )
            .map_err(|error| format!("{error:?}"))
    }

    pub(crate) fn prepare_fragmented_source_transaction(
        &mut self,
        source: &crate::engine::PartitionedSourceFormulaFamily,
        disposition: &crate::engine::FormulaReplayDisposition,
        prepared: crate::engine::fragmented_transaction::PreparedPartitionedSourceFamily,
        legacy_formulas: Vec<
            crate::engine::fragmented_transaction::PreparedFragmentedLegacyFormula,
        >,
    ) -> Result<
        crate::engine::fragmented_transaction::PreparedFragmentedSourceTransaction,
        crate::engine::fragmented_transaction::FragmentedTransactionPrepareError,
    > {
        let transaction = self.graph.prepare_fragmented_source_transaction(
            &self.source_formula_token,
            source,
            disposition,
            prepared,
            legacy_formulas,
        )?;
        self.prepared_legacy_admission(
            transaction.legacy_graph(),
            transaction.materialization_cells(),
        )
        .map_err(
            crate::engine::fragmented_transaction::FragmentedTransactionPrepareError::Admission,
        )?;
        Ok(transaction)
    }

    pub(crate) fn commit_fragmented_source_transaction(
        &mut self,
        prepared: crate::engine::fragmented_transaction::PreparedFragmentedSourceTransaction,
        disposition: &crate::engine::FormulaReplayDisposition,
    ) -> crate::engine::fragmented_transaction::FragmentedCommitDecision {
        let registry_guard = crate::function_registry::semantic_epoch_read_guard();
        let provider_revision = self.resolver.planning_semantic_revision();
        let epoch = registry_guard.epoch();
        let resolver = &self.resolver;
        let decision = self.graph.commit_fragmented_source_transaction(
            prepared,
            &self.source_formula_token,
            disposition,
            epoch,
            provider_revision,
            || resolver.planning_semantic_revision(),
            crate::engine::fragmented_transaction::FragmentedCommitFault::None,
        );
        drop(registry_guard);
        decision
    }

    #[cfg(test)]
    pub(crate) fn commit_fragmented_source_transaction_with_fault_for_test(
        &mut self,
        prepared: crate::engine::fragmented_transaction::PreparedFragmentedSourceTransaction,
        disposition: &crate::engine::FormulaReplayDisposition,
        fault: crate::engine::fragmented_transaction::FragmentedCommitFault,
    ) -> crate::engine::fragmented_transaction::FragmentedCommitDecision {
        let registry_guard = crate::function_registry::semantic_epoch_read_guard();
        let provider_revision = self.resolver.planning_semantic_revision();
        let epoch = registry_guard.epoch();
        let resolver = &self.resolver;
        let decision = self.graph.commit_fragmented_source_transaction(
            prepared,
            &self.source_formula_token,
            disposition,
            epoch,
            provider_revision,
            || resolver.planning_semantic_revision(),
            fault,
        );
        drop(registry_guard);
        decision
    }

    #[cfg(test)]
    pub(crate) fn commit_fragmented_source_transaction_with_provider_flip_for_test(
        &mut self,
        prepared: crate::engine::fragmented_transaction::PreparedFragmentedSourceTransaction,
        disposition: &crate::engine::FormulaReplayDisposition,
        before_second_sample: impl FnOnce(),
    ) -> crate::engine::fragmented_transaction::FragmentedCommitDecision {
        let registry_guard = crate::function_registry::semantic_epoch_read_guard();
        let provider_revision = self.resolver.planning_semantic_revision();
        let epoch = registry_guard.epoch();
        let resolver = &self.resolver;
        let decision = self.graph.commit_fragmented_source_transaction(
            prepared,
            &self.source_formula_token,
            disposition,
            epoch,
            provider_revision,
            || {
                before_second_sample();
                resolver.planning_semantic_revision()
            },
            crate::engine::fragmented_transaction::FragmentedCommitFault::None,
        );
        drop(registry_guard);
        decision
    }

    #[cfg(test)]
    pub(crate) fn commit_fragmented_source_transaction_with_revisions_for_test(
        &mut self,
        prepared: crate::engine::fragmented_transaction::PreparedFragmentedSourceTransaction,
        disposition: &crate::engine::FormulaReplayDisposition,
        function_semantic_epoch: u64,
        function_provider_revision: Option<u64>,
    ) -> crate::engine::fragmented_transaction::FragmentedCommitDecision {
        self.graph.commit_fragmented_source_transaction(
            prepared,
            &self.source_formula_token,
            disposition,
            function_semantic_epoch,
            function_provider_revision,
            || function_provider_revision,
            crate::engine::fragmented_transaction::FragmentedCommitFault::None,
        )
    }

    pub(crate) fn analyze_partitioned_source_family_for_transaction(
        &mut self,
        sheet_name: &str,
        family: &crate::engine::PartitionedSourceFormulaFamily,
    ) -> Result<
        crate::engine::fragmented_transaction::PreparedPartitionedSourceFamily,
        SourceFamilyPreparationError,
    > {
        family
            .validate(&self.workbook_load_limits)
            .map_err(SourceFamilyPreparationError::contract)?;
        let formula = if family.template_text.starts_with('=') {
            family.template_text.to_string()
        } else {
            format!("={}", family.template_text)
        };
        let ast = formualizer_parse::parser::parse(&formula)
            .map_err(|_| SourceFamilyPreparationError::parse("AnchorParseRejected"))?;
        let mut requests = Vec::new();
        Self::collect_planning_function_requests(&ast, &mut requests);
        let snapshot = crate::function_registry::RegistryPlanningSnapshot::capture_for_requests(
            &self.resolver,
            requests,
        )
        .map_err(|error| SourceFamilyPreparationError::ast(format!("{error:?}")))?;
        let sheet_id = self.graph.sheet_id_mut(sheet_name);
        let domains: Vec<_> = family
            .fragments
            .iter()
            .copied()
            .map(|transport| Self::placement_domain_from_transport(sheet_id, transport))
            .collect();
        for domain in &domains {
            validate_anchor_once_shadow_relocation(
                &ast,
                family.template_origin0.row,
                family.template_origin0.col,
                domain,
                &snapshot,
            )
            .map_err(SourceFamilyPreparationError::ast)?;
        }
        let ast_id = self.intern_formula_ast(&ast);
        let placement = CellRef::new(
            sheet_id,
            Coord::from_excel(
                family.template_origin0.row + 1,
                family.template_origin0.col + 1,
                true,
                true,
            ),
        );
        let ingested = self
            .graph
            .ingest_pipeline(&snapshot)
            .enable_function_semantics()
            .ingest_formula(
                FormulaAstInput::RawArena(ast_id),
                placement,
                Some(family.template_text.clone()),
            )
            .map_err(|_| SourceFamilyPreparationError::ast("UnsupportedCanonicalTemplate"))?;
        let function_semantics_used = ingested
            .labels
            .has_flag(crate::engine::arena::ast::CanonicalLabels::FLAG_CONTAINS_FUNCTION);
        let name_assumptions = self
            .graph
            .capture_fragmented_name_assumptions(sheet_id, &ingested.dep_plan.resolved_named_refs)
            .map_err(|error| SourceFamilyPreparationError::ast(format!("{error:?}")))?;
        let candidate = FormulaPlacementCandidate::new(
            sheet_id,
            family.template_origin0.row,
            family.template_origin0.col,
            ingested.ast_id,
            Some(family.template_text.clone()),
        );
        let analysis = CandidateAnalysis::from_ingested(&candidate, &ingested)
            .map_err(|reason| SourceFamilyPreparationError::analysis(format!("{reason:?}")))?;
        let direct_cells = domains.iter().try_fold(0u64, |total, domain| {
            total
                .checked_add(domain.cell_count())
                .ok_or_else(|| SourceFamilyPreparationError::analysis("PartitionAreaOverflow"))
        })?;
        let mut placements = Vec::with_capacity(domains.len());
        for domain in domains {
            let member_count = domain.cell_count();
            placements.push(
                prepare_anchor_once_fragment(
                    candidate.clone(),
                    analysis.clone(),
                    domain,
                    member_count,
                    direct_cells,
                )
                .map_err(|reason| SourceFamilyPreparationError::analysis(format!("{reason:?}")))?,
            );
        }
        let fallback_cells = family.legacy_members.shared_member_count() as u64;
        if direct_cells.checked_add(fallback_cells) != Some(family.surviving_member_count) {
            return Err(SourceFamilyPreparationError::analysis(
                "PartitionMemberCountMismatch",
            ));
        }
        Ok(
            crate::engine::fragmented_transaction::PreparedPartitionedSourceFamily {
                engine_token: Arc::clone(&self.source_formula_token),
                sheet_id,
                sheet_name: Arc::from(sheet_name),
                source: family.clone(),
                placements,
                function_semantic_epoch: snapshot.epoch(),
                function_provider_revision: snapshot.provider_revision(),
                function_semantics_used,
                name_assumptions,
                direct_cells,
            },
        )
    }

    fn prepare_partitioned_source_formula_family_shadow(
        &mut self,
        sheet_id: SheetId,
        family: &crate::engine::PartitionedSourceFormulaFamily,
    ) -> Result<PreparedPartitionShadow, SourceFamilyPreparationError> {
        family
            .validate(&self.workbook_load_limits)
            .map_err(SourceFamilyPreparationError::contract)?;
        let formula = if family.template_text.starts_with('=') {
            family.template_text.to_string()
        } else {
            format!("={}", family.template_text)
        };
        let ast = formualizer_parse::parser::parse(&formula)
            .map_err(|_| SourceFamilyPreparationError::parse("AnchorParseRejected"))?;
        let domains: Vec<_> = family
            .fragments
            .iter()
            .copied()
            .map(|transport| Self::placement_domain_from_transport(sheet_id, transport))
            .collect();
        for domain in &domains {
            validate_anchor_once_shadow_relocation(
                &ast,
                family.template_origin0.row,
                family.template_origin0.col,
                domain,
                &self.resolver,
            )
            .map_err(SourceFamilyPreparationError::ast)?;
        }
        let ast_id = self.intern_formula_ast(&ast);
        let placement = CellRef::new(
            sheet_id,
            Coord::from_excel(
                family.template_origin0.row + 1,
                family.template_origin0.col + 1,
                true,
                true,
            ),
        );
        let ingested = self
            .ingest_pipeline()
            .enable_function_semantics()
            .ingest_formula(
                FormulaAstInput::RawArena(ast_id),
                placement,
                Some(family.template_text.clone()),
            )
            .map_err(|_| SourceFamilyPreparationError::ast("UnsupportedCanonicalTemplate"))?;
        let function_semantics_used = ingested
            .labels
            .has_flag(crate::engine::arena::ast::CanonicalLabels::FLAG_CONTAINS_FUNCTION);
        let candidate = FormulaPlacementCandidate::new(
            sheet_id,
            family.template_origin0.row,
            family.template_origin0.col,
            ingested.ast_id,
            Some(family.template_text.clone()),
        );
        let analysis = CandidateAnalysis::from_ingested(&candidate, &ingested)
            .map_err(|reason| SourceFamilyPreparationError::ast(format!("{reason:?}")))?;
        let fragment_count = domains.len() as u64;
        let mut direct_cells = 0u64;
        for domain in domains {
            let member_count = domain.cell_count();
            validate_anchor_once_fragment_shadow(&analysis, &domain, member_count)
                .map_err(|reason| SourceFamilyPreparationError::analysis(format!("{reason:?}")))?;
            direct_cells = direct_cells
                .checked_add(member_count)
                .ok_or_else(|| SourceFamilyPreparationError::analysis("PartitionAreaOverflow"))?;
        }
        let fallback_cells = family.legacy_members.shared_member_count() as u64;
        if direct_cells.checked_add(fallback_cells) != Some(family.surviving_member_count) {
            return Err(SourceFamilyPreparationError::analysis(
                "PartitionMemberCountMismatch",
            ));
        }
        Ok(PreparedPartitionShadow {
            fragment_count,
            direct_cells,
            fallback_cells,
            function_semantics_used,
        })
    }

    fn analyze_partitioned_formula_plane_shadow(
        &mut self,
        batches: &[(String, Vec<crate::engine::PartitionedSourceFormulaFamily>)],
    ) -> FormulaIngestReport {
        let mut report = FormulaIngestReport::with_mode(FormulaPlaneMode::Shadow);
        for (sheet_name, families) in batches {
            let sheet_id = self.graph.sheet_id_mut(sheet_name);
            for family in families {
                report.shadow_candidate_cells = report
                    .shadow_candidate_cells
                    .saturating_add(family.surviving_member_count);
                match self.prepare_partitioned_source_formula_family_shadow(sheet_id, family) {
                    Ok(prepared) => {
                        let fragment_count = prepared.fragment_count;
                        let descendants = family.surviving_member_count.saturating_sub(1);
                        report.source_anchor_parses = report.source_anchor_parses.saturating_add(1);
                        report.source_anchor_asts = report.source_anchor_asts.saturating_add(1);
                        report.source_anchor_analyses =
                            report.source_anchor_analyses.saturating_add(1);
                        report.source_partition_analyses_reused = report
                            .source_partition_analyses_reused
                            .saturating_add(fragment_count.saturating_sub(1));
                        report.source_partitioned_families_prepared = report
                            .source_partitioned_families_prepared
                            .saturating_add(1);
                        report.source_partition_fragments_prepared = report
                            .source_partition_fragments_prepared
                            .saturating_add(fragment_count);
                        report.source_partition_span_cells_prepared = report
                            .source_partition_span_cells_prepared
                            .saturating_add(prepared.direct_cells);
                        report.source_partition_fallback_cells = report
                            .source_partition_fallback_cells
                            .saturating_add(prepared.fallback_cells);
                        report.shadow_accepted_span_cells = report
                            .shadow_accepted_span_cells
                            .saturating_add(prepared.direct_cells);
                        report.shadow_fallback_cells = report
                            .shadow_fallback_cells
                            .saturating_add(prepared.fallback_cells);
                        report.source_descendant_strings_avoided = report
                            .source_descendant_strings_avoided
                            .saturating_add(descendants);
                        report.source_descendant_events_avoided = report
                            .source_descendant_events_avoided
                            .saturating_add(descendants);
                        report.source_descendant_analyses_avoided = report
                            .source_descendant_analyses_avoided
                            .saturating_add(descendants);
                        report.graph_formula_vertices_avoided_shadow = report
                            .graph_formula_vertices_avoided_shadow
                            .saturating_add(prepared.direct_cells);
                        report.ast_roots_avoided_shadow = report
                            .ast_roots_avoided_shadow
                            .saturating_add(prepared.direct_cells.saturating_sub(fragment_count));
                        report.edge_rows_avoided_shadow = report
                            .edge_rows_avoided_shadow
                            .saturating_add(prepared.direct_cells);
                        if prepared.function_semantics_used {
                            report.source_partition_function_semantics =
                                report.source_partition_function_semantics.saturating_add(1);
                        }
                    }
                    Err(error) => {
                        if error.parse_attempted {
                            report.source_anchor_parses =
                                report.source_anchor_parses.saturating_add(1);
                        }
                        if error.ast_created {
                            report.source_anchor_asts = report.source_anchor_asts.saturating_add(1);
                        }
                        if error.analysis_created {
                            report.source_anchor_analyses =
                                report.source_anchor_analyses.saturating_add(1);
                        }
                        report.shadow_fallback_cells = report
                            .shadow_fallback_cells
                            .saturating_add(family.surviving_member_count);
                        report.source_partitioned_families_rejected = report
                            .source_partitioned_families_rejected
                            .saturating_add(1);
                        *report.fallback_reasons.entry(error.reason).or_default() += 1;
                    }
                }
            }
        }
        report
    }

    fn analyze_compressed_formula_plane_shadow(
        &mut self,
        batches: &[(String, Vec<crate::engine::SourceFormulaFamily>)],
    ) -> FormulaIngestReport {
        let mut report = FormulaIngestReport::with_mode(FormulaPlaneMode::Shadow);
        let _active_epoch = self.graph.formula_authority().plane.epoch();

        for (sheet_name, families) in batches {
            let sheet_id = self.graph.sheet_id_mut(sheet_name);
            for family in families {
                let descendants = family.member_count.saturating_sub(1);
                report.shadow_candidate_cells = report
                    .shadow_candidate_cells
                    .saturating_add(family.member_count);

                match self.prepare_source_formula_family(sheet_id, family, true, None) {
                    Ok(_) => {
                        report.source_descendant_strings_avoided = report
                            .source_descendant_strings_avoided
                            .saturating_add(descendants);
                        report.source_descendant_events_avoided = report
                            .source_descendant_events_avoided
                            .saturating_add(descendants);
                        report.source_descendant_analyses_avoided = report
                            .source_descendant_analyses_avoided
                            .saturating_add(descendants);
                        report.source_anchor_parses = report.source_anchor_parses.saturating_add(1);
                        report.source_anchor_asts = report.source_anchor_asts.saturating_add(1);
                        report.source_anchor_analyses =
                            report.source_anchor_analyses.saturating_add(1);
                        report.shadow_accepted_span_cells = report
                            .shadow_accepted_span_cells
                            .saturating_add(family.member_count);
                        report.source_compressed_families_prepared =
                            report.source_compressed_families_prepared.saturating_add(1);
                        report.source_compressed_cells_prepared = report
                            .source_compressed_cells_prepared
                            .saturating_add(family.member_count);
                        report.graph_formula_vertices_avoided_shadow = report
                            .graph_formula_vertices_avoided_shadow
                            .saturating_add(family.member_count);
                        report.ast_roots_avoided_shadow =
                            report.ast_roots_avoided_shadow.saturating_add(descendants);
                        report.edge_rows_avoided_shadow = report
                            .edge_rows_avoided_shadow
                            .saturating_add(family.member_count);
                    }
                    Err(error) => {
                        if error.parse_attempted {
                            report.source_anchor_parses =
                                report.source_anchor_parses.saturating_add(1);
                        }
                        if error.ast_created {
                            report.source_anchor_asts = report.source_anchor_asts.saturating_add(1);
                        }
                        if error.analysis_created {
                            report.source_anchor_analyses =
                                report.source_anchor_analyses.saturating_add(1);
                        }
                        report.shadow_fallback_cells = report
                            .shadow_fallback_cells
                            .saturating_add(family.member_count);
                        *report.fallback_reasons.entry(error.reason).or_default() += 1;
                    }
                }
            }
        }
        report
    }

    fn analyze_formula_plane_shadow_candidates(
        &mut self,
        batches: &[FormulaIngestBatch],
    ) -> FormulaIngestReport {
        let mut report = FormulaIngestReport::with_mode(FormulaPlaneMode::Shadow);
        report.formula_cells_seen = batches.iter().map(|batch| batch.len() as u64).sum();

        // Touch graph-owned authority deliberately: Tranche 3 shadow analysis uses
        // scratch state, but FormulaPlane ownership now lives on DependencyGraph.
        let _active_epoch = self.graph.formula_authority().plane.epoch();

        let batch_sheet_ids: Vec<SheetId> = batches
            .iter()
            .map(|batch| self.graph.sheet_id_mut(&batch.sheet_name))
            .collect();
        let mut groups: BTreeMap<
            (SheetId, u64, u32),
            Vec<(FormulaPlacementCandidate, CandidateAnalysis)>,
        > = BTreeMap::new();
        {
            let mut pipeline = self.ingest_pipeline();
            for (batch, sheet_id) in batches.iter().zip(batch_sheet_ids.iter().copied()) {
                for record in &batch.formulas {
                    if record.row == 0 || record.col == 0 {
                        report.shadow_candidate_cells =
                            report.shadow_candidate_cells.saturating_add(1);
                        report.shadow_fallback_cells =
                            report.shadow_fallback_cells.saturating_add(1);
                        Self::record_shadow_fallback_reason(
                            &mut report,
                            PlacementFallbackReason::UnsupportedShapeOrGaps,
                            1,
                        );
                        continue;
                    }

                    let placement = CellRef::new(
                        sheet_id,
                        Coord::from_excel(record.row, record.col, true, true),
                    );
                    let ingested = match pipeline.ingest_formula(
                        FormulaAstInput::RawArena(record.ast_id),
                        placement,
                        record.formula_text.clone(),
                    ) {
                        Ok(ingested) => ingested,
                        Err(_) => {
                            report.shadow_candidate_cells =
                                report.shadow_candidate_cells.saturating_add(1);
                            report.shadow_fallback_cells =
                                report.shadow_fallback_cells.saturating_add(1);
                            Self::record_shadow_fallback_reason(
                                &mut report,
                                PlacementFallbackReason::UnsupportedCanonicalTemplate,
                                1,
                            );
                            continue;
                        }
                    };
                    let candidate = FormulaPlacementCandidate::new(
                        sheet_id,
                        record.row - 1,
                        record.col - 1,
                        ingested.ast_id,
                        record.formula_text.clone(),
                    );
                    let analysis = match CandidateAnalysis::from_ingested(&candidate, &ingested) {
                        Ok(analysis) => analysis,
                        Err(reason) => {
                            report.shadow_candidate_cells =
                                report.shadow_candidate_cells.saturating_add(1);
                            report.shadow_fallback_cells =
                                report.shadow_fallback_cells.saturating_add(1);
                            Self::record_shadow_fallback_reason(&mut report, reason, 1);
                            continue;
                        }
                    };
                    groups
                        .entry((
                            sheet_id,
                            ingested.parameterized_canonical_hash,
                            candidate.col,
                        ))
                        .or_default()
                        .push((candidate, analysis));
                }
            }
        }

        let mut scratch_plane = FormulaPlane::default();
        for entries in groups.into_values() {
            let (candidates, analyses): (Vec<_>, Vec<_>) = entries.into_iter().unzip();
            for (component, component_analyses) in
                Self::split_candidate_components_with_analyses(candidates, analyses)
            {
                let placement_report = place_candidate_family_with_analyses(
                    &mut scratch_plane,
                    component,
                    component_analyses,
                );
                let counters = placement_report.counters;
                report.shadow_candidate_cells = report
                    .shadow_candidate_cells
                    .saturating_add(counters.formula_cells_seen);
                report.shadow_accepted_span_cells = report
                    .shadow_accepted_span_cells
                    .saturating_add(counters.accepted_span_cells);
                report.shadow_fallback_cells = report
                    .shadow_fallback_cells
                    .saturating_add(counters.legacy_cells);
                report.shadow_templates_interned = report
                    .shadow_templates_interned
                    .saturating_add(counters.templates_interned);
                report.shadow_spans_created = report
                    .shadow_spans_created
                    .saturating_add(counters.spans_created);
                report.graph_formula_vertices_avoided_shadow = report
                    .graph_formula_vertices_avoided_shadow
                    .saturating_add(counters.formula_vertices_avoided);
                report.ast_roots_avoided_shadow = report
                    .ast_roots_avoided_shadow
                    .saturating_add(counters.ast_roots_avoided);
                report.edge_rows_avoided_shadow = report
                    .edge_rows_avoided_shadow
                    .saturating_add(counters.edge_rows_avoided);
                for (reason, count) in counters.fallback_reasons {
                    Self::record_shadow_fallback_reason(&mut report, reason, count);
                }
            }
        }
        report
    }

    fn record_shadow_fallback_reason(
        report: &mut FormulaIngestReport,
        reason: PlacementFallbackReason,
        count: u64,
    ) {
        *report
            .fallback_reasons
            .entry(format!("{reason:?}"))
            .or_default() += count;
    }

    fn analyze_formula_plane_authoritative_ingest(
        &mut self,
        batches: &[FormulaIngestBatch],
    ) -> (
        FormulaIngestReport,
        Vec<FormulaIngestBatch>,
        PlannedFormulaMaterialize,
    ) {
        let existing_span_refs = self
            .graph
            .formula_authority()
            .active_span_refs()
            .into_iter()
            .collect::<rustc_hash::FxHashSet<_>>();
        let mut report =
            FormulaIngestReport::with_mode(FormulaPlaneMode::AuthoritativeExperimental);
        report.formula_cells_seen = batches.iter().map(|batch| batch.len() as u64).sum();

        let mut pending_candidates: Vec<(String, FormulaPlacementCandidate)> = Vec::new();
        let mut fallback: BTreeMap<String, Vec<FormulaIngestRecord>> = BTreeMap::new();
        let mut planned_fallback: PlannedFormulaMaterialize = BTreeMap::new();

        for batch in batches {
            let sheet_id = self.graph.sheet_id_mut(&batch.sheet_name);
            for record in &batch.formulas {
                if record.row == 0 || record.col == 0 {
                    report.shadow_candidate_cells = report.shadow_candidate_cells.saturating_add(1);
                    report.shadow_fallback_cells = report.shadow_fallback_cells.saturating_add(1);
                    Self::record_shadow_fallback_reason(
                        &mut report,
                        PlacementFallbackReason::UnsupportedShapeOrGaps,
                        1,
                    );
                    fallback
                        .entry(batch.sheet_name.clone())
                        .or_default()
                        .push(record.clone());
                    continue;
                }

                pending_candidates.push((
                    batch.sheet_name.clone(),
                    FormulaPlacementCandidate::new(
                        sheet_id,
                        record.row - 1,
                        record.col - 1,
                        record.ast_id,
                        record.formula_text.clone(),
                    ),
                ));
            }
        }

        let mut groups: BTreeMap<(SheetId, u64, u32), Vec<usize>> = BTreeMap::new();
        let mut analyses_by_index: Vec<Option<CandidateAnalysis>> =
            (0..pending_candidates.len()).map(|_| None).collect();
        let mut plans_by_index: Vec<Option<DependencyPlanRow>> =
            (0..pending_candidates.len()).map(|_| None).collect();
        {
            let mut pipeline = self.ingest_pipeline();
            for (idx, (sheet_name, candidate)) in pending_candidates.iter_mut().enumerate() {
                let placement = CellRef::new(
                    candidate.sheet_id,
                    Coord::from_excel(
                        candidate.row.saturating_add(1),
                        candidate.col.saturating_add(1),
                        true,
                        true,
                    ),
                );
                let ingested = pipeline.ingest_formula(
                    FormulaAstInput::RawArena(candidate.ast_id),
                    placement,
                    candidate.formula_text.clone(),
                );
                match ingested {
                    Ok(ingested) => {
                        candidate.ast_id = ingested.ast_id;
                        let dep_plan = ingested.dep_plan.clone();
                        match CandidateAnalysis::from_ingested(candidate, &ingested) {
                            Ok(analysis) => {
                                analyses_by_index[idx] = Some(analysis);
                                plans_by_index[idx] = Some(dep_plan);
                            }
                            Err(reason) => {
                                report.shadow_candidate_cells =
                                    report.shadow_candidate_cells.saturating_add(1);
                                report.shadow_fallback_cells =
                                    report.shadow_fallback_cells.saturating_add(1);
                                Self::record_shadow_fallback_reason(&mut report, reason, 1);
                                planned_fallback
                                    .entry(sheet_name.clone())
                                    .or_default()
                                    .push((
                                        candidate.row.saturating_add(1),
                                        candidate.col.saturating_add(1),
                                        candidate.ast_id,
                                        dep_plan,
                                    ));
                            }
                        }
                    }
                    Err(_) => {
                        let reason = PlacementFallbackReason::UnsupportedCanonicalTemplate;
                        report.shadow_candidate_cells =
                            report.shadow_candidate_cells.saturating_add(1);
                        report.shadow_fallback_cells =
                            report.shadow_fallback_cells.saturating_add(1);
                        Self::record_shadow_fallback_reason(&mut report, reason, 1);
                        fallback.entry(sheet_name.clone()).or_default().push(
                            FormulaIngestRecord::new(
                                candidate.row.saturating_add(1),
                                candidate.col.saturating_add(1),
                                candidate.ast_id,
                                candidate.formula_text.clone(),
                            ),
                        );
                    }
                }
            }
        }

        for (idx, (_, candidate)) in pending_candidates.iter().enumerate() {
            if analyses_by_index[idx].is_none() {
                continue;
            }
            let canonical_hash = analyses_by_index[idx]
                .as_ref()
                .expect("remaining candidate has an analysis")
                .parameterized_canonical_hash();
            groups
                .entry((candidate.sheet_id, canonical_hash, candidate.col))
                .or_default()
                .push(idx);
        }

        for ((_sheet_id, _canonical_hash, _col), candidate_indices) in groups {
            let sheet_name = pending_candidates[candidate_indices[0]].0.clone();
            let mut plans_by_coord: BTreeMap<(u32, u32), Vec<DependencyPlanRow>> = BTreeMap::new();
            for idx in &candidate_indices {
                // Each candidate index belongs to exactly one group, so the
                // plan row can be moved out instead of deep-cloned.
                if let Some(plan) = plans_by_index[*idx].take() {
                    let candidate = &pending_candidates[*idx].1;
                    plans_by_coord
                        .entry((candidate.row, candidate.col))
                        .or_default()
                        .push(plan);
                }
            }
            let candidates: Vec<_> = candidate_indices
                .iter()
                .map(|idx| pending_candidates[*idx].1.clone())
                .collect();
            let components = Self::split_shadow_candidate_components(candidates);
            let analyzed_components =
                if components.len() == 1 && components[0].len() == candidate_indices.len() {
                    let component = components.into_iter().next().expect("one component");
                    let component_analyses = candidate_indices
                        .iter()
                        .map(|idx| {
                            analyses_by_index[*idx]
                                .take()
                                .expect("candidate analysis must be used once")
                        })
                        .collect();
                    vec![(component, component_analyses)]
                } else {
                    let mut indices_by_coord: BTreeMap<(u32, u32), Vec<usize>> = BTreeMap::new();
                    for idx in candidate_indices.iter().rev() {
                        let candidate = &pending_candidates[*idx].1;
                        indices_by_coord
                            .entry((candidate.row, candidate.col))
                            .or_default()
                            .push(*idx);
                    }

                    components
                        .into_iter()
                        .map(|component| {
                            let mut component_analyses = Vec::with_capacity(component.len());
                            for candidate in &component {
                                let idx = indices_by_coord
                                    .get_mut(&(candidate.row, candidate.col))
                                    .and_then(Vec::pop)
                                    .expect("component candidate must have a precomputed analysis");
                                component_analyses.push(
                                    analyses_by_index[idx]
                                        .take()
                                        .expect("candidate analysis must be used once"),
                                );
                            }
                            (component, component_analyses)
                        })
                        .collect()
                };

            for (component, component_analyses) in analyzed_components {
                for (component, component_analyses) in
                    split_candidate_affine_literal_runs(component, component_analyses)
                {
                    let placement_report = {
                        let authority = self.graph.formula_authority_mut();
                        place_candidate_family_with_analyses(
                            &mut authority.plane,
                            component.clone(),
                            component_analyses,
                        )
                    };
                    Self::accumulate_formula_plane_placement_report(&mut report, &placement_report);

                    // Index candidates by placement once per component. The
                    // previous per-result linear `find` made this fallback
                    // mapping O(N²) for rejected families (e.g. an N-cell
                    // chain rejected with `InternalDependency`), dominating
                    // first-eval ingest cost on large rejected families.
                    // First insert wins, matching the old `Iterator::find`
                    // semantics for duplicate placements.
                    let mut candidate_by_placement: FxHashMap<
                        crate::formula_plane::runtime::PlacementCoord,
                        &FormulaPlacementCandidate,
                    > = FxHashMap::with_capacity_and_hasher(component.len(), Default::default());
                    for candidate in &component {
                        candidate_by_placement
                            .entry(candidate.placement())
                            .or_insert(candidate);
                    }
                    for result in &placement_report.results {
                        let FormulaPlacementResult::Legacy { placement, .. } = result else {
                            continue;
                        };
                        if let Some(&candidate) = candidate_by_placement.get(placement) {
                            let plan = plans_by_coord
                                .get_mut(&(candidate.row, candidate.col))
                                .and_then(Vec::pop);
                            if let Some(plan) = plan {
                                planned_fallback
                                    .entry(sheet_name.clone())
                                    .or_default()
                                    .push((
                                        candidate.row.saturating_add(1),
                                        candidate.col.saturating_add(1),
                                        candidate.ast_id,
                                        plan,
                                    ));
                            } else {
                                fallback.entry(sheet_name.clone()).or_default().push(
                                    FormulaIngestRecord::new(
                                        candidate.row.saturating_add(1),
                                        candidate.col.saturating_add(1),
                                        candidate.ast_id,
                                        candidate.formula_text.clone(),
                                    ),
                                );
                            }
                        }
                    }
                }
            }
        }

        let _index_report = self.graph.formula_authority_mut().rebuild_indexes();
        let new_span_refs = self
            .graph
            .formula_authority()
            .active_span_refs()
            .into_iter()
            .filter(|span_ref| !existing_span_refs.contains(span_ref))
            .collect::<Vec<_>>();
        self.graph
            .mark_formula_spans_dirty(new_span_refs, WholeSpanDirtyReason::NewSpan);

        let fallback_batches = fallback
            .into_iter()
            .map(|(sheet_name, formulas)| FormulaIngestBatch::new(sheet_name, formulas))
            .collect();
        (report, fallback_batches, planned_fallback)
    }

    fn accumulate_formula_plane_placement_report(
        report: &mut FormulaIngestReport,
        placement_report: &crate::formula_plane::placement::FormulaPlacementReport,
    ) {
        let counters = &placement_report.counters;
        report.shadow_candidate_cells = report
            .shadow_candidate_cells
            .saturating_add(counters.formula_cells_seen);
        report.shadow_accepted_span_cells = report
            .shadow_accepted_span_cells
            .saturating_add(counters.accepted_span_cells);
        report.shadow_fallback_cells = report
            .shadow_fallback_cells
            .saturating_add(counters.legacy_cells);
        report.shadow_templates_interned = report
            .shadow_templates_interned
            .saturating_add(counters.templates_interned);
        report.shadow_spans_created = report
            .shadow_spans_created
            .saturating_add(counters.spans_created);
        report.graph_formula_vertices_avoided_shadow = report
            .graph_formula_vertices_avoided_shadow
            .saturating_add(counters.formula_vertices_avoided);
        report.ast_roots_avoided_shadow = report
            .ast_roots_avoided_shadow
            .saturating_add(counters.ast_roots_avoided);
        report.edge_rows_avoided_shadow = report
            .edge_rows_avoided_shadow
            .saturating_add(counters.edge_rows_avoided);
        for (reason, count) in &counters.fallback_reasons {
            Self::record_shadow_fallback_reason(report, *reason, *count);
        }
    }

    fn split_candidate_components_with_analyses(
        candidates: Vec<FormulaPlacementCandidate>,
        mut analyses: Vec<CandidateAnalysis>,
    ) -> Vec<(Vec<FormulaPlacementCandidate>, Vec<CandidateAnalysis>)> {
        let components = Self::split_shadow_candidate_components(candidates.clone());
        let mut analysis_by_coord: BTreeMap<(u32, u32), Vec<CandidateAnalysis>> = BTreeMap::new();
        for (candidate, analysis) in candidates.into_iter().zip(analyses.drain(..)) {
            analysis_by_coord
                .entry((candidate.row, candidate.col))
                .or_default()
                .push(analysis);
        }
        components
            .into_iter()
            .flat_map(|component| {
                let mut component_analyses = Vec::with_capacity(component.len());
                for candidate in &component {
                    let analysis = analysis_by_coord
                        .get_mut(&(candidate.row, candidate.col))
                        .and_then(Vec::pop)
                        .expect("component candidate must have a precomputed analysis");
                    component_analyses.push(analysis);
                }
                split_candidate_affine_literal_runs(component, component_analyses)
            })
            .collect()
    }

    fn split_shadow_candidate_components(
        candidates: Vec<FormulaPlacementCandidate>,
    ) -> Vec<Vec<FormulaPlacementCandidate>> {
        if candidates.len() <= 1 {
            return vec![candidates];
        }

        // Fast path: candidates already ordered as one contiguous
        // single-column (or single-row) run form exactly one 4-connected
        // component in their existing (row, col) order; skip the BFS.
        let is_row_run = candidates.windows(2).all(|w| {
            w[0].sheet_id == w[1].sheet_id && w[0].col == w[1].col && w[0].row + 1 == w[1].row
        });
        let is_col_run = candidates.windows(2).all(|w| {
            w[0].sheet_id == w[1].sheet_id && w[0].row == w[1].row && w[0].col + 1 == w[1].col
        });
        if is_row_run || is_col_run {
            return vec![candidates];
        }

        let mut coord_to_indices: BTreeMap<(u32, u32), Vec<usize>> = BTreeMap::new();
        for (idx, candidate) in candidates.iter().enumerate() {
            coord_to_indices
                .entry((candidate.row, candidate.col))
                .or_default()
                .push(idx);
        }

        let mut remaining: BTreeSet<usize> = (0..candidates.len()).collect();
        let mut components = Vec::new();
        while let Some(&start) = remaining.iter().next() {
            remaining.remove(&start);
            let mut queue = VecDeque::from([start]);
            let mut component_indices = Vec::new();

            while let Some(idx) = queue.pop_front() {
                component_indices.push(idx);
                let candidate = &candidates[idx];
                let mut neighbor_coords = Vec::with_capacity(5);
                neighbor_coords.push((candidate.row, candidate.col));
                if let Some(row) = candidate.row.checked_sub(1) {
                    neighbor_coords.push((row, candidate.col));
                }
                neighbor_coords.push((candidate.row.saturating_add(1), candidate.col));
                if let Some(col) = candidate.col.checked_sub(1) {
                    neighbor_coords.push((candidate.row, col));
                }
                neighbor_coords.push((candidate.row, candidate.col.saturating_add(1)));

                for coord in neighbor_coords {
                    if let Some(indices) = coord_to_indices.get(&coord) {
                        for &neighbor in indices {
                            if remaining.remove(&neighbor) {
                                queue.push_back(neighbor);
                            }
                        }
                    }
                }
            }

            component_indices.sort_by_key(|idx| {
                let candidate = &candidates[*idx];
                (candidate.row, candidate.col, *idx)
            });
            components.push(
                component_indices
                    .into_iter()
                    .map(|idx| candidates[idx].clone())
                    .collect(),
            );
        }

        components
    }

    fn collect_planning_function_requests(
        ast: &ASTNode,
        requests: &mut Vec<(String, String, usize)>,
    ) {
        match &ast.node_type {
            ASTNodeType::Function { name, args } => {
                requests.push((String::new(), name.clone(), args.len()));
                for arg in args {
                    Self::collect_planning_function_requests(arg, requests);
                }
            }
            ASTNodeType::BinaryOp { left, right, .. } => {
                Self::collect_planning_function_requests(left, requests);
                Self::collect_planning_function_requests(right, requests);
            }
            ASTNodeType::UnaryOp { expr, .. } => {
                Self::collect_planning_function_requests(expr, requests);
            }
            ASTNodeType::Call { callee, args } => {
                Self::collect_planning_function_requests(callee, requests);
                for arg in args {
                    Self::collect_planning_function_requests(arg, requests);
                }
            }
            ASTNodeType::Array(rows) => {
                for cell in rows.iter().flatten() {
                    Self::collect_planning_function_requests(cell, requests);
                }
            }
            ASTNodeType::Literal(_) | ASTNodeType::Omitted | ASTNodeType::Reference { .. } => {}
        }
    }

    fn prepared_placement_function_semantics_changed(
        &self,
        semantic_epoch: u64,
        prepared: &crate::formula_plane::placement::PreparedAnchorOncePlacement,
        guard: &crate::function_registry::SemanticEpochReadGuard,
    ) -> bool {
        if semantic_epoch == guard.epoch() {
            return false;
        }
        let (_, _, _, ast_id, _, _) = prepared.ownership_proof();
        let Some(ast) = self
            .graph
            .data_store()
            .reconstruct_ast_node(ast_id, self.graph.sheet_reg())
        else {
            // Missing planning evidence must never turn a semantic change into reuse.
            return true;
        };
        let mut requests = Vec::new();
        Self::collect_planning_function_requests(&ast, &mut requests);
        guard.semantic_changes_affect_requests_since(semantic_epoch, requests)
    }

    fn prepared_function_semantics_changed(
        &self,
        preparation: &crate::engine::FormulaCompressedPreparation,
        guard: &crate::function_registry::SemanticEpochReadGuard,
    ) -> bool {
        if preparation.function_semantic_epoch == guard.epoch() {
            return false;
        }

        let mut requests = Vec::new();
        for (_, _, prepared) in &preparation.prepared {
            let (_, _, _, ast_id, _, _) = prepared.ownership_proof();
            let Some(ast) = self
                .graph
                .data_store()
                .reconstruct_ast_node(ast_id, self.graph.sheet_reg())
            else {
                return true;
            };
            Self::collect_planning_function_requests(&ast, &mut requests);
        }
        guard.semantic_changes_affect_requests_since(preparation.function_semantic_epoch, requests)
    }

    pub(crate) fn prepare_source_formula_families(
        &mut self,
        sheet_name: &str,
        families: &[crate::engine::SourceFormulaFamily],
    ) -> crate::engine::FormulaCompressedPreparation {
        let mut preparation = crate::engine::FormulaCompressedPreparation {
            engine_token: Arc::clone(&self.source_formula_token),
            function_semantic_epoch: crate::function_registry::semantic_epoch(),
            function_provider_revision: None,
            function_semantics_used: false,
            sheet_name: Arc::from(sheet_name),
            prepared: Vec::new(),
            rejected: BTreeMap::new(),
            fragmented: Vec::new(),
            fragmented_sources: BTreeMap::new(),
            eager_replay: Vec::new(),
            preparation_spool_replays: 0,
            clean_rejected_anchor_counts: [0; 3],
            fragmented_rejected_anchor_counts: [0; 3],
            exact_replay: None,
            replay_disposition: crate::engine::FormulaReplayDisposition::default(),
        };
        if self.config.formula_plane_mode != FormulaPlaneMode::AuthoritativeExperimental {
            return preparation;
        }

        let mut requests = Vec::new();
        for family in families {
            let formula = if family.anchor_text.starts_with('=') {
                family.anchor_text.to_string()
            } else {
                format!("={}", family.anchor_text)
            };
            if let Ok(ast) = formualizer_parse::parser::parse(&formula) {
                Self::collect_planning_function_requests(&ast, &mut requests);
            }
        }
        requests.sort();
        requests.dedup();
        let snapshot =
            match crate::function_registry::RegistryPlanningSnapshot::capture_for_requests(
                &self.resolver,
                requests,
            ) {
                Ok(snapshot) => snapshot,
                Err(error) => {
                    let reason = match error {
                        crate::function_registry::PlanningSnapshotError::RegistryChangedDuringCapture => {
                            "FunctionSemanticSnapshotUnavailable"
                        }
                        crate::function_registry::PlanningSnapshotError::ProviderRevisionUnavailable => {
                            "FunctionProviderRevisionUnavailable"
                        }
                    };
                    for family in families {
                        preparation
                            .rejected
                            .insert(family.source_id, reason.to_string());
                    }
                    return preparation;
                }
            };
        preparation.function_semantic_epoch = snapshot.epoch();
        preparation.function_provider_revision = snapshot.provider_revision();

        let sheet_id = self.graph.sheet_id_mut(sheet_name);
        for family in families {
            #[cfg(test)]
            let force_replay = self.force_source_family_fallback
                || cfg!(feature = "benchmark_internal")
                    && std::env::var_os("FORMUALIZER_BENCH_FORCE_FORMULA_FAMILY_REPLAY").is_some();
            #[cfg(all(feature = "benchmark_internal", not(test)))]
            let force_replay =
                std::env::var_os("FORMUALIZER_BENCH_FORCE_FORMULA_FAMILY_REPLAY").is_some();
            #[cfg(any(test, feature = "benchmark_internal"))]
            if force_replay {
                preparation
                    .rejected
                    .insert(family.source_id, "ForcedReplay".to_string());
                continue;
            }
            match self.prepare_source_formula_family(sheet_id, family, true, Some(&snapshot)) {
                Ok((prepared, function_semantics_used)) => {
                    preparation.function_semantics_used |= function_semantics_used;
                    preparation
                        .replay_disposition
                        .set_family_direct(family.source_id);
                    preparation
                        .prepared
                        .push((family.source_id, family.source_order, prepared));
                }
                Err(error) => {
                    preparation.clean_rejected_anchor_counts[0] = preparation
                        .clean_rejected_anchor_counts[0]
                        .saturating_add(u64::from(error.parse_attempted));
                    preparation.clean_rejected_anchor_counts[1] = preparation
                        .clean_rejected_anchor_counts[1]
                        .saturating_add(u64::from(error.ast_created));
                    preparation.clean_rejected_anchor_counts[2] = preparation
                        .clean_rejected_anchor_counts[2]
                        .saturating_add(u64::from(error.analysis_created));
                    preparation.rejected.insert(family.source_id, error.reason);
                }
            }
        }
        preparation
    }

    fn prepare_source_formula_proposals(
        &mut self,
        sheet_name: &str,
        families: &[crate::engine::SourceFormulaFamily],
        authority_partitions: &[crate::engine::PartitionedSourceFormulaFamily],
        replay_partitions: &[crate::engine::PartitionedSourceFormulaFamily],
        formula_record_count: u64,
        replay: Arc<std::sync::Mutex<Box<dyn crate::engine::DeferredFormulaReplay>>>,
        suppressed: &BTreeSet<(u32, u32)>,
    ) -> Result<crate::engine::FormulaCompressedPreparation, ExcelError> {
        let mut preparation = self.prepare_source_formula_families(sheet_name, families);
        preparation.exact_replay = Some(Arc::clone(&replay));
        preparation
            .replay_disposition
            .extend_suppressed_excel_coords(suppressed.iter().copied());
        if self.config.formula_plane_mode != FormulaPlaneMode::AuthoritativeExperimental {
            return Ok(preparation);
        }
        #[cfg(feature = "benchmark_internal")]
        let benchmark_forced_replay =
            std::env::var_os("FORMUALIZER_BENCH_FORCE_FORMULA_FAMILY_REPLAY").is_some();
        #[cfg(not(feature = "benchmark_internal"))]
        let benchmark_forced_replay = false;
        let authority_partitions = if benchmark_forced_replay {
            for partition in authority_partitions {
                preparation
                    .rejected
                    .insert(partition.source_id, "ForcedReplay".to_string());
            }
            &[][..]
        } else {
            authority_partitions
        };
        let authority_ids: BTreeSet<_> = authority_partitions
            .iter()
            .map(|partition| partition.source_id)
            .collect();
        for partition in replay_partitions {
            if !authority_ids.contains(&partition.source_id) {
                preparation
                    .replay_disposition
                    .register_partition(partition, false)
                    .map_err(|reason| {
                        ExcelError::new(ExcelErrorKind::Value).with_message(reason)
                    })?;
            }
        }
        if replay_partitions.is_empty()
            && preparation.rejected.is_empty()
            && preparation.direct_cell_count() == formula_record_count
        {
            return Ok(preparation);
        }

        let mut analyzed = Vec::new();
        for source in authority_partitions {
            preparation
                .fragmented_sources
                .insert(source.source_id, source.clone());
            match self.analyze_partitioned_source_family_for_transaction(sheet_name, source) {
                Ok(prepared) => {
                    let mut candidate = preparation.replay_disposition.clone();
                    match candidate.register_partition(source, true) {
                        Ok(()) => {
                            preparation.replay_disposition = candidate;
                            analyzed.push((source.clone(), prepared));
                        }
                        Err(reason) => {
                            preparation
                                .rejected
                                .insert(source.source_id, reason.to_string());
                            preparation
                                .replay_disposition
                                .register_partition(source, false)
                                .map_err(|reason| {
                                    ExcelError::new(ExcelErrorKind::Value).with_message(reason)
                                })?;
                        }
                    }
                }
                Err(error) => {
                    preparation.fragmented_rejected_anchor_counts[0] = preparation
                        .fragmented_rejected_anchor_counts[0]
                        .saturating_add(u64::from(error.parse_attempted));
                    preparation.fragmented_rejected_anchor_counts[1] = preparation
                        .fragmented_rejected_anchor_counts[1]
                        .saturating_add(u64::from(error.ast_created));
                    preparation.fragmented_rejected_anchor_counts[2] = preparation
                        .fragmented_rejected_anchor_counts[2]
                        .saturating_add(u64::from(error.analysis_created));
                    preparation.rejected.insert(source.source_id, error.reason);
                    preparation
                        .replay_disposition
                        .register_partition(source, false)
                        .map_err(|reason| {
                            ExcelError::new(ExcelErrorKind::Value).with_message(reason)
                        })?;
                }
            }
        }

        let initial_replay = replay
            .lock()
            .map_err(|_| {
                ExcelError::new(ExcelErrorKind::Value)
                    .with_message("compressed formula exact replay lock poisoned")
            })?
            .replay_partitioned(&preparation.replay_disposition, replay_partitions)
            .map_err(|message| ExcelError::new(ExcelErrorKind::Value).with_message(message))?;
        preparation.preparation_spool_replays = 1;
        let sheet_id = self.graph.sheet_id_mut(sheet_name);
        let mut preparation_failed = false;
        for (source, prepared_family) in analyzed {
            let result = (|| {
                let expected: BTreeMap<_, _> = source
                    .legacy_members
                    .as_slice()
                    .iter()
                    .map(|member| (member.coord, member.kind))
                    .collect();
                let mut actual = BTreeMap::new();
                for record in initial_replay
                    .iter()
                    .filter(|record| record.partition_owner == Some(source.source_id))
                {
                    let coord = record
                        .row
                        .checked_sub(1)
                        .zip(record.col.checked_sub(1))
                        .map(|(row, col)| crate::engine::SourceCoord { row, col })
                        .ok_or_else(|| "ExactReplayRecordInvalidCoordinate".to_string())?;
                    let kind = match record.family {
                        Some(family) if family == source.source_id => {
                            crate::engine::PartitionLegacyMemberKind::SharedFamilyMember
                        }
                        None => crate::engine::PartitionLegacyMemberKind::OrdinaryException,
                        Some(_) => return Err("ExactReplayRecordOwnerMismatch".to_string()),
                    };
                    if actual.insert(coord, (kind, record.clone())).is_some() {
                        return Err("ExactReplayRecordDuplicate".to_string());
                    }
                }
                let actual_kinds: BTreeMap<_, _> = actual
                    .iter()
                    .map(|(coord, (kind, _))| (*coord, *kind))
                    .collect();
                if actual_kinds != expected {
                    return Err("ExactReplayLegacySetMismatch".to_string());
                }
                let mut legacy = Vec::with_capacity(source.legacy_members.len());
                for expected in source.legacy_members.as_slice() {
                    let record = actual
                        .remove(&expected.coord)
                        .map(|(_, record)| record)
                        .ok_or_else(|| "ExactReplayRecordMissing".to_string())?;
                    legacy.push(
                        self.graph
                            .analyze_fragmented_exact_replay_record(
                                &self.resolver,
                                sheet_id,
                                source.source_id,
                                *expected,
                                record,
                            )
                            .map_err(|error| format!("{error:?}"))?,
                    );
                }
                Ok::<_, String>((prepared_family, legacy))
            })();
            match result {
                Ok((prepared_family, legacy)) => preparation.fragmented.push(
                    crate::engine::formula_source::PreparedFragmentedSourceProposal {
                        source: source.clone(),
                        prepared: prepared_family,
                        legacy,
                        replay: Arc::clone(&replay),
                    },
                ),
                Err(reason) => {
                    preparation_failed = true;
                    for count in &mut preparation.fragmented_rejected_anchor_counts {
                        *count = count.saturating_add(1);
                    }
                    preparation.rejected.insert(source.source_id, reason);
                    preparation
                        .replay_disposition
                        .force_family_legacy(source.source_id);
                }
            }
        }

        preparation.eager_replay = if preparation_failed {
            preparation.preparation_spool_replays = 2;
            replay
                .lock()
                .map_err(|_| {
                    ExcelError::new(ExcelErrorKind::Value)
                        .with_message("compressed formula exact replay lock poisoned")
                })?
                .replay_partitioned(&preparation.replay_disposition, replay_partitions)
                .map_err(|message| ExcelError::new(ExcelErrorKind::Value).with_message(message))?
        } else {
            initial_replay
        };
        Ok(preparation)
    }

    fn formula_batch_from_exact_replay(
        &mut self,
        sheet_name: &str,
        replayed: impl IntoIterator<Item = crate::engine::DeferredReplayFormula>,
    ) -> Result<FormulaIngestBatch, ExcelError> {
        let mut cache = rustc_hash::FxHashMap::default();
        let mut formulas = Vec::new();
        for record in replayed {
            let key = if record.text.starts_with('=') {
                record.text
            } else {
                format!("={}", record.text)
            };
            let ast_id = if let Some(cached) = cache.get(&key) {
                *cached
            } else {
                let parsed = match formualizer_parse::parser::parse(&key) {
                    Ok(parsed) => parsed,
                    Err(error) => {
                        let Some(parsed) = self.handle_formula_parse_error(
                            sheet_name,
                            record.row,
                            record.col,
                            &key,
                            error.to_string(),
                        )?
                        else {
                            continue;
                        };
                        parsed
                    }
                };
                let ast_id = self.intern_formula_ast(&parsed);
                cache.insert(key.clone(), ast_id);
                ast_id
            };
            formulas.push(
                FormulaIngestRecord::new(record.row, record.col, ast_id, Some(Arc::from(key)))
                    .with_source_proof(record.source_order, record.family, record.partition_owner),
            );
        }
        Ok(FormulaIngestBatch::new(sheet_name.to_string(), formulas))
    }

    fn replay_prepared_families_exact_records(
        &mut self,
        preparation: &crate::engine::FormulaCompressedPreparation,
    ) -> Result<Vec<crate::engine::DeferredReplayFormula>, ExcelError> {
        let replay = preparation.exact_replay.as_ref().ok_or_else(|| {
            ExcelError::new(ExcelErrorKind::Value)
                .with_message("stale compressed preparation has no exact replay owner")
        })?;
        let direct: BTreeSet<_> = preparation
            .prepared
            .iter()
            .map(|(family, _, _)| *family)
            .collect();
        let mut replay_disposition = preparation.replay_disposition.clone();
        for family in &direct {
            replay_disposition.force_family_legacy(*family);
        }
        let replayed = replay
            .lock()
            .map_err(|_| {
                ExcelError::new(ExcelErrorKind::Value)
                    .with_message("compressed formula exact replay lock poisoned")
            })?
            .replay(&replay_disposition)
            .map_err(|message| ExcelError::new(ExcelErrorKind::Value).with_message(message))?;
        let mut records: Vec<_> = replayed
            .into_iter()
            .filter(|record| record.family.is_some_and(|family| direct.contains(&family)))
            .collect();
        records.sort_by_key(|record| record.source_order);
        let expected: u64 = preparation
            .prepared
            .iter()
            .map(|(_, _, prepared)| prepared.member_count)
            .sum();
        if records.len() as u64 != expected {
            return Err(ExcelError::new(ExcelErrorKind::Value).with_message(format!(
                "compressed formula exact replay incomplete: expected {expected}, got {}",
                records.len()
            )));
        }
        Ok(records)
    }

    fn replay_one_prepared_family_exact(
        &mut self,
        preparation: &crate::engine::FormulaCompressedPreparation,
        family: crate::engine::SourceFamilyId,
        member_count: u64,
    ) -> Result<FormulaIngestBatch, ExcelError> {
        let replay = preparation.exact_replay.as_ref().ok_or_else(|| {
            ExcelError::new(ExcelErrorKind::Value)
                .with_message("stale compressed preparation has no exact replay owner")
        })?;
        let mut replay_disposition = preparation.replay_disposition.clone();
        replay_disposition.force_family_legacy(family);
        let replayed = replay
            .lock()
            .map_err(|_| {
                ExcelError::new(ExcelErrorKind::Value)
                    .with_message("compressed formula exact replay lock poisoned")
            })?
            .replay(&replay_disposition)
            .map_err(|message| ExcelError::new(ExcelErrorKind::Value).with_message(message))?
            .into_iter()
            .filter(|record| record.family == Some(family));
        let batch =
            self.formula_batch_from_exact_replay(preparation.sheet_name.as_ref(), replayed)?;
        if batch.formulas.len() as u64 != member_count {
            return Err(ExcelError::new(ExcelErrorKind::Value).with_message(format!(
                "compressed formula exact replay incomplete: expected {member_count}, got {}",
                batch.formulas.len()
            )));
        }
        Ok(batch)
    }

    fn exact_replay_record_is_prepared_partition_legacy(
        source: &crate::engine::PartitionedSourceFormulaFamily,
        record: &crate::engine::DeferredReplayFormula,
    ) -> bool {
        if record.partition_owner != Some(source.source_id) {
            return false;
        }
        let Some(coord) = record
            .row
            .checked_sub(1)
            .zip(record.col.checked_sub(1))
            .map(|(row, col)| crate::engine::SourceCoord { row, col })
        else {
            return false;
        };
        source.legacy_members.as_slice().iter().any(|member| {
            member.coord == coord
                && match member.kind {
                    crate::engine::PartitionLegacyMemberKind::SharedFamilyMember => {
                        record.family == Some(source.source_id)
                    }
                    crate::engine::PartitionLegacyMemberKind::OrdinaryException => {
                        record.family.is_none()
                    }
                }
        })
    }

    fn validate_whole_partition_replay(
        source: &crate::engine::PartitionedSourceFormulaFamily,
        records: &[crate::engine::DeferredReplayFormula],
    ) -> Result<(), ExcelError> {
        let mut coordinates = BTreeSet::new();
        let mut shared = 0u64;
        let mut ordinary = 0u64;
        for record in records {
            let coord = record
                .row
                .checked_sub(1)
                .zip(record.col.checked_sub(1))
                .map(|(row, col)| crate::engine::SourceCoord { row, col })
                .ok_or_else(|| {
                    ExcelError::new(ExcelErrorKind::Value)
                        .with_message("whole-family replay contains an invalid coordinate")
                })?;
            if !coordinates.insert(coord) {
                return Err(ExcelError::new(ExcelErrorKind::Value)
                    .with_message("whole-family replay contains a duplicate coordinate"));
            }
            match (record.family, record.partition_owner) {
                (Some(family), Some(owner))
                    if family == source.source_id && owner == source.source_id =>
                {
                    let direct = source.fragments.iter().any(|fragment| {
                        let rect = fragment.rect();
                        coord.row >= rect.start.row
                            && coord.row <= rect.end.row
                            && coord.col >= rect.start.col
                            && coord.col <= rect.end.col
                    });
                    let legacy = source.legacy_members.as_slice().iter().any(|member| {
                        member.coord == coord
                            && member.kind
                                == crate::engine::PartitionLegacyMemberKind::SharedFamilyMember
                    });
                    if !direct && !legacy {
                        return Err(ExcelError::new(ExcelErrorKind::Value)
                            .with_message("whole-family replay contains an extra shared member"));
                    }
                    shared = shared.saturating_add(1);
                }
                (None, Some(owner)) if owner == source.source_id => {
                    if !source.legacy_members.as_slice().iter().any(|member| {
                        member.coord == coord
                            && member.kind
                                == crate::engine::PartitionLegacyMemberKind::OrdinaryException
                    }) {
                        return Err(ExcelError::new(ExcelErrorKind::Value).with_message(
                            "whole-family replay contains an extra ordinary exception",
                        ));
                    }
                    ordinary = ordinary.saturating_add(1);
                }
                _ => {
                    return Err(ExcelError::new(ExcelErrorKind::Value)
                        .with_message("whole-family replay ownership mismatch"));
                }
            }
        }
        if shared != source.surviving_member_count
            || ordinary != source.reconciliation.ordinary_exceptions
        {
            return Err(ExcelError::new(ExcelErrorKind::Value)
                .with_message("whole-family replay is incomplete"));
        }
        Ok(())
    }

    fn prepare_target_combined_legacy_graph(
        &self,
        packages: &[PreparedTargetSourcePackage],
        ordinary: &[PreparedOrdinaryStagedFormula],
    ) -> Result<(PreparedLegacyGraphPlan, usize), ExcelError> {
        let mut planned_by_coord = BTreeMap::new();
        for package in packages {
            for (row, col, ast_id, plan) in &package.legacy {
                planned_by_coord.insert((package.sheet_id, *row, *col), (*ast_id, plan.clone()));
            }
        }
        for formula in ordinary {
            if let Some((ast_id, plan)) = formula.ast_id.zip(formula.plan.clone()) {
                planned_by_coord.insert(
                    (formula.sheet_id, formula.lease.row, formula.lease.col),
                    (ast_id, plan),
                );
            }
        }
        let planned = planned_by_coord
            .into_iter()
            .map(|((sheet_id, row, col), (ast_id, plan))| (sheet_id, row, col, ast_id, plan))
            .collect::<Vec<_>>();
        let formula_count = planned.len();
        let graph = self
            .graph
            .prepare_legacy_graph_plan_multi_sheet(planned)
            .map_err(|error| {
                ExcelError::new(ExcelErrorKind::Value)
                    .with_message(format!("target graph preparation failed: {error}"))
            })?;
        Ok((graph, formula_count))
    }

    fn materialize_target_package_direct_records(
        &mut self,
        package: &mut PreparedTargetSourcePackage,
        assumptions: &crate::engine::PreparationRevision,
        planning_requests: &mut BTreeSet<(String, String, usize)>,
        deadline: Option<std::time::Instant>,
    ) -> Result<(), ExcelError> {
        let existing = package
            .legacy
            .iter()
            .map(|(row, col, _, _)| (*row, *col))
            .collect::<BTreeSet<_>>();
        let mut missing = BTreeMap::new();
        for record in &package.replay_records {
            if !existing.contains(&(record.row, record.col)) {
                missing.insert((record.row, record.col), record.clone());
            }
        }
        let batch = self.formula_batch_from_exact_replay(&package.sheet, missing.into_values())?;
        for record in batch.formulas {
            self.target_preparation_checkpoint(deadline, 1)?;
            let ast = self
                .graph
                .data_store()
                .retrieve_ast(record.ast_id, self.graph.sheet_reg())
                .ok_or_else(|| {
                    ExcelError::new(ExcelErrorKind::Value)
                        .with_message("target fallback AST is unavailable")
                })?;
            let snapshot = self.target_planning_snapshot(&ast, planning_requests)?;
            if let Some(reason) =
                Self::target_planning_snapshot_stale_reason(&snapshot, assumptions)
            {
                return Err(Self::preparation_stale(
                    reason,
                    "target fallback planning snapshot became stale during materialization",
                ));
            }
            let placement = CellRef::new(
                package.sheet_id,
                Coord::from_excel(record.row, record.col, true, true),
            );
            let ingested = self
                .graph
                .ingest_pipeline(&snapshot)
                .enable_function_semantics()
                .ingest_formula(
                    FormulaAstInput::RawArena(record.ast_id),
                    placement,
                    record.formula_text,
                )?;
            package
                .legacy
                .push((record.row, record.col, ingested.ast_id, ingested.dep_plan));
        }
        package.direct_families = 0;
        package.direct_cells = 0;
        package.direct_fragments = 0;
        package.direct_complete_families = 0;
        package.direct_complete_cells = 0;
        package.direct_partition_families = 0;
        package.direct_partition_cells = 0;
        Ok(())
    }

    fn prepare_target_source_package(
        &mut self,
        sheet: &str,
        lease: StagedPackageLease,
        deadline: Option<std::time::Instant>,
    ) -> Result<PreparedTargetSourcePackage, ExcelError> {
        let sheet_id = self.graph.sheet_id(sheet).ok_or_else(|| {
            ExcelError::new(ExcelErrorKind::Ref)
                .with_message(format!("deferred source sheet not found: {sheet}"))
        })?;
        let (
            mut source_report,
            families,
            partitions,
            replay,
            invalidated,
            suppressed,
            reconciliation_replay,
        ) = {
            let package = self
                .staged_formulas
                .get(sheet)
                .and_then(|staged| staged.deferred_package.as_ref())
                .ok_or_else(|| {
                    ExcelError::new(ExcelErrorKind::Value)
                        .with_message("staged deferred source package is unavailable")
                })?;
            if package.sheet_name != sheet {
                return Err(ExcelError::new(ExcelErrorKind::Value)
                    .with_message("deferred formula package sheet mismatch"));
            }
            (
                package.report.clone(),
                package.families.clone(),
                package.partitioned_families.clone(),
                Arc::clone(&package.replay),
                package.invalidated.clone(),
                package.suppressed.clone(),
                package.reconciliation_replay.clone(),
            )
        };

        let mut replay_disposition = crate::engine::FormulaReplayDisposition::default();
        for partition in &partitions {
            replay_disposition
                .register_partition(partition, false)
                .map_err(|reason| ExcelError::new(ExcelErrorKind::Value).with_message(reason))?;
        }
        replay_disposition.extend_suppressed_excel_coords(suppressed.iter().copied());
        self.target_preparation_checkpoint(deadline, 1)?;
        let mut replay_records = if let Some(mut records) = reconciliation_replay {
            records.retain(|record| {
                let Some((row, col)) = record.row.checked_sub(1).zip(record.col.checked_sub(1))
                else {
                    return true;
                };
                let coord = crate::engine::SourceCoord { row, col };
                let disposition = record.family.map_or_else(
                    || replay_disposition.ordinary_disposition(coord).0,
                    |family| replay_disposition.shared_disposition(family, coord),
                );
                !matches!(
                    disposition,
                    crate::engine::FormulaReplayCoordinateDisposition::Direct
                        | crate::engine::FormulaReplayCoordinateDisposition::Suppressed
                )
            });
            records
        } else {
            replay
                .lock()
                .map_err(|_| {
                    ExcelError::new(ExcelErrorKind::Value)
                        .with_message("deferred formula spool lock poisoned")
                })?
                .replay_partitioned(&replay_disposition, &partitions)
                .map_err(|message| ExcelError::new(ExcelErrorKind::Value).with_message(message))?
        };
        replay_records.sort_by_key(|record| record.source_order);
        for chunk in replay_records.chunks(256) {
            self.target_preparation_checkpoint(deadline, chunk.len() as u64)?;
        }
        if replay_records
            .windows(2)
            .any(|records| records[0].source_order == records[1].source_order)
        {
            return Err(ExcelError::new(ExcelErrorKind::Value)
                .with_message("duplicate deferred source-order proof"));
        }

        let mut disposition = replay_disposition;
        let mut ordered_placements = Vec::new();
        let mut direct_families = 0usize;
        let mut direct_cells = 0u64;
        let mut direct_fragments = 0u64;
        let mut direct_complete_families = 0u64;
        let mut direct_complete_cells = 0u64;
        let mut direct_partition_families = 0u64;
        let mut direct_partition_cells = 0u64;
        let mut anchor_parses = 0u64;
        let mut anchor_asts = 0u64;
        let mut anchor_analyses = 0u64;
        if self.config.formula_plane_mode != FormulaPlaneMode::Off {
            for family in &families {
                self.target_preparation_checkpoint(deadline, 1)?;
                if invalidated.contains(&family.source_id) {
                    continue;
                }
                match self.prepare_source_formula_family(sheet_id, family, true, None) {
                    Ok((prepared, _)) => {
                        anchor_parses = anchor_parses.saturating_add(1);
                        anchor_asts = anchor_asts.saturating_add(1);
                        anchor_analyses = anchor_analyses.saturating_add(1);
                        direct_families = direct_families.saturating_add(1);
                        direct_cells = direct_cells.saturating_add(prepared.member_count);
                        direct_complete_families = direct_complete_families.saturating_add(1);
                        direct_complete_cells =
                            direct_complete_cells.saturating_add(prepared.member_count);
                        if self.config.formula_plane_mode
                            == FormulaPlaneMode::AuthoritativeExperimental
                        {
                            disposition.set_family_direct(family.source_id);
                        }
                        ordered_placements.push((family.source_order, vec![prepared]));
                    }
                    Err(error) => {
                        anchor_parses =
                            anchor_parses.saturating_add(u64::from(error.parse_attempted));
                        anchor_asts = anchor_asts.saturating_add(u64::from(error.ast_created));
                        anchor_analyses =
                            anchor_analyses.saturating_add(u64::from(error.analysis_created));
                        *source_report
                            .fallback_reasons
                            .entry(error.reason)
                            .or_default() += 1;
                    }
                }
            }

            for source in &partitions {
                self.target_preparation_checkpoint(deadline, 1)?;
                if invalidated.contains(&source.source_id) {
                    continue;
                }
                let prepared =
                    match self.analyze_partitioned_source_family_for_transaction(sheet, source) {
                        Ok(prepared) => {
                            anchor_parses = anchor_parses.saturating_add(1);
                            anchor_asts = anchor_asts.saturating_add(1);
                            anchor_analyses = anchor_analyses.saturating_add(1);
                            prepared
                        }
                        Err(error) => {
                            anchor_parses =
                                anchor_parses.saturating_add(u64::from(error.parse_attempted));
                            anchor_asts = anchor_asts.saturating_add(u64::from(error.ast_created));
                            anchor_analyses =
                                anchor_analyses.saturating_add(u64::from(error.analysis_created));
                            *source_report
                                .fallback_reasons
                                .entry(error.reason)
                                .or_default() += 1;
                            continue;
                        }
                    };
                let fragment_regions: Vec<_> = prepared
                    .placements
                    .iter()
                    .map(|placement| Region::from_domain(placement.fragment_dependency_proof().0))
                    .collect();
                let crosses_fragment =
                    prepared
                        .placements
                        .iter()
                        .enumerate()
                        .any(|(fragment_index, placement)| {
                            placement
                                .fragment_dependency_proof()
                                .1
                                .dependencies
                                .iter()
                                .any(|dependency| {
                                    fragment_regions.iter().enumerate().any(
                                        |(candidate_index, candidate)| {
                                            candidate_index != fragment_index
                                                && dependency.read_region.intersects(candidate)
                                        },
                                    )
                                })
                        });
                let family_records = replay_records
                    .iter()
                    .filter(|record| {
                        record.family == Some(source.source_id)
                            || record.partition_owner == Some(source.source_id)
                    })
                    .cloned()
                    .collect::<Vec<_>>();
                if crosses_fragment {
                    *source_report
                        .fallback_reasons
                        .entry("CrossFragmentDependency".to_string())
                        .or_default() += 1;
                    continue;
                }
                if let Err(error) = Self::validate_whole_partition_replay(source, &family_records) {
                    *source_report
                        .fallback_reasons
                        .entry(format!("TargetPartitionReplay:{error}"))
                        .or_default() += 1;
                    continue;
                }
                if self.config.formula_plane_mode == FormulaPlaneMode::AuthoritativeExperimental {
                    let mut candidate = disposition.clone();
                    if let Err(reason) = candidate.register_partition(source, true) {
                        *source_report
                            .fallback_reasons
                            .entry(reason.to_string())
                            .or_default() += 1;
                        continue;
                    }
                    disposition = candidate;
                }
                direct_families = direct_families.saturating_add(1);
                direct_cells = direct_cells.saturating_add(prepared.direct_cells);
                direct_partition_families = direct_partition_families.saturating_add(1);
                direct_partition_cells =
                    direct_partition_cells.saturating_add(prepared.direct_cells);
                direct_fragments =
                    direct_fragments.saturating_add(prepared.placements.len() as u64);
                ordered_placements.push((source.source_order, prepared.placements));
            }
        }
        ordered_placements.sort_by_key(|(source_order, _)| *source_order);
        let placements = ordered_placements
            .into_iter()
            .flat_map(|(_, placements)| placements)
            .collect();

        Ok(PreparedTargetSourcePackage {
            sheet: sheet.to_string(),
            sheet_id,
            lease,
            source_report,
            replay_records,
            disposition,
            placements,
            legacy: Vec::new(),
            direct_families,
            direct_cells,
            direct_fragments,
            direct_complete_families,
            direct_complete_cells,
            direct_partition_families,
            direct_partition_cells,
            anchor_parses,
            anchor_asts,
            anchor_analyses,
        })
    }

    fn fallback_planning_snapshot(
        &self,
        batch: &FormulaIngestBatch,
    ) -> Result<crate::function_registry::RegistryPlanningSnapshot, ExcelError> {
        let mut requests = Vec::new();
        for formula in &batch.formulas {
            let ast = self
                .graph
                .data_store()
                .retrieve_ast(formula.ast_id, self.graph.sheet_reg())
                .ok_or_else(|| {
                    ExcelError::new(ExcelErrorKind::Value)
                        .with_message("ordered fallback AST is unavailable")
                })?;
            Self::collect_planning_function_requests(&ast, &mut requests);
        }
        requests.sort();
        requests.dedup();
        crate::function_registry::RegistryPlanningSnapshot::capture_for_requests(
            &self.resolver,
            requests,
        )
        .map_err(|error| ExcelError::new(ExcelErrorKind::Value).with_message(format!("{error:?}")))
    }

    fn prepare_legacy_batch_fallback(
        &mut self,
        batch: FormulaIngestBatch,
        function_provider: &dyn crate::traits::FunctionProvider,
    ) -> Result<
        (
            crate::engine::graph::prepared_legacy_graph::PreparedLegacyGraphPlan,
            u64,
        ),
        ExcelError,
    > {
        let formula_count = batch.formulas.len() as u64;
        let sheet_id = self.graph.sheet_id_mut(&batch.sheet_name);
        let mut planned = Vec::with_capacity(batch.formulas.len());
        for record in batch.formulas {
            let placement = CellRef::new(
                sheet_id,
                Coord::from_excel(record.row, record.col, true, true),
            );
            let ingested = self
                .graph
                .ingest_pipeline(function_provider)
                .enable_function_semantics()
                .ingest_formula(
                    FormulaAstInput::RawArena(record.ast_id),
                    placement,
                    record.formula_text,
                )
                .map_err(|error| {
                    ExcelError::new(ExcelErrorKind::Value).with_message(format!("{error:?}"))
                })?;
            planned.push((record.row, record.col, ingested.ast_id, ingested.dep_plan));
        }
        let plan = self
            .graph
            .prepare_legacy_graph_plan(sheet_id, planned)
            .map_err(|error| {
                ExcelError::new(ExcelErrorKind::Value).with_message(error.to_string())
            })?;
        Ok((plan, formula_count))
    }

    fn publish_compressed_partial_report(
        &mut self,
        report: &FormulaIngestReport,
        direct_report: &FormulaIngestReport,
    ) {
        if direct_report.source_family_promoted == 0
            && direct_report.graph_formula_cells_materialized == 0
        {
            return;
        }
        let mut published = report.clone();
        published.accumulate(direct_report);
        self.record_formula_ingest_report(published);
    }

    fn finish_compressed_formula_sources(
        &mut self,
        batches: Vec<(
            FormulaIngestBatch,
            crate::engine::FormulaCompressedSourceReport,
            crate::engine::FormulaCompressedPreparation,
        )>,
    ) -> Result<FormulaIngestReport, ExcelError> {
        self.observe_function_semantic_epoch()?;
        if batches.iter().any(|(_, _, preparation)| {
            !Arc::ptr_eq(&preparation.engine_token, &self.source_formula_token)
        }) {
            return Err(ExcelError::new(ExcelErrorKind::Value)
                .with_message("compressed source preparation belongs to another engine"));
        }
        if batches.iter().any(|(fallback, _, preparation)| {
            preparation.sheet_name.as_ref() != fallback.sheet_name
        }) {
            return Err(ExcelError::new(ExcelErrorKind::Value)
                .with_message("compressed source preparation sheet mismatch"));
        }
        let initial_guard = crate::function_registry::semantic_epoch_read_guard();
        let initial_provider_revision = self.resolver.planning_semantic_revision();
        let mut fallback_batches = Vec::with_capacity(batches.len());
        let mut stale_fallback_batches = Vec::new();
        let mut pending_preparations = Vec::new();
        for (mut fallback, mut source, mut preparation) in batches {
            for formula in fallback.formulas.drain(..) {
                let source_order = formula.source_order.ok_or_else(|| {
                    ExcelError::new(ExcelErrorKind::Value).with_message(
                        "compressed source supplied formulas without source-order proof",
                    )
                })?;
                let text = formula.formula_text.ok_or_else(|| {
                    ExcelError::new(ExcelErrorKind::Value).with_message(
                        "ordered compressed fallback formula has no exact source text",
                    )
                })?;
                preparation
                    .eager_replay
                    .push(crate::engine::DeferredReplayFormula {
                        source_order,
                        row: formula.row,
                        col: formula.col,
                        text: text.to_string(),
                        family: formula.source_family,
                        partition_owner: formula.partition_owner,
                    });
            }
            preparation
                .eager_replay
                .sort_by_key(|record| record.source_order);
            source.source_spool_replays = source
                .source_spool_replays
                .saturating_add(preparation.preparation_spool_replays);
            let stale_reason = preparation
                .function_semantics_used
                .then(|| {
                    if preparation.function_provider_revision != initial_provider_revision {
                        Some("FunctionProviderRevisionChanged")
                    } else if self.prepared_function_semantics_changed(&preparation, &initial_guard)
                    {
                        Some("FunctionSemanticEpochChanged")
                    } else {
                        None
                    }
                })
                .flatten();
            let stale_semantics = stale_reason.is_some();
            if let Some(reason) = stale_reason {
                for (family, _, _) in &preparation.prepared {
                    preparation.rejected.insert(*family, reason.to_string());
                }
            }
            for reason in preparation.rejected.values() {
                *source.fallback_reasons.entry(reason.clone()).or_default() += 1;
            }
            let clean_direct_cells: u64 = preparation
                .prepared
                .iter()
                .map(|(_, _, prepared)| prepared.member_count)
                .sum();
            let fragmented_direct_cells: u64 = preparation
                .fragmented
                .iter()
                .map(|fragment| fragment.source.surviving_member_count)
                .sum();
            let direct_cells = clean_direct_cells.saturating_add(fragmented_direct_cells);
            source.replay_families = source.families_seen.saturating_sub(
                preparation
                    .prepared
                    .len()
                    .saturating_add(preparation.fragmented.len()) as u64,
            );
            source.replay_cells = source.family_cells_seen.saturating_sub(direct_cells);
            let compressed = crate::engine::FormulaCompressedSourceBatch::new(
                fallback.sheet_name.clone(),
                source,
            );
            if stale_semantics {
                stale_fallback_batches.push((fallback, compressed));
            } else {
                fallback_batches.push((fallback, compressed));
            }
            pending_preparations.push((preparation, stale_semantics));
        }
        drop(initial_guard);

        // Build known fallback graphs first. Stale batches are forced through legacy ingest.
        let configured_mode = self.config.formula_plane_mode;
        self.config.formula_plane_mode = FormulaPlaneMode::Off;
        let stale_result =
            self.ingest_compressed_formula_source_batches_inner(stale_fallback_batches, false);
        self.config.formula_plane_mode = configured_mode;
        let mut report = stale_result?;
        report.mode = configured_mode;

        self.config.formula_plane_mode = FormulaPlaneMode::Off;
        let fallback_result =
            self.ingest_compressed_formula_source_batches_inner(fallback_batches, false);
        self.config.formula_plane_mode = configured_mode;
        match fallback_result {
            Ok(fallback_report) => report.accumulate(&fallback_report),
            Err(error) => {
                self.record_formula_ingest_report(report);
                return Err(error);
            }
        }

        let mut direct_report =
            FormulaIngestReport::with_mode(FormulaPlaneMode::AuthoritativeExperimental);
        for (preparation, _) in &pending_preparations {
            direct_report.source_anchor_parses = direct_report.source_anchor_parses.saturating_add(
                preparation.clean_rejected_anchor_counts[0]
                    .saturating_add(preparation.fragmented_rejected_anchor_counts[0]),
            );
            direct_report.source_anchor_asts = direct_report.source_anchor_asts.saturating_add(
                preparation.clean_rejected_anchor_counts[1]
                    .saturating_add(preparation.fragmented_rejected_anchor_counts[1]),
            );
            direct_report.source_anchor_analyses =
                direct_report.source_anchor_analyses.saturating_add(
                    preparation.clean_rejected_anchor_counts[2]
                        .saturating_add(preparation.fragmented_rejected_anchor_counts[2]),
                );
            let rejected_partitions: Vec<_> = preparation
                .rejected
                .keys()
                .filter_map(|source_id| preparation.fragmented_sources.get(source_id))
                .collect();
            direct_report.source_partitioned_families_rejected = direct_report
                .source_partitioned_families_rejected
                .saturating_add(rejected_partitions.len() as u64);
            direct_report.source_partition_failures = direct_report
                .source_partition_failures
                .saturating_add(rejected_partitions.len() as u64);
            direct_report.source_partition_fallback_cells = direct_report
                .source_partition_fallback_cells
                .saturating_add(
                    rejected_partitions
                        .iter()
                        .map(|source| source.surviving_member_count)
                        .sum::<u64>(),
                );
        }
        loop {
            #[cfg(any(test, feature = "test-support"))]
            if let Some(hook) = self.before_prepared_span_commit_hook.take() {
                hook();
            }
            let commit_guard = crate::function_registry::semantic_epoch_read_guard();
            let commit_provider_revision = self.resolver.planning_semantic_revision();
            let mut newly_stale = Vec::new();
            let mut current = Vec::new();
            for pending in pending_preparations.drain(..) {
                let stale_reason = pending
                    .0
                    .function_semantics_used
                    .then(|| {
                        if pending.0.function_provider_revision != commit_provider_revision {
                            Some("FunctionProviderRevisionChanged")
                        } else if self
                            .prepared_function_semantics_changed(&pending.0, &commit_guard)
                        {
                            Some("FunctionSemanticEpochChanged")
                        } else {
                            None
                        }
                    })
                    .flatten();
                if let Some(reason) = stale_reason {
                    newly_stale.push((pending, reason));
                } else {
                    current.push(pending);
                }
            }
            if !newly_stale.is_empty() {
                drop(commit_guard);
                for ((mut preparation, was_initially_stale), reason) in newly_stale {
                    for (family, _, _) in &preparation.prepared {
                        preparation.rejected.insert(*family, reason.to_string());
                    }
                    let exact = match self.replay_prepared_families_exact_records(&preparation) {
                        Ok(exact) => exact,
                        Err(error) => {
                            self.publish_compressed_partial_report(&report, &direct_report);
                            return Err(error);
                        }
                    };
                    preparation.eager_replay.extend(exact);
                    preparation
                        .eager_replay
                        .sort_by_key(|record| record.source_order);
                    direct_report.source_spool_replays =
                        direct_report.source_spool_replays.saturating_add(1);
                    if !was_initially_stale {
                        *direct_report
                            .fallback_reasons
                            .entry(reason.to_string())
                            .or_default() += preparation.prepared.len() as u64;
                    }
                    direct_report.source_family_fallback = direct_report
                        .source_family_fallback
                        .saturating_add(preparation.prepared.len() as u64);
                    direct_report.source_family_fallback_cells =
                        direct_report.source_family_fallback_cells.saturating_add(
                            preparation
                                .prepared
                                .iter()
                                .map(|(_, _, prepared)| prepared.member_count)
                                .sum(),
                        );
                    preparation.prepared.clear();
                    preparation.function_semantics_used = false;
                    if !preparation.fragmented.is_empty() || !preparation.eager_replay.is_empty() {
                        current.push((preparation, false));
                    }
                }
                pending_preparations = current;
                continue;
            }
            drop(commit_guard);

            // Preserve source order across clean and fragmented families. Every clean
            // placement uses E3's incremental append, so no global index rebuild is needed.
            enum SourceProposal {
                KnownFallback {
                    source_order: crate::engine::SourceFormulaOrder,
                    records: Vec<crate::engine::DeferredReplayFormula>,
                },
                Clean(
                    crate::engine::SourceFamilyId,
                    crate::engine::SourceFormulaOrder,
                    crate::formula_plane::placement::PreparedAnchorOncePlacement,
                ),
                Fragment(crate::engine::formula_source::PreparedFragmentedSourceProposal),
            }

            impl SourceProposal {
                fn source_order(&self) -> crate::engine::SourceFormulaOrder {
                    match self {
                        Self::KnownFallback { source_order, .. } => *source_order,
                        Self::Clean(_, source_order, _) => *source_order,
                        Self::Fragment(fragment) => fragment.source.source_order,
                    }
                }
            }

            for (mut preparation, _) in current {
                let mut proposals = Vec::with_capacity(
                    preparation
                        .prepared
                        .len()
                        .saturating_add(preparation.fragmented.len())
                        .saturating_add(preparation.eager_replay.len()),
                );
                proposals.extend(preparation.prepared.drain(..).map(
                    |(source_id, source_order, prepared)| {
                        SourceProposal::Clean(source_id, source_order, prepared)
                    },
                ));

                let accepted_fragments: BTreeMap<_, _> = preparation
                    .fragmented
                    .iter()
                    .map(|fragment| (fragment.source.source_id, &fragment.source))
                    .collect();
                let mut family_fallbacks: BTreeMap<_, Vec<_>> = BTreeMap::new();
                for record in preparation.eager_replay.drain(..).filter(|record| {
                    !record.partition_owner.is_some_and(|owner| {
                        accepted_fragments.get(&owner).is_some_and(|source| {
                            Self::exact_replay_record_is_prepared_partition_legacy(source, record)
                        })
                    })
                }) {
                    if let Some(owner) = record.partition_owner.or(record.family) {
                        family_fallbacks.entry(owner).or_default().push(record);
                    } else {
                        proposals.push(SourceProposal::KnownFallback {
                            source_order: record.source_order,
                            records: vec![record],
                        });
                    }
                }
                for (_, mut records) in family_fallbacks {
                    records.sort_by_key(|record| record.source_order);
                    if records
                        .windows(2)
                        .any(|window| window[0].source_order == window[1].source_order)
                    {
                        self.publish_compressed_partial_report(&report, &direct_report);
                        return Err(ExcelError::new(ExcelErrorKind::Value)
                            .with_message("duplicate exact-replay source-order proof"));
                    }
                    let Some(source_order) = records.first().map(|record| record.source_order)
                    else {
                        self.publish_compressed_partial_report(&report, &direct_report);
                        return Err(ExcelError::new(ExcelErrorKind::Value)
                            .with_message("empty exact-replay fallback family"));
                    };
                    proposals.push(SourceProposal::KnownFallback {
                        source_order,
                        records,
                    });
                }
                proposals.extend(
                    preparation
                        .fragmented
                        .drain(..)
                        .map(SourceProposal::Fragment),
                );
                proposals.sort_by_key(SourceProposal::source_order);
                if proposals
                    .windows(2)
                    .any(|window| window[0].source_order() == window[1].source_order())
                {
                    self.publish_compressed_partial_report(&report, &direct_report);
                    return Err(ExcelError::new(ExcelErrorKind::Value)
                        .with_message("ambiguous compressed source-order proof"));
                }

                for proposal in proposals {
                    match proposal {
                        SourceProposal::KnownFallback { records, .. } => {
                            let batch = match self.formula_batch_from_exact_replay(
                                preparation.sheet_name.as_ref(),
                                records,
                            ) {
                                Ok(batch) => batch,
                                Err(error) => {
                                    self.publish_compressed_partial_report(&report, &direct_report);
                                    return Err(error);
                                }
                            };
                            if batch.is_empty() {
                                continue;
                            }
                            let snapshot = match self.fallback_planning_snapshot(&batch) {
                                Ok(snapshot) => snapshot,
                                Err(error) => {
                                    self.publish_compressed_partial_report(&report, &direct_report);
                                    return Err(error);
                                }
                            };
                            let commit_guard =
                                crate::function_registry::semantic_epoch_read_guard();
                            let provider_revision_initial =
                                self.resolver.planning_semantic_revision();
                            if (commit_guard.epoch() != snapshot.epoch()
                                && snapshot.semantic_changes_affect_requests_since_guarded(
                                    &commit_guard,
                                    snapshot.epoch(),
                                ))
                                || snapshot.provider_revision().is_some_and(|revision| {
                                    Some(revision) != provider_revision_initial
                                })
                            {
                                drop(commit_guard);
                                self.publish_compressed_partial_report(&report, &direct_report);
                                return Err(ExcelError::new(ExcelErrorKind::Value).with_message(
                                    "ordered fallback planning snapshot became stale",
                                ));
                            }
                            let (plan, formula_count) = match self
                                .prepare_legacy_batch_fallback(batch, &snapshot)
                            {
                                Ok(plan) => plan,
                                Err(error) => {
                                    drop(commit_guard);
                                    self.publish_compressed_partial_report(&report, &direct_report);
                                    return Err(error);
                                }
                            };
                            let provider_revision_after =
                                self.resolver.planning_semantic_revision();
                            if provider_revision_after != provider_revision_initial {
                                drop(commit_guard);
                                self.publish_compressed_partial_report(&report, &direct_report);
                                return Err(ExcelError::new(ExcelErrorKind::Value).with_message(
                                    "function provider changed while preparing ordered fallback",
                                ));
                            }
                            let graph_vertices = plan.new_vertex_count();
                            let Some(graph_edges) = plan.planned_edge_count() else {
                                drop(commit_guard);
                                self.publish_compressed_partial_report(&report, &direct_report);
                                return Err(ExcelError::new(ExcelErrorKind::Value)
                                    .with_message("prepared ordered fallback size overflow"));
                            };
                            if let Err(error) = self.prepared_legacy_admission(&plan, formula_count)
                            {
                                drop(commit_guard);
                                self.publish_compressed_partial_report(&report, &direct_report);
                                return Err(error);
                            }
                            if let Err(error) =
                                self.graph.validate_prepared_legacy_graph_plan(&plan)
                            {
                                drop(commit_guard);
                                self.publish_compressed_partial_report(&report, &direct_report);
                                return Err(ExcelError::new(ExcelErrorKind::Value)
                                    .with_message(error.to_string()));
                            }
                            #[cfg(test)]
                            if let Some(hook) = self
                                .before_legacy_fallback_final_provider_sample_hook
                                .take()
                            {
                                hook();
                            }
                            let provider_revision_final =
                                self.resolver.planning_semantic_revision();
                            if provider_revision_final != provider_revision_initial {
                                drop(commit_guard);
                                self.publish_compressed_partial_report(&report, &direct_report);
                                return Err(ExcelError::new(ExcelErrorKind::Value).with_message(
                                    "function provider changed after ordered fallback validation",
                                ));
                            }
                            let graph_formulas =
                                self.graph.apply_prevalidated_legacy_graph_plan(plan);
                            direct_report.formula_cells_seen = direct_report
                                .formula_cells_seen
                                .saturating_add(formula_count);
                            direct_report.graph_formula_cells_materialized = direct_report
                                .graph_formula_cells_materialized
                                .saturating_add(graph_formulas as u64);
                            direct_report.graph_vertices_created = direct_report
                                .graph_vertices_created
                                .saturating_add(graph_vertices as u64);
                            direct_report.graph_edges_created = direct_report
                                .graph_edges_created
                                .saturating_add(graph_edges as u64);
                        }
                        SourceProposal::Clean(source_id, _, prepared) => {
                            let commit_guard =
                                crate::function_registry::semantic_epoch_read_guard();
                            let commit_provider_revision =
                                self.resolver.planning_semantic_revision();
                            let semantic_changed = preparation.function_semantics_used
                                && self.prepared_placement_function_semantics_changed(
                                    preparation.function_semantic_epoch,
                                    &prepared,
                                    &commit_guard,
                                );
                            let cells = prepared.member_count;
                            let stats = self.graph.baseline_stats();
                            self.preflight_graph_admission(
                                crate::engine::resource_ledger::GraphAdmission {
                                    final_vertices: stats.graph_vertex_count,
                                    final_edges: stats.graph_edge_count,
                                    materialization_cells: 0,
                                    added_vertices: 0,
                                    added_edges: 0,
                                },
                            )?;
                            let append = self
                                .graph
                                .formula_authority()
                                .prepare_formula_plane_append(
                                    vec![prepared],
                                    self.graph.data_store(),
                                    self.graph.sheet_reg(),
                                )
                                .map_err(|error| error.to_string())
                                .and_then(|append| {
                                    if preparation.function_semantics_used
                                        && preparation.function_provider_revision
                                            != commit_provider_revision
                                    {
                                        return Err("FunctionProviderRevisionChanged".to_string());
                                    }
                                    if preparation.function_semantics_used
                                        && self.resolver.planning_semantic_revision()
                                            != commit_provider_revision
                                    {
                                        return Err("FunctionProviderRevisionChanged".to_string());
                                    }
                                    if semantic_changed {
                                        return Err("FunctionSemanticEpochChanged".to_string());
                                    }
                                    self.graph
                                        .formula_authority()
                                        .validate_prepared_formula_plane_append(
                                            &append,
                                            self.graph.data_store(),
                                            self.graph.sheet_reg(),
                                        )
                                        .map_err(|error| error.to_string())?;
                                    Ok(append)
                                });
                            match append {
                                Ok(append) => {
                                    let placement_report = self
                                        .graph
                                        .formula_authority_mut()
                                        .apply_prevalidated_formula_plane_append(append);
                                    self.graph.mark_formula_spans_dirty(
                                        placement_report.spans.iter().copied(),
                                        WholeSpanDirtyReason::NewSpan,
                                    );
                                    direct_report.formula_cells_seen =
                                        direct_report.formula_cells_seen.saturating_add(cells);
                                    direct_report.shadow_candidate_cells =
                                        direct_report.shadow_candidate_cells.saturating_add(cells);
                                    direct_report.shadow_accepted_span_cells = direct_report
                                        .shadow_accepted_span_cells
                                        .saturating_add(cells);
                                    direct_report.shadow_templates_interned =
                                        direct_report.shadow_templates_interned.saturating_add(
                                            placement_report.work.templates_to_append as u64,
                                        );
                                    direct_report.shadow_spans_created = direct_report
                                        .shadow_spans_created
                                        .saturating_add(placement_report.spans.len() as u64);
                                    direct_report.graph_formula_vertices_avoided_shadow =
                                        direct_report
                                            .graph_formula_vertices_avoided_shadow
                                            .saturating_add(cells);
                                    direct_report.ast_roots_avoided_shadow = direct_report
                                        .ast_roots_avoided_shadow
                                        .saturating_add(cells.saturating_sub(1));
                                    direct_report.edge_rows_avoided_shadow = direct_report
                                        .edge_rows_avoided_shadow
                                        .saturating_add(cells);
                                    direct_report.source_family_promoted =
                                        direct_report.source_family_promoted.saturating_add(1);
                                    direct_report.source_family_promoted_cells = direct_report
                                        .source_family_promoted_cells
                                        .saturating_add(cells);
                                    direct_report.source_anchor_parses =
                                        direct_report.source_anchor_parses.saturating_add(1);
                                    direct_report.source_anchor_asts =
                                        direct_report.source_anchor_asts.saturating_add(1);
                                    direct_report.source_anchor_analyses =
                                        direct_report.source_anchor_analyses.saturating_add(1);
                                    let descendants = cells.saturating_sub(1);
                                    direct_report.source_descendant_strings_avoided = direct_report
                                        .source_descendant_strings_avoided
                                        .saturating_add(descendants);
                                    direct_report.source_descendant_events_avoided = direct_report
                                        .source_descendant_events_avoided
                                        .saturating_add(descendants);
                                    direct_report.source_descendant_analyses_avoided =
                                        direct_report
                                            .source_descendant_analyses_avoided
                                            .saturating_add(descendants);
                                    direct_report.source_compressed_families_prepared =
                                        direct_report
                                            .source_compressed_families_prepared
                                            .saturating_add(1);
                                    direct_report.source_compressed_cells_prepared = direct_report
                                        .source_compressed_cells_prepared
                                        .saturating_add(cells);
                                }
                                Err(error) => {
                                    drop(commit_guard);
                                    let reason = format!("CleanFormulaPlaneAppend:{error}");
                                    let batch = match self.replay_one_prepared_family_exact(
                                        &preparation,
                                        source_id,
                                        cells,
                                    ) {
                                        Ok(batch) => batch,
                                        Err(error) => {
                                            self.publish_compressed_partial_report(
                                                &report,
                                                &direct_report,
                                            );
                                            return Err(error);
                                        }
                                    };
                                    let snapshot = match self.fallback_planning_snapshot(&batch) {
                                        Ok(snapshot) => snapshot,
                                        Err(error) => {
                                            self.publish_compressed_partial_report(
                                                &report,
                                                &direct_report,
                                            );
                                            return Err(error);
                                        }
                                    };
                                    let commit_guard =
                                        crate::function_registry::semantic_epoch_read_guard();
                                    let provider_revision =
                                        self.resolver.planning_semantic_revision();
                                    if (commit_guard.epoch() != snapshot.epoch()
                                        && snapshot.semantic_changes_affect_requests_since_guarded(
                                            &commit_guard,
                                            snapshot.epoch(),
                                        ))
                                        || snapshot.provider_revision().is_some_and(|revision| {
                                            Some(revision) != provider_revision
                                        })
                                    {
                                        drop(commit_guard);
                                        self.publish_compressed_partial_report(
                                            &report,
                                            &direct_report,
                                        );
                                        return Err(ExcelError::new(ExcelErrorKind::Value)
                                            .with_message(
                                                "clean-family fallback planning snapshot became stale",
                                            ));
                                    }
                                    let (plan, formula_count) = match self
                                        .prepare_legacy_batch_fallback(batch, &snapshot)
                                    {
                                        Ok(plan) => plan,
                                        Err(error) => {
                                            drop(commit_guard);
                                            self.publish_compressed_partial_report(
                                                &report,
                                                &direct_report,
                                            );
                                            return Err(error);
                                        }
                                    };
                                    let provider_revision_after =
                                        self.resolver.planning_semantic_revision();
                                    if provider_revision_after != provider_revision {
                                        drop(commit_guard);
                                        self.publish_compressed_partial_report(
                                            &report,
                                            &direct_report,
                                        );
                                        return Err(ExcelError::new(ExcelErrorKind::Value)
                                            .with_message(
                                                "function provider changed while preparing clean-family fallback",
                                            ));
                                    }
                                    let graph_vertices = plan.new_vertex_count();
                                    let Some(graph_edges) = plan.planned_edge_count() else {
                                        drop(commit_guard);
                                        self.publish_compressed_partial_report(
                                            &report,
                                            &direct_report,
                                        );
                                        return Err(ExcelError::new(ExcelErrorKind::Value)
                                            .with_message(
                                                "prepared clean-family fallback size overflow",
                                            ));
                                    };
                                    if let Err(error) =
                                        self.prepared_legacy_admission(&plan, formula_count)
                                    {
                                        drop(commit_guard);
                                        self.publish_compressed_partial_report(
                                            &report,
                                            &direct_report,
                                        );
                                        return Err(error);
                                    }
                                    if let Err(error) =
                                        self.graph.validate_prepared_legacy_graph_plan(&plan)
                                    {
                                        drop(commit_guard);
                                        self.publish_compressed_partial_report(
                                            &report,
                                            &direct_report,
                                        );
                                        return Err(ExcelError::new(ExcelErrorKind::Value)
                                            .with_message(error.to_string()));
                                    }
                                    #[cfg(test)]
                                    if let Some(hook) = self
                                        .before_legacy_fallback_final_provider_sample_hook
                                        .take()
                                    {
                                        hook();
                                    }
                                    let provider_revision_final =
                                        self.resolver.planning_semantic_revision();
                                    if provider_revision_final != provider_revision {
                                        drop(commit_guard);
                                        self.publish_compressed_partial_report(
                                            &report,
                                            &direct_report,
                                        );
                                        return Err(ExcelError::new(ExcelErrorKind::Value)
                                            .with_message(
                                                "function provider changed after clean-family fallback validation",
                                            ));
                                    }
                                    let graph_formulas =
                                        self.graph.apply_prevalidated_legacy_graph_plan(plan);
                                    direct_report.formula_cells_seen = direct_report
                                        .formula_cells_seen
                                        .saturating_add(formula_count);
                                    direct_report.graph_formula_cells_materialized = direct_report
                                        .graph_formula_cells_materialized
                                        .saturating_add(graph_formulas as u64);
                                    direct_report.graph_vertices_created = direct_report
                                        .graph_vertices_created
                                        .saturating_add(graph_vertices as u64);
                                    direct_report.graph_edges_created = direct_report
                                        .graph_edges_created
                                        .saturating_add(graph_edges as u64);
                                    direct_report.source_spool_replays =
                                        direct_report.source_spool_replays.saturating_add(1);
                                    direct_report.source_family_fallback =
                                        direct_report.source_family_fallback.saturating_add(1);
                                    direct_report.source_family_fallback_cells = direct_report
                                        .source_family_fallback_cells
                                        .saturating_add(cells);
                                    direct_report.source_anchor_parses =
                                        direct_report.source_anchor_parses.saturating_add(1);
                                    direct_report.source_anchor_asts =
                                        direct_report.source_anchor_asts.saturating_add(1);
                                    direct_report.source_anchor_analyses =
                                        direct_report.source_anchor_analyses.saturating_add(1);
                                    *direct_report.fallback_reasons.entry(reason).or_default() += 1;
                                }
                            }
                        }
                        SourceProposal::Fragment(fragment) => {
                            let commit_guard =
                                crate::function_registry::semantic_epoch_read_guard();
                            let commit_epoch = commit_guard.epoch();
                            let commit_provider_revision =
                                self.resolver.planning_semantic_revision();
                            let source = fragment.source;
                            let source_id = source.source_id;
                            #[cfg(test)]
                            let commit_fault = self
                                .fragmented_commit_fault_for_test
                                .take()
                                .unwrap_or(
                                crate::engine::fragmented_transaction::FragmentedCommitFault::None,
                            );
                            #[cfg(not(test))]
                            let commit_fault =
                                crate::engine::fragmented_transaction::FragmentedCommitFault::None;
                            let outcome = self
                                .prepare_fragmented_source_transaction(
                                    &source,
                                    &preparation.replay_disposition,
                                    fragment.prepared,
                                    fragment.legacy,
                                )
                                .map(|transaction| {
                                    let resolver = &self.resolver;
                                    self.graph.commit_fragmented_source_transaction(
                                        transaction,
                                        &self.source_formula_token,
                                        &preparation.replay_disposition,
                                        commit_epoch,
                                        commit_provider_revision,
                                        || resolver.planning_semantic_revision(),
                                        commit_fault,
                                    )
                                });
                            let fallback_reason = match outcome {
                                Ok(crate::engine::fragmented_transaction::FragmentedCommitDecision::Committed(success)) => {
                                    let mut delta = success.report_delta;
                                    delta.mode = FormulaPlaneMode::AuthoritativeExperimental;
                                    delta.source_family_promoted = 1;
                                    delta.source_family_promoted_cells =
                                        source.surviving_member_count;
                                    delta.source_partitioned_families_seen = 0;
                                    delta.source_partition_holes = 0;
                                    delta.source_partition_ordinary_exceptions = 0;
                                    delta.source_partition_surviving_cells = 0;
                                    delta.shadow_templates_interned =
                                        success.plane.work.templates_to_append as u64;
                                    delta.shadow_spans_created = success.plane.spans.len() as u64;
                                    let descendants =
                                        source.surviving_member_count.saturating_sub(1);
                                    delta.source_descendant_strings_avoided = descendants;
                                    delta.source_descendant_events_avoided = descendants;
                                    delta.source_descendant_analyses_avoided = descendants;
                                    direct_report.accumulate(&delta);
                                    None
                                }
                                Ok(crate::engine::fragmented_transaction::FragmentedCommitDecision::ReplayWholeFamily { reason, .. }) => {
                                    Some(format!("{reason:?}"))
                                }
                                Err(error) => Some(format!("{error:?}")),
                            };
                            if let Some(reason) = fallback_reason {
                                drop(commit_guard);
                                let mut replay_disposition = preparation.replay_disposition.clone();
                                replay_disposition.force_family_legacy(source_id);
                                let replayed = (|| {
                                    let records = fragment
                                        .replay
                                        .lock()
                                        .map_err(|_| {
                                            ExcelError::new(ExcelErrorKind::Value).with_message(
                                                "compressed formula exact replay lock poisoned",
                                            )
                                        })?
                                        .replay_partitioned(
                                            &replay_disposition,
                                            std::slice::from_ref(&source),
                                        )
                                        .map_err(|message| {
                                            ExcelError::new(ExcelErrorKind::Value)
                                                .with_message(message)
                                        })?
                                        .into_iter()
                                        .filter(|record| {
                                            record.family == Some(source_id)
                                                || (record.family.is_none()
                                                    && record.partition_owner == Some(source_id))
                                        })
                                        .collect::<Vec<_>>();
                                    Self::validate_whole_partition_replay(&source, &records)?;
                                    Ok::<_, ExcelError>(records)
                                })();
                                let replayed = match replayed {
                                    Ok(replayed) => replayed,
                                    Err(error) => {
                                        self.publish_compressed_partial_report(
                                            &report,
                                            &direct_report,
                                        );
                                        return Err(error);
                                    }
                                };
                                let batch = match self.formula_batch_from_exact_replay(
                                    preparation.sheet_name.as_ref(),
                                    replayed,
                                ) {
                                    Ok(batch) => batch,
                                    Err(error) => {
                                        self.publish_compressed_partial_report(
                                            &report,
                                            &direct_report,
                                        );
                                        return Err(error);
                                    }
                                };
                                let snapshot = match self.fallback_planning_snapshot(&batch) {
                                    Ok(snapshot) => snapshot,
                                    Err(error) => {
                                        self.publish_compressed_partial_report(
                                            &report,
                                            &direct_report,
                                        );
                                        return Err(error);
                                    }
                                };
                                let commit_guard =
                                    crate::function_registry::semantic_epoch_read_guard();
                                let provider_revision = self.resolver.planning_semantic_revision();
                                if (commit_guard.epoch() != snapshot.epoch()
                                    && snapshot.semantic_changes_affect_requests_since_guarded(
                                        &commit_guard,
                                        snapshot.epoch(),
                                    ))
                                    || snapshot
                                        .provider_revision()
                                        .is_some_and(|revision| Some(revision) != provider_revision)
                                {
                                    self.publish_compressed_partial_report(&report, &direct_report);
                                    return Err(ExcelError::new(ExcelErrorKind::Value).with_message(
                                        format!(
                                            "whole-family fallback planning snapshot became stale: epoch {} != {}, provider {:?} != {:?}",
                                            snapshot.epoch(),
                                            commit_guard.epoch(),
                                            snapshot.provider_revision(),
                                            provider_revision,
                                        ),
                                    ));
                                }
                                let (plan, formula_count) =
                                    match self.prepare_legacy_batch_fallback(batch, &snapshot) {
                                        Ok(plan) => plan,
                                        Err(error) => {
                                            drop(commit_guard);
                                            self.publish_compressed_partial_report(
                                                &report,
                                                &direct_report,
                                            );
                                            return Err(error);
                                        }
                                    };
                                let provider_revision_after =
                                    self.resolver.planning_semantic_revision();
                                if provider_revision_after != provider_revision {
                                    drop(commit_guard);
                                    self.publish_compressed_partial_report(&report, &direct_report);
                                    return Err(ExcelError::new(ExcelErrorKind::Value)
                                        .with_message(
                                            "function provider changed while preparing whole-family fallback",
                                        ));
                                }
                                let graph_vertices = plan.new_vertex_count();
                                let Some(graph_edges) = plan.planned_edge_count() else {
                                    drop(commit_guard);
                                    self.publish_compressed_partial_report(&report, &direct_report);
                                    return Err(ExcelError::new(ExcelErrorKind::Value)
                                        .with_message(
                                            "prepared whole-family fallback size overflow",
                                        ));
                                };
                                if let Err(error) =
                                    self.prepared_legacy_admission(&plan, formula_count)
                                {
                                    drop(commit_guard);
                                    self.publish_compressed_partial_report(&report, &direct_report);
                                    return Err(error);
                                }
                                if let Err(error) =
                                    self.graph.validate_prepared_legacy_graph_plan(&plan)
                                {
                                    drop(commit_guard);
                                    self.publish_compressed_partial_report(&report, &direct_report);
                                    return Err(ExcelError::new(ExcelErrorKind::Value)
                                        .with_message(error.to_string()));
                                }
                                #[cfg(test)]
                                if let Some(hook) = self
                                    .before_legacy_fallback_final_provider_sample_hook
                                    .take()
                                {
                                    hook();
                                }
                                let provider_revision_final =
                                    self.resolver.planning_semantic_revision();
                                if provider_revision_final != provider_revision {
                                    drop(commit_guard);
                                    self.publish_compressed_partial_report(&report, &direct_report);
                                    return Err(ExcelError::new(ExcelErrorKind::Value).with_message(
                                        "function provider changed after whole-family fallback validation",
                                    ));
                                }
                                let graph_formulas =
                                    self.graph.apply_prevalidated_legacy_graph_plan(plan);
                                direct_report.formula_cells_seen = direct_report
                                    .formula_cells_seen
                                    .saturating_add(formula_count);
                                direct_report.graph_formula_cells_materialized = direct_report
                                    .graph_formula_cells_materialized
                                    .saturating_add(graph_formulas as u64);
                                direct_report.graph_vertices_created = direct_report
                                    .graph_vertices_created
                                    .saturating_add(graph_vertices as u64);
                                direct_report.graph_edges_created = direct_report
                                    .graph_edges_created
                                    .saturating_add(graph_edges as u64);
                                direct_report.source_spool_replays =
                                    direct_report.source_spool_replays.saturating_add(1);
                                direct_report.source_family_fallback =
                                    direct_report.source_family_fallback.saturating_add(1);
                                direct_report.source_family_fallback_cells = direct_report
                                    .source_family_fallback_cells
                                    .saturating_add(source.surviving_member_count);
                                direct_report.source_partitioned_families_rejected = direct_report
                                    .source_partitioned_families_rejected
                                    .saturating_add(1);
                                direct_report.source_partition_failures =
                                    direct_report.source_partition_failures.saturating_add(1);
                                direct_report.source_partition_fallback_cells = direct_report
                                    .source_partition_fallback_cells
                                    .saturating_add(source.surviving_member_count);
                                direct_report.source_anchor_parses =
                                    direct_report.source_anchor_parses.saturating_add(1);
                                direct_report.source_anchor_asts =
                                    direct_report.source_anchor_asts.saturating_add(1);
                                direct_report.source_anchor_analyses =
                                    direct_report.source_anchor_analyses.saturating_add(1);
                                *direct_report.fallback_reasons.entry(reason).or_default() += 1;
                            }
                        }
                    }
                    #[cfg(test)]
                    if let Some(hook) = self.after_eager_proposal_commit_hook.take() {
                        hook();
                    }
                }
            }
            break;
        }
        report.accumulate(&direct_report);
        self.record_formula_ingest_report(report.clone());
        Ok(report)
    }
    /// Ingest replayed per-cell formulas while preserving compressed source counters.
    pub(crate) fn ingest_compressed_formula_source_batches(
        &mut self,
        batches: Vec<(
            FormulaIngestBatch,
            crate::engine::FormulaCompressedSourceBatch,
        )>,
    ) -> Result<FormulaIngestReport, ExcelError> {
        self.ingest_compressed_formula_source_batches_inner(batches, true)
    }

    fn ingest_compressed_formula_source_batches_inner(
        &mut self,
        batches: Vec<(
            FormulaIngestBatch,
            crate::engine::FormulaCompressedSourceBatch,
        )>,
        publish_report: bool,
    ) -> Result<FormulaIngestReport, ExcelError> {
        let mut source_counts = [0_u64; 11];
        let mut source_report = crate::engine::FormulaCompressedSourceReport::default();
        let mut formula_batches = Vec::with_capacity(batches.len());
        let mut compressed_families = Vec::new();
        let mut partitioned_families = Vec::new();
        for (batch, compressed_batch) in batches {
            let (sheet_name, compressed, families, partitions) = compressed_batch.into_parts();
            if sheet_name.as_ref() != batch.sheet_name {
                return Err(ExcelError::new(ExcelErrorKind::Value).with_message(
                    "compressed formula source sheet does not match its replay batch",
                ));
            }
            compressed_families.push((batch.sheet_name.clone(), families));
            partitioned_families.push((batch.sheet_name.clone(), partitions));
            source_counts[0] = source_counts[0].saturating_add(compressed.source_formula_events);
            source_counts[1] = source_counts[1].saturating_add(compressed.source_ordinary_events);
            source_counts[2] =
                source_counts[2].saturating_add(compressed.source_shared_anchor_events);
            source_counts[3] =
                source_counts[3].saturating_add(compressed.source_shared_descendant_events);
            source_counts[4] = source_counts[4].saturating_add(compressed.source_unknown_events);
            source_counts[5] =
                source_counts[5].saturating_add(compressed.source_formula_records_spooled);
            source_counts[6] =
                source_counts[6].saturating_add(compressed.source_spool_encoded_bytes);
            source_counts[7] = source_counts[7].max(compressed.source_spool_peak_memory_bytes);
            source_counts[8] =
                source_counts[8].saturating_add(compressed.source_spool_spilled_bytes);
            source_counts[9] = source_counts[9].saturating_add(compressed.source_spool_spill_files);
            source_counts[10] = source_counts[10].saturating_add(compressed.source_spool_replays);
            source_report.families_seen = source_report
                .families_seen
                .saturating_add(compressed.families_seen);
            source_report.family_cells_seen = source_report
                .family_cells_seen
                .saturating_add(compressed.family_cells_seen);
            source_report.source_clean_families = source_report
                .source_clean_families
                .saturating_add(compressed.source_clean_families);
            source_report.source_clean_cells = source_report
                .source_clean_cells
                .saturating_add(compressed.source_clean_cells);
            source_report.source_fragmentable_families = source_report
                .source_fragmentable_families
                .saturating_add(compressed.source_fragmentable_families);
            source_report.source_fragmentable_cells = source_report
                .source_fragmentable_cells
                .saturating_add(compressed.source_fragmentable_cells);
            source_report.source_fragment_count = source_report
                .source_fragment_count
                .saturating_add(compressed.source_fragment_count);
            source_report.source_isolated_fallback_cells = source_report
                .source_isolated_fallback_cells
                .saturating_add(compressed.source_isolated_fallback_cells);
            source_report.source_hole_exclusions = source_report
                .source_hole_exclusions
                .saturating_add(compressed.source_hole_exclusions);
            source_report.source_ordinary_exclusions = source_report
                .source_ordinary_exclusions
                .saturating_add(compressed.source_ordinary_exclusions);
            source_report.source_partition_failures = source_report
                .source_partition_failures
                .saturating_add(compressed.source_partition_failures);
            source_report.replay_families = source_report
                .replay_families
                .saturating_add(compressed.replay_families);
            source_report.replay_cells = source_report
                .replay_cells
                .saturating_add(compressed.replay_cells);
            source_report.forward_descendants = source_report
                .forward_descendants
                .saturating_add(compressed.forward_descendants);
            source_report.evidence_limit_fallbacks = source_report
                .evidence_limit_fallbacks
                .saturating_add(compressed.evidence_limit_fallbacks);
            source_report.evidence_peak_bytes = source_report
                .evidence_peak_bytes
                .max(compressed.evidence_peak_bytes);
            for (reason, count) in compressed.fallback_reasons {
                *source_report.fallback_reasons.entry(reason).or_default() += count;
            }
            formula_batches.push(batch);
        }
        self.ingest_formula_batches_inner(
            formula_batches,
            source_counts,
            Some(source_report),
            compressed_families,
            partitioned_families,
            publish_report,
        )
    }

    pub fn ingest_formula_batches(
        &mut self,
        batches: Vec<FormulaIngestBatch>,
    ) -> Result<FormulaIngestReport, ExcelError> {
        let has_formulas = batches.iter().any(|batch| !batch.formulas.is_empty());
        let report = self.ingest_formula_batches_inner(
            batches,
            [0; 11],
            None,
            Vec::new(),
            Vec::new(),
            true,
        )?;
        if has_formulas {
            self.mark_topology_edited();
        }
        Ok(report)
    }

    fn ingest_formula_batches_unpublished(
        &mut self,
        batches: Vec<FormulaIngestBatch>,
    ) -> Result<FormulaIngestReport, ExcelError> {
        self.ingest_formula_batches_inner(batches, [0; 11], None, Vec::new(), Vec::new(), false)
    }

    fn ingest_formula_batches_inner(
        &mut self,
        batches: Vec<FormulaIngestBatch>,
        source_counts: [u64; 11],
        source_report: Option<crate::engine::FormulaCompressedSourceReport>,
        compressed_families: Vec<(String, Vec<crate::engine::SourceFormulaFamily>)>,
        partitioned_families: Vec<(String, Vec<crate::engine::PartitionedSourceFormulaFamily>)>,
        publish_report: bool,
    ) -> Result<FormulaIngestReport, ExcelError> {
        self.observe_function_semantic_epoch()?;
        let formula_cells_seen = batches.iter().map(|batch| batch.len() as u64).sum();
        #[cfg(feature = "benchmark_internal")]
        let benchmark_forced_replay =
            std::env::var_os("FORMUALIZER_BENCH_FORCE_FORMULA_FAMILY_REPLAY").is_some();
        #[cfg(not(feature = "benchmark_internal"))]
        let benchmark_forced_replay = false;
        let (mut report, materialize_batches, planned_materialize) = if benchmark_forced_replay
            && self.config.formula_plane_mode == FormulaPlaneMode::AuthoritativeExperimental
        {
            let mut report =
                FormulaIngestReport::with_mode(FormulaPlaneMode::AuthoritativeExperimental);
            report
                .fallback_reasons
                .insert("ForcedReplay".to_string(), formula_cells_seen);
            (report, batches, BTreeMap::new())
        } else {
            match self.config.formula_plane_mode {
                FormulaPlaneMode::Off => (
                    FormulaIngestReport::with_mode(FormulaPlaneMode::Off),
                    batches,
                    BTreeMap::new(),
                ),
                FormulaPlaneMode::Shadow => (
                    if partitioned_families
                        .iter()
                        .all(|(_, families)| families.is_empty())
                    {
                        if compressed_families.is_empty() {
                            self.analyze_formula_plane_shadow_candidates(&batches)
                        } else {
                            self.analyze_compressed_formula_plane_shadow(&compressed_families)
                        }
                    } else {
                        let mut partition_report =
                            self.analyze_partitioned_formula_plane_shadow(&partitioned_families);
                        if compressed_families
                            .iter()
                            .any(|(_, families)| !families.is_empty())
                        {
                            partition_report.accumulate(
                                &self.analyze_compressed_formula_plane_shadow(&compressed_families),
                            );
                        }
                        partition_report
                    },
                    batches,
                    BTreeMap::new(),
                ),
                FormulaPlaneMode::AuthoritativeExperimental => {
                    self.analyze_formula_plane_authoritative_ingest(&batches)
                }
            }
        };
        report.formula_cells_seen = formula_cells_seen;
        report.source_formula_events = source_counts[0];
        report.source_ordinary_events = source_counts[1];
        report.source_shared_anchor_events = source_counts[2];
        report.source_shared_descendant_events = source_counts[3];
        report.source_unknown_events = source_counts[4];
        report.source_formula_records_spooled = source_counts[5];
        report.source_spool_encoded_bytes = source_counts[6];
        report.source_spool_peak_memory_bytes = source_counts[7];
        report.source_spool_spilled_bytes = source_counts[8];
        report.source_spool_spill_files = source_counts[9];
        report.source_spool_replays = source_counts[10];
        if let Some(source) = source_report {
            report.source_families_seen = source.families_seen;
            report.source_family_cells_seen = source.family_cells_seen;
            report.source_family_shadow_eligible = source.source_clean_families;
            report.source_family_shadow_eligible_cells = source.source_clean_cells;
            report.source_partitioned_families_seen = source.source_fragmentable_families;
            report.source_partition_holes = source.source_hole_exclusions;
            report.source_partition_ordinary_exceptions = source.source_ordinary_exclusions;
            report.source_partition_failures = source.source_partition_failures;
            report.source_partition_surviving_cells = source.source_fragmentable_cells;
            report.source_family_fallback = report
                .source_family_fallback
                .saturating_add(source.replay_families);
            report.source_family_fallback_cells = report
                .source_family_fallback_cells
                .saturating_add(source.replay_cells);
            report.source_forward_descendants = source.forward_descendants;
            report.source_evidence_limit_fallbacks = source.evidence_limit_fallbacks;
            report.source_evidence_peak_bytes = source.evidence_peak_bytes;
            for (reason, count) in source.fallback_reasons {
                let total = report.fallback_reasons.entry(reason).or_default();
                *total = total.saturating_add(count);
            }
        }

        if !materialize_batches.iter().all(FormulaIngestBatch::is_empty)
            || !planned_materialize.is_empty()
        {
            let mut prepared_by_sheet = planned_materialize;
            for batch in materialize_batches {
                if batch.is_empty() {
                    continue;
                }
                let sheet_id = self.graph.sheet_id(&batch.sheet_name).ok_or_else(|| {
                    ExcelError::new(ExcelErrorKind::Ref)
                        .with_message(format!("unknown ingest sheet: {}", batch.sheet_name))
                })?;
                let mut pipeline = self.ingest_pipeline();
                let ingested = pipeline.ingest_batch(batch.formulas.into_iter().map(|record| {
                    let placement = CellRef::new(
                        sheet_id,
                        Coord::from_excel(record.row, record.col, true, true),
                    );
                    (
                        FormulaAstInput::RawArena(record.ast_id),
                        placement,
                        record.formula_text,
                    )
                }))?;
                prepared_by_sheet
                    .entry(batch.sheet_name)
                    .or_default()
                    .extend(ingested.into_iter().map(|formula| {
                        (
                            formula.placement.coord.row() + 1,
                            formula.placement.coord.col() + 1,
                            formula.ast_id,
                            formula.dep_plan,
                        )
                    }));
            }
            let admission_preflighted = self.graph_admission_enabled();
            if admission_preflighted {
                let mut preview = Vec::new();
                for (sheet_name, formulas) in &prepared_by_sheet {
                    let sheet_id = self.graph.sheet_id(sheet_name).ok_or_else(|| {
                        ExcelError::new(ExcelErrorKind::Ref)
                            .with_message(format!("unknown ingest sheet: {sheet_name}"))
                    })?;
                    preview.extend(
                        formulas
                            .iter()
                            .map(|(row, col, _, plan)| (sheet_id, *row, *col, plan.clone())),
                    );
                }
                let admission = self.graph.preview_formula_mutations(&preview)?;
                self.preflight_graph_admission(admission)?;
            }

            let mut builder = self.begin_bulk_ingest();
            if admission_preflighted {
                builder.mark_admission_preflighted();
            }
            for (sheet_name, formulas) in prepared_by_sheet {
                if formulas.is_empty() {
                    continue;
                }
                let sheet_id = builder.add_sheet(&sheet_name);
                builder.add_formula_plans(sheet_id, formulas);
            }
            let summary = builder.finish()?;
            report.graph_formula_cells_materialized = summary.formulas as u64;
            report.graph_vertices_created = summary.vertices as u64;
            report.graph_edges_created = summary.edges as u64;
        }

        if publish_report {
            self.record_formula_ingest_report(report.clone());
        }
        Ok(report)
    }

    fn dedup_formula_parse_diagnostics_since(&mut self, start: usize) {
        let mut unique = Vec::new();
        for diagnostic in self.formula_parse_diagnostics.drain(start..) {
            let duplicate = unique.iter().any(|prior: &FormulaParseDiagnostic| {
                prior.sheet == diagnostic.sheet
                    && prior.row == diagnostic.row
                    && prior.col == diagnostic.col
                    && prior.formula == diagnostic.formula
                    && prior.policy == diagnostic.policy
            });
            if !duplicate {
                unique.push(diagnostic);
            }
        }
        self.formula_parse_diagnostics.extend(unique);
    }

    pub fn handle_formula_parse_error(
        &mut self,
        sheet: &str,
        row: u32,
        col: u32,
        formula: &str,
        message: String,
    ) -> Result<Option<ASTNode>, ExcelError> {
        let policy = self.config.formula_parse_policy;

        if policy == FormulaParsePolicy::Strict {
            let col_a1 = col_letters_from_1based(col).unwrap_or_else(|_| "?".to_string());
            return Err(ExcelError::new(ExcelErrorKind::Value).with_message(format!(
                "Formula parse error at {sheet}!{col_a1}{row}: {message}"
            )));
        }

        self.formula_parse_diagnostics.push(FormulaParseDiagnostic {
            sheet: sheet.to_string(),
            row,
            col,
            formula: formula.to_string(),
            message: message.clone(),
            policy,
        });

        match policy {
            FormulaParsePolicy::Strict => unreachable!(),
            FormulaParsePolicy::KeepCachedValue => Ok(None),
            FormulaParsePolicy::AsText => Ok(Some(ASTNode::new(
                ASTNodeType::Literal(LiteralValue::Text(formula.to_string())),
                None,
            ))),
            FormulaParsePolicy::CoerceToError => {
                let err = ExcelError::new(ExcelErrorKind::Error)
                    .with_message(format!("Malformed formula: {message}"));
                Ok(Some(ASTNode::new(
                    ASTNodeType::Literal(LiteralValue::Error(err)),
                    None,
                )))
            }
        }
    }

    #[cfg(test)]
    fn target_preparation_fault(
        &mut self,
        seam: crate::engine::target_preparation::TargetPreparationFault,
    ) -> Result<(), ExcelError> {
        if self.target_preparation_fault_for_test == Some(seam) {
            self.target_preparation_fault_for_test = None;
            Err(ExcelError::new(ExcelErrorKind::Value)
                .with_message(format!("injected target preparation fault: {seam:?}")))
        } else {
            Ok(())
        }
    }

    fn preparation_stale(
        reason: formualizer_common::PreparationStaleReason,
        message: impl Into<String>,
    ) -> ExcelError {
        ExcelError::new(ExcelErrorKind::Value)
            .with_message(message)
            .with_extra(formualizer_common::ExcelErrorExtra::PreparationStale { reason })
    }

    fn preparation_revision_stale_reason(
        assumptions: &crate::engine::PreparationRevision,
        current: &crate::engine::PreparationRevision,
        planning_requests: &BTreeSet<(String, String, usize)>,
        staged_leases_match: bool,
    ) -> Option<formualizer_common::PreparationStaleReason> {
        if assumptions.graph != current.graph {
            Some(formualizer_common::PreparationStaleReason::Graph)
        } else if assumptions.authority != current.authority
            || assumptions.authority_indexes != current.authority_indexes
            || assumptions.authority_indexed_plane != current.authority_indexed_plane
        {
            Some(formualizer_common::PreparationStaleReason::Authority)
        } else if assumptions.staged != current.staged || !staged_leases_match {
            Some(formualizer_common::PreparationStaleReason::Staged)
        } else if assumptions.symbols != current.symbols {
            Some(formualizer_common::PreparationStaleReason::Symbols)
        } else if assumptions.provider != current.provider {
            Some(formualizer_common::PreparationStaleReason::Provider)
        } else if assumptions.semantic != current.semantic
            && crate::function_registry::semantic_changes_affect_requests_since(
                assumptions.semantic,
                planning_requests.iter().cloned(),
            )
        {
            Some(formualizer_common::PreparationStaleReason::Semantic)
        } else {
            None
        }
    }

    fn preparation_revisions(&self) -> crate::engine::PreparationRevision {
        let (authority, authority_indexes, authority_indexed_plane) =
            self.graph.authority_revisions();
        crate::engine::PreparationRevision {
            graph: self.graph.topology_revision(),
            authority,
            authority_indexes,
            authority_indexed_plane,
            staged: self.staged_formula_index.revision(),
            symbols: self.graph.symbol_revision(),
            semantic: crate::function_registry::semantic_epoch(),
            provider: self.resolver.planning_semantic_revision(),
        }
    }

    fn planning_revision_snapshot(&self) -> PlanningRevisionSnapshot {
        let registry_guard = crate::function_registry::semantic_epoch_read_guard();
        let provider = self.resolver.planning_semantic_revision();
        let semantic = registry_guard.epoch();
        let (authority, authority_indexes, authority_indexed_plane) =
            self.graph.authority_revisions();
        let mut span_refs = self.graph.formula_authority().active_span_refs();
        span_refs.sort_unstable_by_key(|span_ref| {
            (span_ref.id.0, span_ref.generation, span_ref.version)
        });
        PlanningRevisionSnapshot {
            engine_topology_epoch: self.topology_epoch,
            graph_topology_revision: self.graph.topology_revision(),
            authority,
            authority_indexes,
            authority_indexed_plane,
            staged: self.staged_formula_index.revision(),
            symbols: self.graph.symbol_revision(),
            semantic,
            provider,
            formula_plane_mode: self.config.formula_plane_mode,
            deterministic_mode: self.config.deterministic_mode.clone(),
            budgets: self.evaluation_resource_budgets.clone(),
            span_refs,
        }
    }

    fn recalc_plan_key(&self) -> RecalcPlanKey {
        RecalcPlanKey {
            engine_token: Arc::clone(&self.recalc_plan_token),
            revisions: self.planning_revision_snapshot(),
        }
    }

    fn plan_stale(reason: formualizer_common::PlanStaleReason) -> ExcelError {
        ExcelError::new(ExcelErrorKind::Value)
            .with_message(format!("recalculation plan is stale: {}", reason.as_str()))
            .with_extra(formualizer_common::ExcelErrorExtra::PlanStale { reason })
    }

    fn validate_recalc_plan_key(&self, key: &RecalcPlanKey) -> Result<(), ExcelError> {
        use formualizer_common::PlanStaleReason;

        if !Arc::ptr_eq(&key.engine_token, &self.recalc_plan_token) {
            return Err(Self::plan_stale(PlanStaleReason::Engine));
        }

        let current = self.planning_revision_snapshot();
        let expected = &key.revisions;
        let stale = if expected.provider != current.provider {
            Some(PlanStaleReason::Provider)
        } else if expected.semantic != current.semantic {
            Some(PlanStaleReason::Semantic)
        } else if expected.budgets != current.budgets
            || expected.deterministic_mode != current.deterministic_mode
        {
            Some(PlanStaleReason::Budget)
        } else if expected.staged != current.staged {
            Some(PlanStaleReason::Staged)
        } else if expected.symbols != current.symbols {
            Some(PlanStaleReason::Symbols)
        } else if expected.formula_plane_mode != current.formula_plane_mode
            || expected.authority != current.authority
            || expected.authority_indexes != current.authority_indexes
            || expected.authority_indexed_plane != current.authority_indexed_plane
        {
            Some(PlanStaleReason::Authority)
        } else if expected.span_refs != current.span_refs {
            Some(PlanStaleReason::SpanGeneration)
        } else if expected.graph_topology_revision != current.graph_topology_revision
            || expected.engine_topology_epoch != current.engine_topology_epoch
        {
            Some(PlanStaleReason::Graph)
        } else {
            None
        };
        stale.map_or(Ok(()), |reason| Err(Self::plan_stale(reason)))
    }

    fn target_preparation_checkpoint(
        &mut self,
        deadline: Option<std::time::Instant>,
        work: u64,
    ) -> Result<(), ExcelError> {
        if self
            .active_cancel_flag
            .as_ref()
            .is_some_and(|cancel| cancel.is_cancelled())
        {
            return Err(ExcelError::new(ExcelErrorKind::Cancelled)
                .with_message("target graph preparation cancelled"));
        }
        if deadline.is_some_and(|deadline| std::time::Instant::now() >= deadline) {
            return Err(crate::engine::ResourceLedgerError::Exhausted(
                formualizer_common::ResourceExhaustionDetail {
                    reason: formualizer_common::ResourceExhaustionReason::Deadline,
                    limit: 0,
                    observed: 1,
                    request_id: self
                        .active_evaluation_resource_request
                        .as_ref()
                        .map(|stats| stats.request_id),
                },
            )
            .into_excel_error());
        }
        self.charge_bounded_work(work)
    }

    fn opaque_reason_in_ast(
        &self,
        ast: &ASTNode,
        provider: &dyn crate::traits::FunctionProvider,
    ) -> Option<crate::engine::OpaqueReason> {
        match &ast.node_type {
            ASTNodeType::Function { name, args } => {
                let canonical = name.rsplit('.').next().unwrap_or(name).to_ascii_uppercase();
                if canonical == "INDIRECT" {
                    return Some(crate::engine::OpaqueReason::RuntimeTextReference);
                }
                let Some(function) = provider.get_function_for_planning("", name) else {
                    return Some(crate::engine::OpaqueReason::UnknownFunction);
                };
                let caps = function.caps();
                if caps.contains(FnCaps::DYNAMIC_DEPENDENCY)
                    || caps.contains(FnCaps::RETURNS_REFERENCE)
                {
                    return Some(crate::engine::OpaqueReason::DynamicReference);
                }
                args.iter()
                    .find_map(|arg| self.opaque_reason_in_ast(arg, provider))
            }
            ASTNodeType::Call { .. } => Some(crate::engine::OpaqueReason::UnknownCustomFunction),
            ASTNodeType::UnaryOp { expr, .. } => self.opaque_reason_in_ast(expr, provider),
            ASTNodeType::BinaryOp { left, right, .. } => self
                .opaque_reason_in_ast(left, provider)
                .or_else(|| self.opaque_reason_in_ast(right, provider)),
            ASTNodeType::Array(rows) => rows
                .iter()
                .flat_map(|row| row.iter())
                .find_map(|item| self.opaque_reason_in_ast(item, provider)),
            ASTNodeType::Reference {
                reference:
                    ReferenceType::Cell {
                        sheet: Some(sheet), ..
                    }
                    | ReferenceType::Range {
                        sheet: Some(sheet), ..
                    },
                ..
            } if self.graph.sheet_id(sheet).is_none() => {
                Some(crate::engine::OpaqueReason::UnresolvedCrossSheetBinding)
            }
            ASTNodeType::Reference {
                reference:
                    ReferenceType::External(_)
                    | ReferenceType::Cell3D { .. }
                    | ReferenceType::Range3D { .. },
                ..
            } => Some(crate::engine::OpaqueReason::UnresolvedCrossSheetBinding),
            ASTNodeType::Literal(_) | ASTNodeType::Omitted | ASTNodeType::Reference { .. } => None,
        }
    }

    fn target_planning_snapshot(
        &mut self,
        ast: &ASTNode,
        planning_requests: &mut BTreeSet<(String, String, usize)>,
    ) -> Result<crate::function_registry::RegistryPlanningSnapshot, ExcelError> {
        #[cfg(test)]
        if std::mem::take(&mut self.inject_target_semantic_stale_once_for_test) {
            return Err(Self::preparation_stale(
                formualizer_common::PreparationStaleReason::Semantic,
                "injected target semantic preparation movement",
            ));
        }
        #[cfg(test)]
        if let Some(hook) = self.before_target_planning_snapshot_hook.take() {
            hook();
        }
        let mut requests = Vec::new();
        Self::collect_planning_function_requests(ast, &mut requests);
        requests.sort();
        requests.dedup();
        planning_requests.extend(requests.iter().cloned());
        crate::function_registry::RegistryPlanningSnapshot::capture_for_requests(
            &self.resolver,
            requests,
        )
        .map_err(|error| {
            ExcelError::new(ExcelErrorKind::Value)
                .with_message(format!("target planning snapshot unavailable: {error:?}"))
        })
    }

    fn target_planning_snapshot_stale_reason(
        snapshot: &crate::function_registry::RegistryPlanningSnapshot,
        assumptions: &crate::engine::PreparationRevision,
    ) -> Option<formualizer_common::PreparationStaleReason> {
        if snapshot
            .provider_revision()
            .is_some_and(|revision| Some(revision) != assumptions.provider)
        {
            Some(formualizer_common::PreparationStaleReason::Provider)
        } else if snapshot.epoch() != assumptions.semantic
            && snapshot.semantic_changes_affect_requests_since(assumptions.semantic)
        {
            Some(formualizer_common::PreparationStaleReason::Semantic)
        } else {
            None
        }
    }

    fn widen_target_preparation(
        policy: crate::engine::OpaquePreparePolicy,
        scope: &mut crate::engine::PrepareScope,
        reasons: &mut Vec<crate::engine::OpaqueReason>,
        reason: crate::engine::OpaqueReason,
    ) -> Result<bool, ExcelError> {
        if policy == crate::engine::OpaquePreparePolicy::Error {
            return Err(ExcelError::new(ExcelErrorKind::NImpl)
                .with_message(format!("opaque target preparation semantics: {reason:?}")));
        }
        if !reasons.contains(&reason) {
            reasons.push(reason);
        }
        if !matches!(scope, crate::engine::PrepareScope::Workbook) {
            *scope = crate::engine::PrepareScope::Workbook;
            Ok(true)
        } else {
            Ok(false)
        }
    }

    fn widen_target_preparation_to_sheet(
        policy: crate::engine::OpaquePreparePolicy,
        scope: &mut crate::engine::PrepareScope,
        reasons: &mut Vec<crate::engine::OpaqueReason>,
        reason: crate::engine::OpaqueReason,
        sheet: &str,
    ) -> Result<bool, ExcelError> {
        if policy == crate::engine::OpaquePreparePolicy::Error {
            return Err(ExcelError::new(ExcelErrorKind::NImpl)
                .with_message(format!("opaque target preparation semantics: {reason:?}")));
        }
        if !reasons.contains(&reason) {
            reasons.push(reason);
        }
        match scope {
            crate::engine::PrepareScope::Exact => {
                *scope = crate::engine::PrepareScope::Sheets(vec![sheet.to_string()]);
                Ok(true)
            }
            crate::engine::PrepareScope::Sheets(sheets) => {
                if sheets.iter().any(|candidate| candidate == sheet) {
                    Ok(false)
                } else {
                    sheets.push(sheet.to_string());
                    sheets.sort();
                    Ok(true)
                }
            }
            crate::engine::PrepareScope::Workbook => Ok(false),
        }
    }

    fn ast_has_proven_sheet_local_dynamic(
        ast: &ASTNode,
        provider: &dyn crate::traits::FunctionProvider,
    ) -> bool {
        fn classify(ast: &ASTNode, provider: &dyn crate::traits::FunctionProvider) -> (bool, bool) {
            match &ast.node_type {
                ASTNodeType::Function { name, args } => {
                    let Some(function) = provider.get_function_for_planning("", name) else {
                        return (false, false);
                    };
                    let caps = function.caps();
                    let dynamic = caps.contains(FnCaps::DYNAMIC_DEPENDENCY)
                        || caps.contains(FnCaps::RETURNS_REFERENCE);
                    let canonical = name.rsplit('.').next().unwrap_or(name);
                    if dynamic
                        && !canonical.eq_ignore_ascii_case("OFFSET")
                        && !canonical.eq_ignore_ascii_case("INDEX")
                    {
                        return (false, true);
                    }
                    let mut has_dynamic = dynamic;
                    for arg in args {
                        let (safe, child_dynamic) = classify(arg, provider);
                        if !safe {
                            return (false, has_dynamic || child_dynamic);
                        }
                        has_dynamic |= child_dynamic;
                    }
                    (true, has_dynamic)
                }
                ASTNodeType::UnaryOp { expr, .. } => classify(expr, provider),
                ASTNodeType::BinaryOp { left, right, .. } => {
                    let (left_safe, left_dynamic) = classify(left, provider);
                    let (right_safe, right_dynamic) = classify(right, provider);
                    (left_safe && right_safe, left_dynamic || right_dynamic)
                }
                ASTNodeType::Array(rows) => {
                    let mut has_dynamic = false;
                    for item in rows.iter().flatten() {
                        let (safe, child_dynamic) = classify(item, provider);
                        if !safe {
                            return (false, has_dynamic || child_dynamic);
                        }
                        has_dynamic |= child_dynamic;
                    }
                    (true, has_dynamic)
                }
                ASTNodeType::Reference {
                    reference:
                        ReferenceType::Cell { sheet: None, .. }
                        | ReferenceType::Range { sheet: None, .. },
                    ..
                }
                | ASTNodeType::Literal(_)
                | ASTNodeType::Omitted => (true, false),
                ASTNodeType::Call { .. } | ASTNodeType::Reference { .. } => (false, false),
            }
        }

        let (safe, dynamic) = classify(ast, provider);
        safe && dynamic
    }

    fn table_selection_region(
        &self,
        entry: &crate::engine::graph::TableEntry,
        selection: &crate::engine::TableSelection,
    ) -> Result<PreparationRegion, ExcelError> {
        let mut start_row = entry.range.start.coord.row() + 1;
        let mut end_row = entry.range.end.coord.row() + 1;
        let mut start_col = entry.range.start.coord.col() + 1;
        let mut end_col = entry.range.end.coord.col() + 1;
        match selection {
            crate::engine::TableSelection::Whole => {}
            crate::engine::TableSelection::Headers => {
                if !entry.header_row {
                    return Err(ExcelError::new(ExcelErrorKind::Value)
                        .with_message(format!("table {} has no header row", entry.name)));
                }
                end_row = start_row;
            }
            crate::engine::TableSelection::Data => {
                if entry.header_row {
                    start_row = start_row.saturating_add(1);
                }
                if entry.totals_row {
                    end_row = end_row.saturating_sub(1);
                }
            }
            crate::engine::TableSelection::Totals => {
                if !entry.totals_row {
                    return Err(ExcelError::new(ExcelErrorKind::Value)
                        .with_message(format!("table {} has no totals row", entry.name)));
                }
                start_row = end_row;
            }
            crate::engine::TableSelection::Column(column) => {
                let index = entry.col_index(column).ok_or_else(|| {
                    ExcelError::new(ExcelErrorKind::Name)
                        .with_message(format!("unknown table column: {column}"))
                })?;
                start_col = start_col.saturating_add(index as u32);
                end_col = start_col;
            }
            crate::engine::TableSelection::Columns { start, end } => {
                let first = entry.col_index(start).ok_or_else(|| {
                    ExcelError::new(ExcelErrorKind::Name)
                        .with_message(format!("unknown table column: {start}"))
                })?;
                let last = entry.col_index(end).ok_or_else(|| {
                    ExcelError::new(ExcelErrorKind::Name)
                        .with_message(format!("unknown table column: {end}"))
                })?;
                if first > last {
                    return Err(ExcelError::new(ExcelErrorKind::Value)
                        .with_message("table column selection is reversed"));
                }
                start_col = start_col.saturating_add(first as u32);
                end_col = entry
                    .range
                    .start
                    .coord
                    .col()
                    .saturating_add(last as u32)
                    .saturating_add(1);
            }
        }
        if start_row > end_row && matches!(selection, crate::engine::TableSelection::Data) {
            start_row = entry.range.start.coord.row() + 1;
            end_row = start_row;
        }
        if start_row > end_row || start_col > end_col {
            return Err(
                ExcelError::new(ExcelErrorKind::Value).with_message("table selection is empty")
            );
        }
        Ok(PreparationRegion {
            sheet: self.graph.sheet_name(entry.sheet_id()).to_string(),
            sheet_id: entry.sheet_id(),
            start_row,
            start_col,
            end_row,
            end_col,
        })
    }

    #[cfg(test)]
    pub(crate) fn reset_target_root_dedup_probes_for_test() {
        TARGET_ROOT_DEDUP_PROBES.with(|probes| probes.set(0));
    }

    #[cfg(test)]
    pub(crate) fn target_root_dedup_probes_for_test() -> usize {
        TARGET_ROOT_DEDUP_PROBES.with(std::cell::Cell::get)
    }

    pub(crate) fn resolve_target_producers(
        &mut self,
        targets: &[crate::engine::EvaluationTarget],
    ) -> Result<Vec<crate::engine::target_preparation::TargetProducer>, ExcelError> {
        use crate::engine::target_preparation::TargetProducer;

        let request_id = self
            .active_evaluation_resource_request
            .as_ref()
            .map(|request| request.request_id);
        let mut roots = OrderedTargetProducers::with_capacity(targets.len())
            .map_err(|_| target_root_allocation_error(targets.len(), request_id))?;
        let active_span_refs = self
            .graph
            .formula_authority()
            .active_span_refs()
            .into_iter()
            .map(|span_ref| (span_ref.id, span_ref))
            .collect::<BTreeMap<_, _>>();
        let resolve_region = |engine: &mut Self,
                              region: Region,
                              value_only: Option<CellRef>,
                              roots: &mut OrderedTargetProducers|
         -> Result<(), ExcelError> {
            let before = roots.len();
            let authority = engine.graph.formula_authority();
            for matched in authority.producer_results.query(region).matches {
                if let FormulaProducerId::Span(span_id) = matched.value.producer
                    && let Some(span_ref) = active_span_refs.get(&span_id).copied()
                    && let Some(demanded) = matched.value.result_region.intersection(region)
                {
                    roots
                        .push(TargetProducer::Span { span_ref, demanded })
                        .map_err(|_| target_root_allocation_error(roots.len() + 1, request_id))?;
                }
            }
            for anchor in engine.graph.spill_anchors_in_region(
                region.sheet_id(),
                region.axis_ranges().0.query_bounds().0,
                region.axis_ranges().1.query_bounds().0,
                region.axis_ranges().0.query_bounds().1,
                region.axis_ranges().1.query_bounds().1,
            ) {
                roots
                    .push(TargetProducer::Legacy(anchor))
                    .map_err(|_| target_root_allocation_error(roots.len() + 1, request_id))?;
            }
            for vertex in engine.graph.vertices_in_region(
                region.sheet_id(),
                region.axis_ranges().0.query_bounds().0,
                region.axis_ranges().0.query_bounds().1,
                region.axis_ranges().1.query_bounds().0,
                region.axis_ranges().1.query_bounds().1,
            ) {
                let vertex = engine
                    .graph
                    .get_cell_ref(vertex)
                    .and_then(|cell| engine.graph.spill_registry_anchor_for_cell(cell))
                    .unwrap_or(vertex);
                match engine.graph.get_vertex_kind(vertex) {
                    VertexKind::FormulaScalar | VertexKind::FormulaArray => {
                        roots.push(TargetProducer::Legacy(vertex)).map_err(|_| {
                            target_root_allocation_error(roots.len() + 1, request_id)
                        })?;
                    }
                    VertexKind::NamedScalar
                    | VertexKind::NamedArray
                    | VertexKind::Range
                    | VertexKind::InfiniteRange
                    | VertexKind::Table => {
                        roots.push(TargetProducer::Symbol(vertex)).map_err(|_| {
                            target_root_allocation_error(roots.len() + 1, request_id)
                        })?;
                    }
                    VertexKind::Empty | VertexKind::Cell | VertexKind::External => {}
                }
            }
            if roots.len() == before
                && let Some(cell) = value_only
            {
                roots
                    .push(TargetProducer::ValueOnly(cell))
                    .map_err(|_| target_root_allocation_error(roots.len() + 1, request_id))?;
            }
            Ok(())
        };

        for target in targets {
            match target {
                crate::engine::EvaluationTarget::Cell { sheet, row, col } => {
                    if *row == 0 || *col == 0 {
                        return Err(ExcelError::new(ExcelErrorKind::Ref)
                            .with_message("target cell coordinates are one-based"));
                    }
                    let sheet_id = self.graph.sheet_id(sheet).ok_or_else(|| {
                        ExcelError::new(ExcelErrorKind::Ref)
                            .with_message(format!("target sheet not found: {sheet}"))
                    })?;
                    let cell = CellRef::new(sheet_id, Coord::from_excel(*row, *col, true, true));
                    resolve_region(
                        self,
                        Region::point(sheet_id, *row - 1, *col - 1),
                        Some(cell),
                        &mut roots,
                    )?;
                }
                crate::engine::EvaluationTarget::Range(range) => {
                    let sheet_id = self.graph.sheet_id(&range.sheet).ok_or_else(|| {
                        ExcelError::new(ExcelErrorKind::Ref)
                            .with_message(format!("target sheet not found: {}", range.sheet))
                    })?;
                    resolve_region(
                        self,
                        Region::rect(
                            sheet_id,
                            range.start_row - 1,
                            range.end_row - 1,
                            range.start_col - 1,
                            range.end_col - 1,
                        ),
                        None,
                        &mut roots,
                    )?;
                }
                crate::engine::EvaluationTarget::Name { name, scope_sheet } => {
                    let sheet_id = scope_sheet
                        .as_deref()
                        .and_then(|sheet| self.graph.sheet_id(sheet))
                        .unwrap_or_else(|| self.graph.default_sheet_id());
                    if let Some(entry) = self.graph.resolve_name_entry(name, sheet_id) {
                        roots
                            .push(TargetProducer::Symbol(entry.vertex))
                            .map_err(|_| {
                                target_root_allocation_error(roots.len() + 1, request_id)
                            })?;
                    }
                }
                crate::engine::EvaluationTarget::Table { name, .. } => {
                    if let Some(entry) = self.graph.resolve_table_entry(name) {
                        roots
                            .push(TargetProducer::Symbol(entry.vertex))
                            .map_err(|_| {
                                target_root_allocation_error(roots.len() + 1, request_id)
                            })?;
                    }
                }
            }
        }
        Ok(roots.into_vec())
    }

    fn resolve_target_producers_from_existing_roots(
        &mut self,
        roots: &[crate::engine::target_preparation::TargetProducer],
    ) -> Result<Vec<crate::engine::target_preparation::TargetProducer>, ExcelError> {
        use crate::engine::target_preparation::TargetProducer;
        let request_id = self
            .active_evaluation_resource_request
            .as_ref()
            .map(|request| request.request_id);
        let mut refreshed = OrderedTargetProducers::with_capacity(roots.len())
            .map_err(|_| target_root_allocation_error(roots.len(), request_id))?;
        for root in roots {
            match *root {
                TargetProducer::Span { demanded, .. } => {
                    let (rows, cols) = demanded.axis_ranges();
                    for vertex in self.graph.vertices_in_region(
                        demanded.sheet_id(),
                        rows.query_bounds().0,
                        rows.query_bounds().1,
                        cols.query_bounds().0,
                        cols.query_bounds().1,
                    ) {
                        if matches!(
                            self.graph.get_vertex_kind(vertex),
                            VertexKind::FormulaScalar | VertexKind::FormulaArray
                        ) {
                            refreshed
                                .push(TargetProducer::Legacy(vertex))
                                .map_err(|_| {
                                    target_root_allocation_error(refreshed.len() + 1, request_id)
                                })?;
                        }
                    }
                }
                other => {
                    refreshed.push(other).map_err(|_| {
                        target_root_allocation_error(refreshed.len() + 1, request_id)
                    })?;
                }
            }
        }
        Ok(refreshed.into_vec())
    }

    /// Transactionally prepare the complete ordinary staged demand closure for typed targets.
    ///
    /// This method prepares graph topology only. It does not evaluate target values.
    pub fn prepare_graph_for_targets(
        &mut self,
        targets: &[crate::engine::EvaluationTarget],
        options: crate::engine::TargetEvalOptions<'_>,
    ) -> Result<crate::engine::PreparedTargetGraphReport, ExcelError> {
        let previous_budgets = self.evaluation_resource_budgets.clone();
        let diagnostics_len = self.formula_parse_diagnostics.len();
        let previous_report = self.last_formula_ingest_report.clone();
        if let Some(budgets) = options.budgets {
            self.evaluation_resource_budgets = budgets.clone();
        }
        let previous_graph_budget_override = self
            .graph
            .set_admission_budget_override(Some(self.evaluation_resource_budgets.clone()));
        // Hoist the call's cancellation onto the engine for its duration, so the
        // preparation checkpoints observe it. This is a standalone entry point, so
        // the previous value is restored rather than cleared.
        let previous_cancel = self.active_cancel_flag.take();
        self.active_cancel_flag = options.cancel.clone();
        let result = self.observe_evaluation_resource_request(
            EvaluationRequestKind::TargetPreparation,
            |engine| engine.prepare_graph_for_targets_unobserved(targets, &options),
        );
        self.active_cancel_flag = previous_cancel;
        self.graph
            .set_admission_budget_override(previous_graph_budget_override);
        self.evaluation_resource_budgets = previous_budgets;
        if result.is_err() {
            self.formula_parse_diagnostics.truncate(diagnostics_len);
            self.last_formula_ingest_report = previous_report;
        }
        result
    }

    fn prepare_graph_for_targets_unobserved(
        &mut self,
        targets: &[crate::engine::EvaluationTarget],
        options: &crate::engine::TargetEvalOptions<'_>,
    ) -> Result<crate::engine::PreparedTargetGraphReport, ExcelError> {
        let scratch_checkpoint = self
            .active_resource_ledger
            .as_ref()
            .map_or(0, crate::engine::ResourceLedger::scratch_checkpoint);
        let result = self.prepare_graph_for_targets_transaction(targets, options);
        let release = self
            .active_resource_ledger
            .as_mut()
            .map_or(Ok(()), |ledger| {
                ledger.release_scratch_to(scratch_checkpoint)
            });
        match (result, release) {
            (result, Ok(())) => result,
            (Ok(_), Err(error)) | (Err(_), Err(error)) => Err(error.into_excel_error()),
        }
    }

    fn prepare_graph_for_targets_transaction(
        &mut self,
        targets: &[crate::engine::EvaluationTarget],
        options: &crate::engine::TargetEvalOptions<'_>,
    ) -> Result<crate::engine::PreparedTargetGraphReport, ExcelError> {
        use crate::engine::{
            OpaqueReason, PreparationOutcome, PrepareScope, PreparedTargetGraphReport,
            TableSelection,
        };

        self.target_preparation_checkpoint(options.deadline, 0)?;
        self.observe_function_semantic_epoch()?;
        let assumptions = self.preparation_revisions();
        let ledger_at_start = self
            .active_resource_ledger
            .as_ref()
            .map(|ledger| ledger.snapshot());
        let diagnostics_len = self.formula_parse_diagnostics.len();
        let report_len = self.last_formula_ingest_report.clone();
        let request_id = options.request_id.or_else(|| {
            self.active_evaluation_resource_request
                .as_ref()
                .map(|stats| stats.request_id)
        });

        let mut scope = PrepareScope::Exact;
        let mut reasons = Vec::new();
        let mut regions = VecDeque::new();
        let mut normalized = Vec::with_capacity(targets.len());
        let mut symbol_vertices = VecDeque::new();
        for target in targets {
            self.target_preparation_checkpoint(options.deadline, 1)?;
            match target {
                crate::engine::EvaluationTarget::Cell { sheet, row, col } => {
                    if *row == 0 || *col == 0 {
                        return Err(ExcelError::new(ExcelErrorKind::Ref)
                            .with_message("target cell coordinates are one-based"));
                    }
                    let sheet_id = self.graph.sheet_id(sheet).ok_or_else(|| {
                        ExcelError::new(ExcelErrorKind::Ref)
                            .with_message(format!("target sheet not found: {sheet}"))
                    })?;
                    regions.push_back(PreparationRegion {
                        sheet: sheet.clone(),
                        sheet_id,
                        start_row: *row,
                        start_col: *col,
                        end_row: *row,
                        end_col: *col,
                    });
                    normalized.push(target.clone());
                }
                crate::engine::EvaluationTarget::Range(range) => {
                    if range.start_row == 0
                        || range.start_col == 0
                        || range.end_row < range.start_row
                        || range.end_col < range.start_col
                    {
                        return Err(ExcelError::new(ExcelErrorKind::Ref)
                            .with_message("invalid target range"));
                    }
                    let sheet_id = self.graph.sheet_id(&range.sheet).ok_or_else(|| {
                        ExcelError::new(ExcelErrorKind::Ref)
                            .with_message(format!("target sheet not found: {}", range.sheet))
                    })?;
                    regions.push_back(PreparationRegion {
                        sheet: range.sheet.clone(),
                        sheet_id,
                        start_row: range.start_row,
                        start_col: range.start_col,
                        end_row: range.end_row,
                        end_col: range.end_col,
                    });
                    normalized.push(target.clone());
                }
                crate::engine::EvaluationTarget::Name { name, scope_sheet } => {
                    let current_sheet = match scope_sheet {
                        Some(sheet) => self.graph.sheet_id(sheet).ok_or_else(|| {
                            ExcelError::new(ExcelErrorKind::Ref)
                                .with_message(format!("name scope sheet not found: {sheet}"))
                        })?,
                        None => self.graph.default_sheet_id(),
                    };
                    if let Some(entry) = self.graph.resolve_name_entry(name, current_sheet) {
                        symbol_vertices.push_back(entry.vertex);
                    } else {
                        Self::widen_target_preparation(
                            options.opaque_policy,
                            &mut scope,
                            &mut reasons,
                            OpaqueReason::UnresolvedName,
                        )?;
                    }
                    normalized.push(target.clone());
                }
                crate::engine::EvaluationTarget::Table { name, selection } => {
                    if let Some(entry) = self.graph.resolve_table_entry(name) {
                        let region = self.table_selection_region(entry, selection)?;
                        symbol_vertices.push_back(entry.vertex);
                        regions.push_back(region);
                    } else {
                        Self::widen_target_preparation(
                            options.opaque_policy,
                            &mut scope,
                            &mut reasons,
                            OpaqueReason::UnresolvedTable,
                        )?;
                    }
                    normalized.push(target.clone());
                }
            }
        }

        let mut visited_regions = FxHashSet::default();
        let mut visited_vertices = FxHashSet::default();
        let mut selected = FxHashSet::default();
        let mut prepared = Vec::new();
        let mut pending_diagnostics = Vec::new();
        let mut planning_requests = BTreeSet::new();
        let mut selected_cells = Vec::new();
        let mut workbook_seeded = false;
        let mut sheet_scope_seeded = BTreeSet::new();
        let mut indexed_query_sheets = FxHashSet::default();
        let mut discovery_scratch_reserved = 0u64;
        let mut package_encountered = false;
        let mut selected_package_sheets = FxHashSet::default();
        let mut prepared_packages = Vec::new();
        let authoritative_with_ordinary = self.config.formula_plane_mode
            == FormulaPlaneMode::AuthoritativeExperimental
            && self.staged_formula_index.ordinary_count() != 0;
        let has_unknown_package_sheet = self
            .staged_formula_index
            .package_sheets()
            .any(|sheet| self.graph.sheet_id(sheet).is_none());

        loop {
            if let PrepareScope::Sheets(sheets) = &scope {
                for sheet in sheets.clone() {
                    if !sheet_scope_seeded.insert(sheet.clone()) {
                        continue;
                    }
                    let Some(sheet_id) = self.graph.sheet_id(&sheet) else {
                        package_encountered = true;
                        Self::widen_target_preparation(
                            options.opaque_policy,
                            &mut scope,
                            &mut reasons,
                            OpaqueReason::UnsupportedSourceSemantics,
                        )?;
                        continue;
                    };
                    for lease in self.staged_formula_index.leases_for_sheet(&sheet) {
                        self.target_preparation_checkpoint(options.deadline, 1)?;
                        regions.push_back(PreparationRegion {
                            sheet: sheet.clone(),
                            sheet_id,
                            start_row: lease.row,
                            start_col: lease.col,
                            end_row: lease.row,
                            end_col: lease.col,
                        });
                    }
                    if self
                        .staged_formula_index
                        .package_lease_for_sheet(&sheet)
                        .is_some()
                    {
                        regions.push_back(PreparationRegion {
                            sheet: sheet.clone(),
                            sheet_id,
                            start_row: 1,
                            start_col: 1,
                            end_row: self.workbook_load_limits.max_sheet_rows,
                            end_col: self.workbook_load_limits.max_sheet_cols,
                        });
                    }
                }
            }
            if matches!(scope, PrepareScope::Workbook) && !workbook_seeded {
                workbook_seeded = true;
                for (sheet, lease) in self.staged_formula_index.all_leases() {
                    self.target_preparation_checkpoint(options.deadline, 1)?;
                    let Some(sheet_id) = self.graph.sheet_id(&sheet) else {
                        package_encountered = true;
                        Self::widen_target_preparation(
                            options.opaque_policy,
                            &mut scope,
                            &mut reasons,
                            OpaqueReason::UnsupportedSourceSemantics,
                        )?;
                        continue;
                    };
                    regions.push_back(PreparationRegion {
                        sheet,
                        sheet_id,
                        start_row: lease.row,
                        start_col: lease.col,
                        end_row: lease.row,
                        end_col: lease.col,
                    });
                }
                let package_sheets = self
                    .staged_formula_index
                    .package_sheets()
                    .map(str::to_string)
                    .collect::<Vec<_>>();
                for sheet in package_sheets {
                    let Some(sheet_id) = self.graph.sheet_id(&sheet) else {
                        package_encountered = true;
                        Self::widen_target_preparation(
                            options.opaque_policy,
                            &mut scope,
                            &mut reasons,
                            OpaqueReason::UnsupportedSourceSemantics,
                        )?;
                        continue;
                    };
                    regions.push_back(PreparationRegion {
                        sheet,
                        sheet_id,
                        start_row: 1,
                        start_col: 1,
                        end_row: self.workbook_load_limits.max_sheet_rows,
                        end_col: self.workbook_load_limits.max_sheet_cols,
                    });
                }
            }

            let Some(region) = regions.pop_front() else {
                if let Some(vertex) = symbol_vertices.pop_front() {
                    self.target_preparation_checkpoint(options.deadline, 1)?;
                    if !visited_vertices.insert(vertex) || !self.graph.vertex_exists(vertex) {
                        continue;
                    }
                    let vertex_is_dynamic = self.graph.is_dynamic(vertex);
                    if let Some(ast) = self.graph.get_formula(vertex) {
                        let snapshot =
                            self.target_planning_snapshot(&ast, &mut planning_requests)?;
                        if let Some(reason) =
                            Self::target_planning_snapshot_stale_reason(&snapshot, &assumptions)
                        {
                            return Err(Self::preparation_stale(
                                reason,
                                "target planning snapshot became stale during discovery",
                            ));
                        }
                        let opaque = self.opaque_reason_in_ast(&ast, &snapshot);
                        if let Some(reason) =
                            opaque.or(vertex_is_dynamic.then_some(OpaqueReason::DynamicReference))
                        {
                            if reason == OpaqueReason::DynamicReference
                                && Self::ast_has_proven_sheet_local_dynamic(&ast, &snapshot)
                            {
                                let sheet = self.graph.get_vertex_sheet_id(vertex);
                                let sheet = self.graph.sheet_name(sheet).to_string();
                                Self::widen_target_preparation_to_sheet(
                                    options.opaque_policy,
                                    &mut scope,
                                    &mut reasons,
                                    reason,
                                    &sheet,
                                )?;
                            } else {
                                Self::widen_target_preparation(
                                    options.opaque_policy,
                                    &mut scope,
                                    &mut reasons,
                                    reason,
                                )?;
                            }
                        }
                    } else if vertex_is_dynamic {
                        Self::widen_target_preparation(
                            options.opaque_policy,
                            &mut scope,
                            &mut reasons,
                            OpaqueReason::DynamicReference,
                        )?;
                    }
                    if let Some(anchor) = self
                        .graph
                        .get_cell_ref(vertex)
                        .and_then(|cell| self.graph.spill_registry_anchor_for_cell(cell))
                    {
                        symbol_vertices.push_back(anchor);
                    }
                    if let Some(cell) = self.graph.get_cell_ref(vertex) {
                        let sheet = self.graph.sheet_name(cell.sheet_id).to_string();
                        regions.push_back(PreparationRegion {
                            sheet,
                            sheet_id: cell.sheet_id,
                            start_row: cell.coord.row() + 1,
                            start_col: cell.coord.col() + 1,
                            end_row: cell.coord.row() + 1,
                            end_col: cell.coord.col() + 1,
                        });
                    }
                    for dependency in self.graph.get_dependencies(vertex) {
                        self.target_preparation_checkpoint(options.deadline, 1)?;
                        symbol_vertices.push_back(dependency);
                    }
                    if let Some(range_dependencies) = self
                        .graph
                        .formula_range_dependencies(vertex)
                        .map(<[_]>::to_vec)
                    {
                        for range in range_dependencies {
                            self.target_preparation_checkpoint(options.deadline, 1)?;
                            let sheet_id = match range.sheet {
                                crate::reference::SharedSheetLocator::Id(id) => id,
                                crate::reference::SharedSheetLocator::Current => {
                                    self.graph.get_vertex_sheet_id(vertex)
                                }
                                crate::reference::SharedSheetLocator::Name(ref name) => {
                                    let Some(id) = self.graph.sheet_id(name) else {
                                        if Self::widen_target_preparation(
                                            options.opaque_policy,
                                            &mut scope,
                                            &mut reasons,
                                            OpaqueReason::UnresolvedCrossSheetBinding,
                                        )? {
                                            break;
                                        }
                                        continue;
                                    };
                                    id
                                }
                            };
                            let sheet = self.graph.sheet_name(sheet_id).to_string();
                            regions.push_back(PreparationRegion {
                                sheet,
                                sheet_id,
                                start_row: range.start_row.map_or(1, |bound| bound.index + 1),
                                start_col: range.start_col.map_or(1, |bound| bound.index + 1),
                                end_row: range
                                    .end_row
                                    .map_or(self.workbook_load_limits.max_sheet_rows, |bound| {
                                        bound.index + 1
                                    }),
                                end_col: range
                                    .end_col
                                    .map_or(self.workbook_load_limits.max_sheet_cols, |bound| {
                                        bound.index + 1
                                    }),
                            });
                        }
                    }
                    if let Some(name) = self.graph.named_range_by_vertex(vertex).cloned() {
                        match &name.definition {
                            NamedDefinition::Cell(cell) => regions.push_back(PreparationRegion {
                                sheet: self.graph.sheet_name(cell.sheet_id).to_string(),
                                sheet_id: cell.sheet_id,
                                start_row: cell.coord.row() + 1,
                                start_col: cell.coord.col() + 1,
                                end_row: cell.coord.row() + 1,
                                end_col: cell.coord.col() + 1,
                            }),
                            NamedDefinition::Range(range) => regions.push_back(PreparationRegion {
                                sheet: self.graph.sheet_name(range.start.sheet_id).to_string(),
                                sheet_id: range.start.sheet_id,
                                start_row: range.start.coord.row() + 1,
                                start_col: range.start.coord.col() + 1,
                                end_row: range.end.coord.row() + 1,
                                end_col: range.end.coord.col() + 1,
                            }),
                            NamedDefinition::Formula {
                                ast,
                                dependencies,
                                range_deps,
                            } => {
                                let snapshot =
                                    self.target_planning_snapshot(ast, &mut planning_requests)?;
                                if let Some(reason) = Self::target_planning_snapshot_stale_reason(
                                    &snapshot,
                                    &assumptions,
                                ) {
                                    return Err(Self::preparation_stale(
                                        reason,
                                        "target planning snapshot became stale during discovery",
                                    ));
                                }
                                if let Some(reason) = self.opaque_reason_in_ast(ast, &snapshot) {
                                    Self::widen_target_preparation(
                                        options.opaque_policy,
                                        &mut scope,
                                        &mut reasons,
                                        reason,
                                    )?;
                                }
                                for dependency in dependencies {
                                    self.target_preparation_checkpoint(options.deadline, 1)?;
                                    symbol_vertices.push_back(*dependency);
                                }
                                for range in range_deps {
                                    self.target_preparation_checkpoint(options.deadline, 1)?;
                                    let sheet_id = match range.sheet {
                                        crate::reference::SharedSheetLocator::Id(id) => id,
                                        _ => self.graph.default_sheet_id(),
                                    };
                                    regions.push_back(PreparationRegion {
                                        sheet: self.graph.sheet_name(sheet_id).to_string(),
                                        sheet_id,
                                        start_row: range
                                            .start_row
                                            .map_or(1, |bound| bound.index + 1),
                                        start_col: range
                                            .start_col
                                            .map_or(1, |bound| bound.index + 1),
                                        end_row: range.end_row.map_or(
                                            self.workbook_load_limits.max_sheet_rows,
                                            |bound| bound.index + 1,
                                        ),
                                        end_col: range.end_col.map_or(
                                            self.workbook_load_limits.max_sheet_cols,
                                            |bound| bound.index + 1,
                                        ),
                                    });
                                }
                            }
                            NamedDefinition::Literal(_) => {}
                        }
                    }
                    if let Some(table) = self.graph.table_by_vertex(vertex) {
                        regions
                            .push_back(self.table_selection_region(table, &TableSelection::Whole)?);
                    }
                    continue;
                }
                break;
            };

            self.target_preparation_checkpoint(options.deadline, 1)?;
            if !visited_regions.insert(region.clone()) {
                continue;
            }
            if let PrepareScope::Sheets(sheets) = &mut scope
                && !sheets.iter().any(|sheet| sheet == &region.sheet)
            {
                sheets.push(region.sheet.clone());
                sheets.sort();
            }
            let package_match = self.staged_formula_index.package_for_region(
                &region.sheet,
                region.start_row,
                region.start_col,
                region.end_row,
                region.end_col,
            );
            let package_lease = match package_match {
                Some(Ok(lease)) => Some(lease),
                Some(Err(()))
                    if region.start_row == 1
                        && region.start_col == 1
                        && region.end_row == self.workbook_load_limits.max_sheet_rows
                        && region.end_col == self.workbook_load_limits.max_sheet_cols =>
                {
                    self.staged_formula_index
                        .package_lease_for_sheet(&region.sheet)
                }
                Some(Err(())) => {
                    Self::widen_target_preparation(
                        options.opaque_policy,
                        &mut scope,
                        &mut reasons,
                        OpaqueReason::DeferredSourcePackage,
                    )?;
                    None
                }
                None => None,
            };
            let compatibility_before_package_replay = package_lease.is_some()
                && (authoritative_with_ordinary || has_unknown_package_sheet);
            let package_lease = if compatibility_before_package_replay {
                package_encountered = true;
                Self::widen_target_preparation(
                    options.opaque_policy,
                    &mut scope,
                    &mut reasons,
                    OpaqueReason::UnsupportedSourceSemantics,
                )?;
                None
            } else {
                package_lease
            };
            if let Some(package_lease) = package_lease
                && selected_package_sheets.insert(region.sheet.clone())
            {
                self.target_preparation_checkpoint(options.deadline, 1)?;
                let mut package = self.prepare_target_source_package(
                    &region.sheet,
                    package_lease,
                    options.deadline,
                )?;
                for placement in &package.placements {
                    self.target_preparation_checkpoint(options.deadline, 1)?;
                    for dependency in &placement.fragment_dependency_proof().1.dependencies {
                        self.target_preparation_checkpoint(options.deadline, 1)?;
                        let (rows, cols) = dependency.read_region.axis_ranges();
                        let (start_row, end_row) = rows.query_bounds();
                        let (start_col, end_col) = cols.query_bounds();
                        let dependency_sheet = dependency.read_region.sheet_id();
                        regions.push_back(PreparationRegion {
                            sheet: self.graph.sheet_name(dependency_sheet).to_string(),
                            sheet_id: dependency_sheet,
                            start_row: start_row.saturating_add(1),
                            start_col: start_col.saturating_add(1),
                            end_row: end_row
                                .min(self.workbook_load_limits.max_sheet_rows.saturating_sub(1))
                                .saturating_add(1),
                            end_col: end_col
                                .min(self.workbook_load_limits.max_sheet_cols.saturating_sub(1))
                                .saturating_add(1),
                        });
                    }
                }

                let mut final_fallback = BTreeMap::new();
                for record in package.fallback_records() {
                    final_fallback.insert((record.row, record.col), record.clone());
                }
                let batch = self
                    .formula_batch_from_exact_replay(&region.sheet, final_fallback.into_values())?;
                for record in batch.formulas {
                    self.target_preparation_checkpoint(options.deadline, 1)?;
                    let ast = self
                        .graph
                        .data_store()
                        .retrieve_ast(record.ast_id, self.graph.sheet_reg())
                        .ok_or_else(|| {
                            ExcelError::new(ExcelErrorKind::Value)
                                .with_message("target fallback AST is unavailable")
                        })?;
                    let snapshot = self.target_planning_snapshot(&ast, &mut planning_requests)?;
                    if let Some(reason) =
                        Self::target_planning_snapshot_stale_reason(&snapshot, &assumptions)
                    {
                        return Err(Self::preparation_stale(
                            reason,
                            "target fallback planning snapshot became stale during discovery",
                        ));
                    }
                    let proven_sheet_local_dynamic =
                        Self::ast_has_proven_sheet_local_dynamic(&ast, &snapshot);
                    if let Some(reason) = self.opaque_reason_in_ast(&ast, &snapshot) {
                        if reason == OpaqueReason::DynamicReference && proven_sheet_local_dynamic {
                            Self::widen_target_preparation_to_sheet(
                                options.opaque_policy,
                                &mut scope,
                                &mut reasons,
                                reason,
                                &region.sheet,
                            )?;
                        } else {
                            Self::widen_target_preparation(
                                options.opaque_policy,
                                &mut scope,
                                &mut reasons,
                                reason,
                            )?;
                        }
                    }
                    let placement = CellRef::new(
                        package.sheet_id,
                        Coord::from_excel(record.row, record.col, true, true),
                    );
                    let ingested = self
                        .graph
                        .ingest_pipeline(&snapshot)
                        .enable_function_semantics()
                        .ingest_formula(
                            FormulaAstInput::RawArena(record.ast_id),
                            placement,
                            record.formula_text,
                        )?;
                    if ingested.dep_plan.dynamic {
                        if proven_sheet_local_dynamic {
                            Self::widen_target_preparation_to_sheet(
                                options.opaque_policy,
                                &mut scope,
                                &mut reasons,
                                OpaqueReason::DynamicReference,
                                &region.sheet,
                            )?;
                        } else {
                            Self::widen_target_preparation(
                                options.opaque_policy,
                                &mut scope,
                                &mut reasons,
                                OpaqueReason::DynamicReference,
                            )?;
                        }
                    }
                    for dep in &ingested.dep_plan.direct_cell_deps {
                        self.target_preparation_checkpoint(options.deadline, 1)?;
                        regions.push_back(PreparationRegion {
                            sheet: self.graph.sheet_name(dep.sheet_id).to_string(),
                            sheet_id: dep.sheet_id,
                            start_row: dep.coord.row().saturating_add(1),
                            start_col: dep.coord.col().saturating_add(1),
                            end_row: dep.coord.row().saturating_add(1),
                            end_col: dep.coord.col().saturating_add(1),
                        });
                    }
                    for range in &ingested.dep_plan.range_deps {
                        self.target_preparation_checkpoint(options.deadline, 1)?;
                        let dependency_sheet = match &range.sheet {
                            crate::reference::SharedSheetLocator::Id(id) => *id,
                            crate::reference::SharedSheetLocator::Current => package.sheet_id,
                            crate::reference::SharedSheetLocator::Name(name) => {
                                let Some(id) = self.graph.sheet_id(name) else {
                                    Self::widen_target_preparation(
                                        options.opaque_policy,
                                        &mut scope,
                                        &mut reasons,
                                        OpaqueReason::UnresolvedCrossSheetBinding,
                                    )?;
                                    continue;
                                };
                                id
                            }
                        };
                        regions.push_back(PreparationRegion {
                            sheet: self.graph.sheet_name(dependency_sheet).to_string(),
                            sheet_id: dependency_sheet,
                            start_row: range.start_row.map_or(1, |bound| bound.index + 1),
                            start_col: range.start_col.map_or(1, |bound| bound.index + 1),
                            end_row: range
                                .end_row
                                .map_or(self.workbook_load_limits.max_sheet_rows, |bound| {
                                    bound.index + 1
                                }),
                            end_col: range
                                .end_col
                                .map_or(self.workbook_load_limits.max_sheet_cols, |bound| {
                                    bound.index + 1
                                }),
                        });
                    }
                    for name in ingested
                        .dep_plan
                        .resolved_named_refs
                        .iter()
                        .chain(&ingested.dep_plan.named_refs)
                    {
                        self.target_preparation_checkpoint(options.deadline, 1)?;
                        if let Some(entry) = self.graph.resolve_name_entry(name, package.sheet_id) {
                            symbol_vertices.push_back(entry.vertex);
                        } else if self.graph.resolve_source_scalar_entry(name).is_none()
                            && self.graph.resolve_source_table_entry(name).is_none()
                        {
                            Self::widen_target_preparation(
                                options.opaque_policy,
                                &mut scope,
                                &mut reasons,
                                OpaqueReason::UnresolvedName,
                            )?;
                        }
                    }
                    for table in &ingested.dep_plan.table_refs {
                        self.target_preparation_checkpoint(options.deadline, 1)?;
                        if let Some(entry) = self.graph.resolve_table_entry(table) {
                            symbol_vertices.push_back(entry.vertex);
                        } else if self.graph.resolve_source_table_entry(table).is_none() {
                            Self::widen_target_preparation(
                                options.opaque_policy,
                                &mut scope,
                                &mut reasons,
                                OpaqueReason::UnresolvedTable,
                            )?;
                        }
                    }
                    package.legacy.push((
                        record.row,
                        record.col,
                        ingested.ast_id,
                        ingested.dep_plan,
                    ));
                }
                prepared_packages.push(package);
            }
            let leases = self.staged_formula_index.leases_in_region(
                &region.sheet,
                region.start_row,
                region.start_col,
                region.end_row,
                region.end_col,
            );
            for lease in leases {
                self.target_preparation_checkpoint(options.deadline, 1)?;
                let sheet_id = self.graph.sheet_id(&region.sheet).ok_or_else(|| {
                    ExcelError::new(ExcelErrorKind::Ref)
                        .with_message(format!("staged formula sheet not found: {}", region.sheet))
                })?;
                let key = (region.sheet.clone(), lease.row, lease.col, lease.generation);
                if !selected.insert(key) {
                    continue;
                }
                let text = self
                    .staged_formulas
                    .get(&region.sheet)
                    .and_then(|sheet| sheet.get_ordinary(lease.row, lease.col))
                    .ok_or_else(|| {
                        ExcelError::new(ExcelErrorKind::Value)
                            .with_message("staged formula index is stale")
                    })?
                    .to_string();
                let formula = if text.starts_with('=') {
                    text.clone()
                } else {
                    format!("={text}")
                };
                self.target_preparation_checkpoint(options.deadline, 1)?;
                let ast = match formualizer_parse::parser::parse(&formula) {
                    Ok(ast) => ast,
                    Err(error) => {
                        if self.config.formula_parse_policy == FormulaParsePolicy::Strict {
                            return Err(ExcelError::new(ExcelErrorKind::Value).with_message(
                                format!(
                                    "Formula parse error at {}!{}{}: {error}",
                                    region.sheet,
                                    col_letters_from_1based(lease.col)
                                        .unwrap_or_else(|_| "?".to_string()),
                                    lease.row
                                ),
                            ));
                        }
                        pending_diagnostics.push(FormulaParseDiagnostic {
                            sheet: region.sheet.clone(),
                            row: lease.row,
                            col: lease.col,
                            formula: formula.clone(),
                            message: error.to_string(),
                            policy: self.config.formula_parse_policy,
                        });
                        match self.config.formula_parse_policy {
                            FormulaParsePolicy::KeepCachedValue => {
                                selected_cells.push(
                                    formualizer_common::RangeAddress::new(
                                        region.sheet.clone(),
                                        lease.row,
                                        lease.col,
                                        lease.row,
                                        lease.col,
                                    )
                                    .expect("selected staged coordinates are valid"),
                                );
                                prepared.push(PreparedOrdinaryStagedFormula {
                                    sheet: region.sheet.clone(),
                                    sheet_id,
                                    lease,
                                    ast_id: None,
                                    plan: None,
                                });
                                continue;
                            }
                            FormulaParsePolicy::AsText => ASTNode::new(
                                ASTNodeType::Literal(LiteralValue::Text(formula.clone())),
                                None,
                            ),
                            FormulaParsePolicy::CoerceToError => ASTNode::new(
                                ASTNodeType::Literal(LiteralValue::Error(
                                    ExcelError::new(ExcelErrorKind::Error)
                                        .with_message(format!("Malformed formula: {error}")),
                                )),
                                None,
                            ),
                            FormulaParsePolicy::Strict => unreachable!(),
                        }
                    }
                };
                self.target_preparation_checkpoint(options.deadline, 1)?;
                let snapshot = self.target_planning_snapshot(&ast, &mut planning_requests)?;
                self.target_preparation_checkpoint(options.deadline, 1)?;
                if let Some(reason) =
                    Self::target_planning_snapshot_stale_reason(&snapshot, &assumptions)
                {
                    return Err(Self::preparation_stale(
                        reason,
                        "target planning snapshot became stale during discovery",
                    ));
                }
                if let Some(reason) = self.opaque_reason_in_ast(&ast, &snapshot) {
                    if reason == OpaqueReason::DynamicReference
                        && Self::ast_has_proven_sheet_local_dynamic(&ast, &snapshot)
                    {
                        Self::widen_target_preparation_to_sheet(
                            options.opaque_policy,
                            &mut scope,
                            &mut reasons,
                            reason,
                            &region.sheet,
                        )?;
                    } else {
                        Self::widen_target_preparation(
                            options.opaque_policy,
                            &mut scope,
                            &mut reasons,
                            reason,
                        )?;
                    }
                }
                let proven_sheet_local_dynamic =
                    Self::ast_has_proven_sheet_local_dynamic(&ast, &snapshot);
                let placement = CellRef::new(
                    sheet_id,
                    Coord::from_excel(lease.row, lease.col, true, true),
                );
                let ingested = self.graph.ingest_pipeline(&snapshot).ingest_formula(
                    FormulaAstInput::Tree(ast),
                    placement,
                    Some(Arc::from(formula)),
                )?;
                self.target_preparation_checkpoint(options.deadline, 1)?;
                if ingested.dep_plan.dynamic {
                    if proven_sheet_local_dynamic {
                        Self::widen_target_preparation_to_sheet(
                            options.opaque_policy,
                            &mut scope,
                            &mut reasons,
                            OpaqueReason::DynamicReference,
                            &region.sheet,
                        )?;
                    } else {
                        Self::widen_target_preparation(
                            options.opaque_policy,
                            &mut scope,
                            &mut reasons,
                            OpaqueReason::DynamicReference,
                        )?;
                    }
                }
                for dep in &ingested.dep_plan.direct_cell_deps {
                    self.target_preparation_checkpoint(options.deadline, 1)?;
                    regions.push_back(PreparationRegion {
                        sheet: self.graph.sheet_name(dep.sheet_id).to_string(),
                        sheet_id: dep.sheet_id,
                        start_row: dep.coord.row() + 1,
                        start_col: dep.coord.col() + 1,
                        end_row: dep.coord.row() + 1,
                        end_col: dep.coord.col() + 1,
                    });
                }
                for range in &ingested.dep_plan.range_deps {
                    self.target_preparation_checkpoint(options.deadline, 1)?;
                    let sheet_id = match range.sheet {
                        crate::reference::SharedSheetLocator::Id(id) => id,
                        crate::reference::SharedSheetLocator::Current => sheet_id,
                        crate::reference::SharedSheetLocator::Name(ref name) => {
                            let Some(id) = self.graph.sheet_id(name) else {
                                Self::widen_target_preparation(
                                    options.opaque_policy,
                                    &mut scope,
                                    &mut reasons,
                                    OpaqueReason::UnresolvedCrossSheetBinding,
                                )?;
                                continue;
                            };
                            id
                        }
                    };
                    regions.push_back(PreparationRegion {
                        sheet: self.graph.sheet_name(sheet_id).to_string(),
                        sheet_id,
                        start_row: range.start_row.map_or(1, |bound| bound.index + 1),
                        start_col: range.start_col.map_or(1, |bound| bound.index + 1),
                        end_row: range
                            .end_row
                            .map_or(self.workbook_load_limits.max_sheet_rows, |bound| {
                                bound.index + 1
                            }),
                        end_col: range
                            .end_col
                            .map_or(self.workbook_load_limits.max_sheet_cols, |bound| {
                                bound.index + 1
                            }),
                    });
                }
                for name in ingested
                    .dep_plan
                    .resolved_named_refs
                    .iter()
                    .chain(&ingested.dep_plan.named_refs)
                {
                    self.target_preparation_checkpoint(options.deadline, 1)?;
                    if let Some(entry) = self.graph.resolve_name_entry(name, sheet_id) {
                        symbol_vertices.push_back(entry.vertex);
                    } else if self.graph.resolve_source_scalar_entry(name).is_none()
                        && self.graph.resolve_source_table_entry(name).is_none()
                    {
                        Self::widen_target_preparation(
                            options.opaque_policy,
                            &mut scope,
                            &mut reasons,
                            OpaqueReason::UnresolvedName,
                        )?;
                    }
                }
                for table in &ingested.dep_plan.table_refs {
                    self.target_preparation_checkpoint(options.deadline, 1)?;
                    if let Some(entry) = self.graph.resolve_table_entry(table) {
                        symbol_vertices.push_back(entry.vertex);
                    } else if self.graph.resolve_source_table_entry(table).is_none() {
                        Self::widen_target_preparation(
                            options.opaque_policy,
                            &mut scope,
                            &mut reasons,
                            OpaqueReason::UnresolvedTable,
                        )?;
                    }
                }
                selected_cells.push(
                    formualizer_common::RangeAddress::new(
                        region.sheet.clone(),
                        lease.row,
                        lease.col,
                        lease.row,
                        lease.col,
                    )
                    .expect("selected staged coordinates are valid"),
                );
                prepared.push(PreparedOrdinaryStagedFormula {
                    sheet: region.sheet.clone(),
                    sheet_id,
                    lease,
                    ast_id: Some(ingested.ast_id),
                    plan: Some(ingested.dep_plan),
                });
            }

            if indexed_query_sheets.insert(region.sheet_id) {
                self.graph.prepare_sheet_index_for_query(region.sheet_id);
                let bytes = (self.graph.sheet_index_vertex_count(region.sheet_id) as u64)
                    .saturating_mul(32);
                self.reserve_graph_source_scratch(bytes)?;
                discovery_scratch_reserved = discovery_scratch_reserved.saturating_add(bytes);
            }
            let spill_anchors = self.graph.spill_anchors_in_region(
                region.sheet_id,
                region.start_row - 1,
                region.start_col - 1,
                region.end_row - 1,
                region.end_col - 1,
            );
            for anchor in spill_anchors {
                self.target_preparation_checkpoint(options.deadline, 1)?;
                symbol_vertices.push_back(anchor);
            }
            let vertices = self.graph.vertices_in_region(
                region.sheet_id,
                region.start_row - 1,
                region.end_row - 1,
                region.start_col - 1,
                region.end_col - 1,
            );
            for vertex in vertices {
                self.target_preparation_checkpoint(options.deadline, 1)?;
                symbol_vertices.push_back(vertex);
            }
        }

        #[cfg(test)]
        self.target_preparation_fault(
            crate::engine::target_preparation::TargetPreparationFault::AfterDiscovery,
        )?;

        if package_encountered
            || (self.config.formula_plane_mode == FormulaPlaneMode::AuthoritativeExperimental
                && !prepared.is_empty())
        {
            Self::widen_target_preparation(
                options.opaque_policy,
                &mut scope,
                &mut reasons,
                OpaqueReason::UnsupportedSourceSemantics,
            )?;
            self.target_preparation_checkpoint(options.deadline, 0)?;
            let selected_count = self.staged_formula_count();
            let selected_packages = self
                .staged_formulas
                .values()
                .filter_map(|staged| staged.deferred_package.as_ref())
                .map(|package| package.families.len() + package.partitioned_families.len())
                .sum();
            self.formula_parse_diagnostics.truncate(diagnostics_len);
            self.last_formula_ingest_report = report_len;
            #[cfg(test)]
            if let Some(hook) = self.before_target_preparation_commit_hook.take() {
                hook();
            }
            self.target_preparation_checkpoint(options.deadline, 0)?;
            #[cfg(test)]
            self.target_preparation_fault(
                crate::engine::target_preparation::TargetPreparationFault::FinalRevisionValidation,
            )?;
            let current_revisions = self.preparation_revisions();
            if let Some(reason) = Self::preparation_revision_stale_reason(
                &assumptions,
                &current_revisions,
                &planning_requests,
                true,
            ) {
                return Err(Self::preparation_stale(
                    reason,
                    "target compatibility preparation plan is stale",
                ));
            }
            #[cfg(test)]
            self.target_preparation_fault(
                crate::engine::target_preparation::TargetPreparationFault::FinalGraphValidation,
            )?;
            let commit_work_before = self
                .active_resource_ledger
                .as_ref()
                .map_or(0, |ledger| ledger.snapshot().work_charged);
            let commit_started = crate::instant::FzInstant::now();
            self.build_graph_all_unobserved()?;
            let commit_window = commit_started.elapsed();
            let ledger_after = self
                .active_resource_ledger
                .as_ref()
                .map(|ledger| ledger.snapshot());
            let actual_commit_work = ledger_after
                .map_or(0, |snapshot| snapshot.work_charged)
                .saturating_sub(commit_work_before);
            let observed_scratch_bytes = ledger_after
                .map_or(0, |snapshot| snapshot.scratch_peak)
                .saturating_sub(ledger_at_start.map_or(0, |snapshot| snapshot.scratch_current));
            let revisions = assumptions.clone();
            let report = PreparedTargetGraphReport {
                request_id: request_id.unwrap_or_default(),
                requested_targets: targets.len(),
                normalized_regions: visited_regions.len(),
                normalized_target_list: normalized,
                selected_staged_cells: selected_count,
                selected_source_families: selected_packages,
                retained_staged_cells: self.staged_formula_count(),
                selected_cells,
                retained_cells: Vec::new(),
                widened_scope: PrepareScope::Workbook,
                widening_reasons: reasons,
                revisions,
                commit_window,
                estimated_scratch_bytes: discovery_scratch_reserved
                    .saturating_add((selected_count as u64).saturating_mul(256)),
                observed_scratch_bytes,
                estimated_commit_work: selected_count as u64,
                actual_commit_work,
                outcome: PreparationOutcome::CompatibilityPrepared,
            };
            self.observe_target_preparation_report(&report);
            return Ok(report);
        }

        prepared.sort_by_key(|formula| formula.lease.insertion_order);
        for package in &prepared_packages {
            selected_cells.extend(package.replay_records.iter().filter_map(|record| {
                formualizer_common::RangeAddress::new(
                    package.sheet.clone(),
                    record.row,
                    record.col,
                    record.row,
                    record.col,
                )
                .ok()
            }));
        }
        let (mut legacy_graph, mut planned_formula_count) =
            self.prepare_target_combined_legacy_graph(&prepared_packages, &prepared)?;
        let placements = prepared_packages
            .iter_mut()
            .flat_map(|package| std::mem::take(&mut package.placements))
            .collect::<Vec<_>>();
        let formula_plane = if placements.is_empty() {
            None
        } else {
            match self.graph.formula_authority().prepare_formula_plane_append(
                placements,
                self.graph.data_store(),
                self.graph.sheet_reg(),
            ) {
                Ok(append) => Some(append),
                Err(error) => {
                    let reason = format!("TargetFormulaPlaneAppend:{error}");
                    for package in &mut prepared_packages {
                        *package
                            .source_report
                            .fallback_reasons
                            .entry(reason.clone())
                            .or_default() += package.direct_families as u64;
                        if self.config.formula_plane_mode
                            == FormulaPlaneMode::AuthoritativeExperimental
                        {
                            self.materialize_target_package_direct_records(
                                package,
                                &assumptions,
                                &mut planning_requests,
                                options.deadline,
                            )?;
                        } else {
                            package.direct_families = 0;
                            package.direct_cells = 0;
                            package.direct_fragments = 0;
                            package.direct_complete_families = 0;
                            package.direct_complete_cells = 0;
                            package.direct_partition_families = 0;
                            package.direct_partition_cells = 0;
                        }
                    }
                    (legacy_graph, planned_formula_count) =
                        self.prepare_target_combined_legacy_graph(&prepared_packages, &prepared)?;
                    None
                }
            }
        };
        let new_vertices = legacy_graph.new_vertex_count();
        let new_edges = legacy_graph.planned_edge_count().ok_or_else(|| {
            ExcelError::new(ExcelErrorKind::NImpl).with_message("target graph edge count overflow")
        })?;
        let removed_edges = legacy_graph.removed_edge_count().ok_or_else(|| {
            ExcelError::new(ExcelErrorKind::NImpl).with_message("target graph edge count overflow")
        })?;
        let current = self.graph.baseline_stats();
        let final_vertices = current
            .graph_vertex_count
            .checked_add(new_vertices)
            .ok_or_else(|| {
                crate::engine::ResourceLedgerError::Exhausted(
                    formualizer_common::ResourceExhaustionDetail {
                        reason: formualizer_common::ResourceExhaustionReason::ArithmeticOverflow,
                        limit: u64::MAX,
                        observed: u64::MAX,
                        request_id,
                    },
                )
                .into_excel_error()
            })?;
        let final_edges = current
            .graph_edge_count
            .checked_sub(removed_edges)
            .and_then(|count| count.checked_add(new_edges))
            .ok_or_else(|| {
                crate::engine::ResourceLedgerError::Exhausted(
                    formualizer_common::ResourceExhaustionDetail {
                        reason: formualizer_common::ResourceExhaustionReason::ArithmeticOverflow,
                        limit: u64::MAX,
                        observed: u64::MAX,
                        request_id,
                    },
                )
                .into_excel_error()
            })?;
        #[cfg(test)]
        self.target_preparation_fault(
            crate::engine::target_preparation::TargetPreparationFault::Admission,
        )?;
        let resource = |reason, limit: u64, observed: u64| {
            crate::engine::ResourceLedgerError::Exhausted(
                formualizer_common::ResourceExhaustionDetail {
                    reason,
                    limit,
                    observed,
                    request_id,
                },
            )
            .into_excel_error()
        };
        let admission = crate::engine::resource_ledger::GraphAdmission {
            final_vertices,
            final_edges,
            materialization_cells: planned_formula_count as u64,
            added_vertices: new_vertices,
            added_edges: new_edges,
        };
        let materialized_bytes = admission
            .materialized_graph_bytes()
            .map_err(crate::engine::ResourceLedgerError::into_excel_error)?;
        if let Err(error) = self.preflight_graph_admission(admission) {
            if let formualizer_common::ExcelErrorExtra::Resource { detail } = &error.extra {
                self.observe_target_admission_failure(detail.reason);
            }
            return Err(error);
        }
        let selected_package_records = prepared_packages
            .iter()
            .map(|package| package.replay_records.len() as u64)
            .sum::<u64>();
        let planned_working_bytes = (prepared.len() as u64)
            .saturating_add(selected_package_records)
            .saturating_mul(256)
            .saturating_add((visited_regions.len() as u64).saturating_mul(128))
            .saturating_add((visited_vertices.len() as u64).saturating_mul(32))
            .saturating_add((selected.len() as u64).saturating_mul(96))
            .saturating_add(materialized_bytes);
        let scratch_bytes = discovery_scratch_reserved.saturating_add(planned_working_bytes);
        let remaining_scratch = scratch_bytes.saturating_sub(discovery_scratch_reserved);
        if let Err(error) = self.reserve_graph_source_scratch(remaining_scratch) {
            self.observe_target_admission_failure(
                formualizer_common::ResourceExhaustionReason::ScratchMemory,
            );
            return Err(error);
        }

        let estimated_commit_duration = std::time::Duration::from_nanos(
            (new_vertices as u64)
                .saturating_add(new_edges as u64)
                .saturating_add(prepared.len() as u64)
                .saturating_add(selected_package_records)
                .max(1)
                .saturating_mul(100),
        );
        if options.deadline.is_some_and(|deadline| {
            std::time::Instant::now()
                .checked_add(estimated_commit_duration)
                .is_none_or(|finish| finish > deadline)
        }) {
            self.observe_target_admission_failure(
                formualizer_common::ResourceExhaustionReason::Deadline,
            );
            return Err(resource(
                formualizer_common::ResourceExhaustionReason::Deadline,
                0,
                1,
            ));
        }
        #[cfg(test)]
        if let Some(hook) = self.before_target_preparation_commit_hook.take() {
            hook();
        }
        self.target_preparation_checkpoint(options.deadline, 0)?;
        #[cfg(test)]
        self.target_preparation_fault(
            crate::engine::target_preparation::TargetPreparationFault::FinalRevisionValidation,
        )?;
        let current_revisions = self.preparation_revisions();
        let staged_leases_match = prepared.iter().all(|formula| {
            self.staged_formula_index
                .lease_matches(&formula.sheet, formula.lease)
        }) && prepared_packages.iter().all(|package| {
            self.staged_formula_index
                .package_lease_matches(&package.sheet, package.lease)
        });
        let stale_reason = Self::preparation_revision_stale_reason(
            &assumptions,
            &current_revisions,
            &planning_requests,
            staged_leases_match,
        );
        if let Some(reason) = stale_reason {
            return Err(Self::preparation_stale(
                reason,
                "target graph preparation plan is stale",
            ));
        }
        #[cfg(test)]
        self.target_preparation_fault(
            crate::engine::target_preparation::TargetPreparationFault::FinalGraphValidation,
        )?;
        self.graph
            .validate_prepared_legacy_graph_plan(&legacy_graph)
            .map_err(|error| {
                Self::preparation_stale(
                    formualizer_common::PreparationStaleReason::Graph,
                    format!("target graph preparation plan is stale: {error}"),
                )
            })?;
        if let Some(append) = formula_plane.as_ref() {
            self.graph
                .formula_authority()
                .validate_prepared_formula_plane_append(
                    append,
                    self.graph.data_store(),
                    self.graph.sheet_reg(),
                )
                .map_err(|error| {
                    Self::preparation_stale(
                        formualizer_common::PreparationStaleReason::Authority,
                        format!("target FormulaPlane preparation is stale: {error}"),
                    )
                })?;
        }
        #[cfg(test)]
        self.target_preparation_fault(
            crate::engine::target_preparation::TargetPreparationFault::Reservation,
        )?;
        self.graph.reserve_prepared_legacy_graph_plan(&legacy_graph);
        self.formula_parse_diagnostics
            .try_reserve(pending_diagnostics.len())
            .map_err(|_| {
                resource(
                    formualizer_common::ResourceExhaustionReason::Admission,
                    pending_diagnostics.len() as u64,
                    pending_diagnostics.len() as u64,
                )
            })?;
        self.target_preparation_checkpoint(options.deadline, 0)?;
        #[cfg(test)]
        self.target_preparation_fault(
            crate::engine::target_preparation::TargetPreparationFault::BeforeFirstMutation,
        )?;

        let commit_started = crate::instant::FzInstant::now();
        let committed = self
            .graph
            .apply_prevalidated_legacy_graph_plan(legacy_graph);
        let plane_report =
            if self.config.formula_plane_mode == FormulaPlaneMode::AuthoritativeExperimental {
                formula_plane.map(|append| {
                    self.graph
                        .formula_authority_mut()
                        .apply_prevalidated_formula_plane_append(append)
                })
            } else {
                None
            };
        if let Some(report) = plane_report.as_ref() {
            self.graph.mark_formula_spans_dirty(
                report.spans.iter().copied(),
                WholeSpanDirtyReason::NewSpan,
            );
        }
        for formula in &prepared {
            let removed = self
                .staged_formulas
                .get_mut(&formula.sheet)
                .and_then(|sheet| sheet.remove_ordinary(formula.lease.row, formula.lease.col));
            debug_assert!(removed.is_some());
            let index_removed = self.staged_formula_index.remove(
                &formula.sheet,
                formula.lease.row,
                formula.lease.col,
            );
            debug_assert!(index_removed);
        }
        for package in &prepared_packages {
            let removed = self
                .staged_formulas
                .get_mut(&package.sheet)
                .and_then(|staged| staged.deferred_package.take());
            debug_assert!(removed.is_some());
            self.staged_formula_index.set_package(&package.sheet, None);
        }
        let empty_sheets = self
            .staged_formulas
            .iter()
            .filter_map(|(sheet, staged)| staged.is_empty().then_some(sheet.clone()))
            .collect::<Vec<_>>();
        for sheet in empty_sheets {
            self.staged_formulas.remove(&sheet);
        }
        if committed > 0 || plane_report.is_some() {
            self.mark_topology_edited();
        }
        self.formula_parse_diagnostics.extend(pending_diagnostics);
        if !prepared.is_empty() || !prepared_packages.is_empty() {
            let mut ingest_delta = FormulaIngestReport::with_mode(self.config.formula_plane_mode);
            ingest_delta.formula_cells_seen = (prepared.len() as u64).saturating_add(
                prepared_packages
                    .iter()
                    .map(|package| package.replay_records.len() as u64)
                    .sum::<u64>(),
            );
            ingest_delta.graph_formula_cells_materialized = committed as u64;
            ingest_delta.graph_vertices_created = new_vertices as u64;
            ingest_delta.graph_edges_created = new_edges as u64;
            for package in &prepared_packages {
                let source = &package.source_report;
                ingest_delta.source_formula_events = ingest_delta
                    .source_formula_events
                    .saturating_add(source.source_formula_events);
                ingest_delta.source_formula_records_spooled = ingest_delta
                    .source_formula_records_spooled
                    .saturating_add(source.source_formula_records_spooled);
                ingest_delta.source_spool_encoded_bytes = ingest_delta
                    .source_spool_encoded_bytes
                    .saturating_add(source.source_spool_encoded_bytes);
                ingest_delta.source_spool_peak_memory_bytes = ingest_delta
                    .source_spool_peak_memory_bytes
                    .max(source.source_spool_peak_memory_bytes);
                ingest_delta.source_spool_spilled_bytes = ingest_delta
                    .source_spool_spilled_bytes
                    .saturating_add(source.source_spool_spilled_bytes);
                ingest_delta.source_spool_spill_files = ingest_delta
                    .source_spool_spill_files
                    .saturating_add(source.source_spool_spill_files);
                ingest_delta.source_spool_replays = ingest_delta
                    .source_spool_replays
                    .saturating_add(source.source_spool_replays)
                    .saturating_add(1);
                ingest_delta.source_families_seen = ingest_delta
                    .source_families_seen
                    .saturating_add(source.families_seen);
                ingest_delta.source_family_cells_seen = ingest_delta
                    .source_family_cells_seen
                    .saturating_add(source.family_cells_seen);
                ingest_delta.source_family_shadow_eligible = ingest_delta
                    .source_family_shadow_eligible
                    .saturating_add(source.source_clean_families);
                ingest_delta.source_family_shadow_eligible_cells = ingest_delta
                    .source_family_shadow_eligible_cells
                    .saturating_add(source.source_clean_cells);
                ingest_delta.source_partitioned_families_seen = ingest_delta
                    .source_partitioned_families_seen
                    .saturating_add(source.source_fragmentable_families);
                ingest_delta.source_partition_holes = ingest_delta
                    .source_partition_holes
                    .saturating_add(source.source_hole_exclusions);
                ingest_delta.source_partition_ordinary_exceptions = ingest_delta
                    .source_partition_ordinary_exceptions
                    .saturating_add(source.source_ordinary_exclusions);
                ingest_delta.source_partition_surviving_cells = ingest_delta
                    .source_partition_surviving_cells
                    .saturating_add(source.source_fragmentable_cells);
                for (reason, count) in &source.fallback_reasons {
                    let total = ingest_delta
                        .fallback_reasons
                        .entry(reason.clone())
                        .or_default();
                    *total = total.saturating_add(*count);
                }
                if self.config.formula_plane_mode == FormulaPlaneMode::Off {
                    ingest_delta.source_family_fallback = ingest_delta
                        .source_family_fallback
                        .saturating_add(source.families_seen);
                    ingest_delta.source_family_fallback_cells = ingest_delta
                        .source_family_fallback_cells
                        .saturating_add(source.family_cells_seen);
                } else {
                    ingest_delta.shadow_candidate_cells = ingest_delta
                        .shadow_candidate_cells
                        .saturating_add(source.family_cells_seen);
                    ingest_delta.shadow_accepted_span_cells = ingest_delta
                        .shadow_accepted_span_cells
                        .saturating_add(package.direct_cells);
                    ingest_delta.shadow_fallback_cells =
                        ingest_delta.shadow_fallback_cells.saturating_add(
                            source
                                .family_cells_seen
                                .saturating_sub(package.direct_cells),
                        );
                    ingest_delta.source_anchor_parses = ingest_delta
                        .source_anchor_parses
                        .saturating_add(package.anchor_parses);
                    ingest_delta.source_anchor_asts = ingest_delta
                        .source_anchor_asts
                        .saturating_add(package.anchor_asts);
                    ingest_delta.source_anchor_analyses = ingest_delta
                        .source_anchor_analyses
                        .saturating_add(package.anchor_analyses);
                    ingest_delta.source_compressed_families_prepared = ingest_delta
                        .source_compressed_families_prepared
                        .saturating_add(package.direct_complete_families);
                    ingest_delta.source_compressed_cells_prepared = ingest_delta
                        .source_compressed_cells_prepared
                        .saturating_add(package.direct_complete_cells);
                    ingest_delta.source_partitioned_families_prepared = ingest_delta
                        .source_partitioned_families_prepared
                        .saturating_add(package.direct_partition_families);
                    ingest_delta.source_partition_fragments_prepared = ingest_delta
                        .source_partition_fragments_prepared
                        .saturating_add(package.direct_fragments);
                    ingest_delta.source_partition_span_cells_prepared = ingest_delta
                        .source_partition_span_cells_prepared
                        .saturating_add(package.direct_partition_cells);
                    ingest_delta.source_partition_analyses_reused = ingest_delta
                        .source_partition_analyses_reused
                        .saturating_add(
                            package
                                .direct_fragments
                                .saturating_sub(package.direct_partition_families),
                        );
                    ingest_delta.graph_formula_vertices_avoided_shadow = ingest_delta
                        .graph_formula_vertices_avoided_shadow
                        .saturating_add(package.direct_cells);
                    ingest_delta.ast_roots_avoided_shadow =
                        ingest_delta.ast_roots_avoided_shadow.saturating_add(
                            package
                                .direct_complete_cells
                                .saturating_sub(package.direct_complete_families)
                                .saturating_add(
                                    package
                                        .direct_partition_cells
                                        .saturating_sub(package.direct_fragments),
                                ),
                        );
                    ingest_delta.edge_rows_avoided_shadow = ingest_delta
                        .edge_rows_avoided_shadow
                        .saturating_add(package.direct_cells);
                    if self.config.formula_plane_mode == FormulaPlaneMode::AuthoritativeExperimental
                    {
                        ingest_delta.source_family_promoted = ingest_delta
                            .source_family_promoted
                            .saturating_add(package.direct_families as u64);
                        ingest_delta.source_family_promoted_cells = ingest_delta
                            .source_family_promoted_cells
                            .saturating_add(package.direct_cells);
                        let descendants = package
                            .direct_complete_cells
                            .saturating_sub(package.direct_complete_families)
                            .saturating_add(
                                package
                                    .direct_partition_cells
                                    .saturating_sub(package.direct_partition_families),
                            );
                        ingest_delta.source_descendant_strings_avoided = ingest_delta
                            .source_descendant_strings_avoided
                            .saturating_add(descendants);
                        ingest_delta.source_descendant_events_avoided = ingest_delta
                            .source_descendant_events_avoided
                            .saturating_add(descendants);
                        ingest_delta.source_descendant_analyses_avoided = ingest_delta
                            .source_descendant_analyses_avoided
                            .saturating_add(descendants);
                    }
                    ingest_delta.source_family_fallback =
                        ingest_delta.source_family_fallback.saturating_add(
                            source
                                .families_seen
                                .saturating_sub(package.direct_families as u64),
                        );
                    ingest_delta.source_family_fallback_cells =
                        ingest_delta.source_family_fallback_cells.saturating_add(
                            source
                                .family_cells_seen
                                .saturating_sub(package.direct_cells),
                        );
                }
            }
            if let Some(report) = plane_report.as_ref() {
                ingest_delta.shadow_templates_interned = report.work.templates_to_append as u64;
                ingest_delta.shadow_spans_created = report.spans.len() as u64;
            }
            self.record_formula_ingest_report(ingest_delta);
        }
        let commit_window = commit_started.elapsed();
        let retained_cells = self
            .staged_formula_index
            .all_leases()
            .into_iter()
            .filter_map(|(sheet, lease)| {
                formualizer_common::RangeAddress::new(
                    sheet, lease.row, lease.col, lease.row, lease.col,
                )
                .ok()
            })
            .collect::<Vec<_>>();
        let observed_scratch_bytes = self
            .active_resource_ledger
            .as_ref()
            .map_or(0, |ledger| ledger.snapshot().scratch_peak)
            .saturating_sub(ledger_at_start.map_or(0, |snapshot| snapshot.scratch_current));
        let committed_spans = plane_report
            .as_ref()
            .map_or(0, |report| report.spans.len() as u64);
        let selected_source_families = prepared_packages
            .iter()
            .map(|package| package.lease.family_count)
            .sum::<usize>();
        let selected_staged_cells = prepared
            .len()
            .saturating_add(usize::try_from(selected_package_records).unwrap_or(usize::MAX));
        let actual_commit_work = (new_vertices as u64)
            .saturating_add(new_edges as u64)
            .saturating_add(committed as u64)
            .saturating_add(committed_spans)
            .saturating_add(prepared.len() as u64)
            .saturating_add(prepared_packages.len() as u64);
        let report = PreparedTargetGraphReport {
            request_id: request_id.unwrap_or_default(),
            requested_targets: targets.len(),
            normalized_regions: visited_regions.len(),
            normalized_target_list: normalized,
            selected_staged_cells,
            selected_source_families,
            retained_staged_cells: self.staged_formula_count(),
            selected_cells,
            retained_cells,
            widened_scope: scope,
            widening_reasons: reasons,
            revisions: assumptions,
            commit_window,
            estimated_scratch_bytes: scratch_bytes,
            observed_scratch_bytes,
            estimated_commit_work: (new_vertices as u64)
                .saturating_add(new_edges as u64)
                .saturating_add(prepared.len() as u64)
                .saturating_add(selected_package_records),
            actual_commit_work,
            outcome: PreparationOutcome::Prepared,
        };
        self.observe_target_preparation_report(&report);
        Ok(report)
    }

    /// Build graph for all staged formulas.
    pub fn build_graph_all(&mut self) -> Result<(), formualizer_parse::ExcelError> {
        self.observe_evaluation_resource_request(EvaluationRequestKind::Full, |engine| {
            engine.build_graph_all_unobserved()
        })
    }

    fn build_graph_all_unobserved(&mut self) -> Result<(), formualizer_parse::ExcelError> {
        let selected = self.staged_formula_count();
        let started = crate::instant::FzInstant::now();
        self.resource_checkpoint(selected as u64)?;
        let scratch_bytes = (selected as u64).saturating_mul(256);
        let result = self.with_request_scratch(scratch_bytes, |engine| {
            let index_snapshot = engine.staged_formula_index.clone();
            let collected = std::mem::take(&mut engine.staged_formulas)
                .into_iter()
                .collect();
            engine.staged_formula_index.clear_all();
            engine.build_graph_from_staged_batches(collected, false, index_snapshot)
        });
        self.observe_staged_preparation(selected, self.staged_formula_count(), started.elapsed());
        result
    }

    /// Build graph for specific sheets (consuming only those staged entries).
    pub fn build_graph_for_sheets<'a, I: IntoIterator<Item = &'a str>>(
        &mut self,
        sheets: I,
    ) -> Result<(), formualizer_parse::ExcelError> {
        let mut sheets = sheets.into_iter();
        self.observe_evaluation_resource_request(EvaluationRequestKind::Targeted, move |engine| {
            let name_scratch = (sheets.size_hint().0 as u64).saturating_mul(64);
            engine.with_request_scratch(name_scratch, |engine| {
                // Allocation failure follows the baseline process-fatal policy; it is not a
                // recoverable resource error or a new staged-preparation route.
                let names = sheets.by_ref().map(str::to_string).collect::<Vec<_>>();
                engine.charge_bounded_work(names.len() as u64)?;
                engine.build_graph_for_sheet_names_unobserved(names)
            })
        })
    }

    fn build_graph_for_sheet_names_unobserved(
        &mut self,
        sheets: Vec<String>,
    ) -> Result<(), formualizer_parse::ExcelError> {
        let started = crate::instant::FzInstant::now();
        let selected = sheets
            .iter()
            .filter_map(|sheet| self.staged_formulas.get(sheet))
            .map(StagedSheet::len)
            .sum::<usize>();
        self.resource_checkpoint(selected as u64)?;
        let scratch_bytes = (selected as u64).saturating_mul(256);
        self.reserve_request_scratch(scratch_bytes)?;
        let index_snapshot = self.staged_formula_index.clone();
        let mut collected = Vec::new();
        for sheet in sheets {
            if let Some(staged) = self.staged_formulas.remove(&sheet) {
                self.index_removed_staged_sheet(&sheet, &staged);
                collected.push((sheet, staged));
            }
        }
        let result = self.build_graph_from_staged_batches(collected, true, index_snapshot);
        self.release_request_scratch(scratch_bytes);
        self.observe_staged_preparation(selected, self.staged_formula_count(), started.elapsed());
        result
    }

    fn build_graph_from_staged_batches(
        &mut self,
        collected: StagedFormulaBatches,
        share_parse_cache_across_sheets: bool,
        staged_index_snapshot: StagedFormulaIndex,
    ) -> Result<(), formualizer_parse::ExcelError> {
        if collected.is_empty() {
            return Ok(());
        }
        for (sheet, _) in &collected {
            let _ = self.add_sheet(sheet);
        }

        let diagnostics_len = self.formula_parse_diagnostics.len();
        let mut collected = collected;
        let prepared = match self
            .prepare_staged_formula_batches(&mut collected, share_parse_cache_across_sheets)
        {
            Ok(prepared) => prepared,
            Err(error) => {
                self.formula_parse_diagnostics.truncate(diagnostics_len);
                for (sheet, staged) in collected {
                    self.restore_staged_sheet(sheet, staged);
                }
                self.staged_formula_index = staged_index_snapshot;
                return Err(error);
            }
        };
        let (ordinary, compressed, direct) = prepared;

        // Deferred packages are consumed exactly once once authority commit starts.
        // Pre-commit lock, replay, and parse failures restore them above for retry.
        if !ordinary.is_empty()
            && let Err(error) = self.ingest_formula_batches(ordinary)
        {
            self.formula_parse_diagnostics.truncate(diagnostics_len);
            for (sheet, staged) in collected {
                self.restore_staged_sheet(sheet, staged);
            }
            self.staged_formula_index = staged_index_snapshot;
            return Err(error);
        }
        if !compressed.is_empty() {
            let _ = self.ingest_compressed_formula_source_batches(compressed)?;
        }
        if !direct.is_empty() {
            let _ = self.finish_compressed_formula_sources(direct)?;
        }
        self.dedup_formula_parse_diagnostics_since(diagnostics_len);
        Ok(())
    }

    fn prepare_staged_formula_batches(
        &mut self,
        collected: &mut StagedFormulaBatches,
        share_parse_cache_across_sheets: bool,
    ) -> Result<PreparedStagedFormulaBatches, formualizer_parse::ExcelError> {
        let mut ordinary = Vec::new();
        let mut compressed = Vec::new();
        let mut direct = Vec::new();
        let mut cache: rustc_hash::FxHashMap<String, Option<crate::engine::arena::AstNodeId>> =
            rustc_hash::FxHashMap::default();
        cache.reserve(4096);

        for (sheet, staged) in collected {
            if !share_parse_cache_across_sheets {
                cache.clear();
            }
            let mut entries: Vec<_> = staged
                .entries
                .iter()
                .cloned()
                .map(|(row, col, text)| (row, col, text, None))
                .collect();
            let mut deferred_source = None;
            let mut deferred_fallback = None;
            if let Some(package) = staged.deferred_package.as_mut() {
                if package.sheet_name != *sheet {
                    return Err(ExcelError::new(ExcelErrorKind::Value)
                        .with_message("deferred formula package sheet mismatch"));
                }
                let eligible: Vec<_> = package
                    .families
                    .iter()
                    .filter(|family| !package.invalidated.contains(&family.source_id))
                    .cloned()
                    .collect();
                let eligible_partitions: Vec<_> = package
                    .partitioned_families
                    .iter()
                    .filter(|family| !package.invalidated.contains(&family.source_id))
                    .cloned()
                    .collect();
                if self.config.formula_plane_mode == FormulaPlaneMode::AuthoritativeExperimental {
                    let mut preparation = self.prepare_source_formula_proposals(
                        sheet,
                        &eligible,
                        &eligible_partitions,
                        &package.partitioned_families,
                        package.report.source_formula_records_spooled,
                        Arc::clone(&package.replay),
                        &package.suppressed,
                    )?;
                    let replay_records = std::mem::take(&mut preparation.eager_replay);
                    let (fragment_legacy, ordered_fallback): (Vec<_>, Vec<_>) = {
                        let accepted: BTreeMap<_, _> = preparation
                            .fragmented
                            .iter()
                            .map(|fragment| (fragment.source.source_id, &fragment.source))
                            .collect();
                        replay_records.into_iter().partition(|record| {
                            record.partition_owner.is_some_and(|owner| {
                                accepted.get(&owner).is_some_and(|source| {
                                    Self::exact_replay_record_is_prepared_partition_legacy(
                                        source, record,
                                    )
                                })
                            })
                        })
                    };
                    preparation.eager_replay = fragment_legacy;
                    entries.extend(ordered_fallback.into_iter().map(|record| {
                        (
                            record.row,
                            record.col,
                            record.text,
                            Some((record.source_order, record.family, record.partition_owner)),
                        )
                    }));
                    deferred_source = Some((package.report.clone(), preparation));
                } else {
                    let mut replay_disposition = crate::engine::FormulaReplayDisposition::default();
                    for partition in &eligible_partitions {
                        replay_disposition
                            .register_partition(partition, false)
                            .map_err(|reason| {
                                ExcelError::new(ExcelErrorKind::Value).with_message(reason)
                            })?;
                    }
                    replay_disposition
                        .extend_suppressed_excel_coords(package.suppressed.iter().copied());
                    let replayed = package
                        .replay
                        .lock()
                        .map_err(|_| {
                            ExcelError::new(ExcelErrorKind::Value)
                                .with_message("deferred formula spool lock poisoned")
                        })?
                        .replay(&replay_disposition)
                        .map_err(|message| {
                            ExcelError::new(ExcelErrorKind::Value).with_message(message)
                        })?;
                    entries.extend(replayed.into_iter().map(|record| {
                        (
                            record.row,
                            record.col,
                            record.text,
                            Some((record.source_order, record.family, record.partition_owner)),
                        )
                    }));
                    let mut report = package.report.clone();
                    report.source_spool_replays = report.source_spool_replays.saturating_add(1);
                    deferred_fallback =
                        Some((report, package.families.clone(), eligible_partitions));
                }
            }

            let mut formulas = Vec::new();
            let staged_order_base = u64::MAX.saturating_sub(entries.len() as u64);
            for (entry_index, (row, col, txt, source_proof)) in entries.into_iter().enumerate() {
                let key = if txt.starts_with('=') {
                    txt
                } else {
                    format!("={txt}")
                };
                let ast_id = if let Some(cached) = cache.get(&key) {
                    *cached
                } else {
                    let parsed = match formualizer_parse::parser::parse(&key) {
                        Ok(parsed) => Some(parsed),
                        Err(error) => self.handle_formula_parse_error(
                            sheet,
                            row,
                            col,
                            &key,
                            error.to_string(),
                        )?,
                    };
                    let ast_id = parsed.as_ref().map(|ast| self.intern_formula_ast(ast));
                    cache.insert(key.clone(), ast_id);
                    ast_id
                };

                if let Some(ast_id) = ast_id {
                    let mut formula = FormulaIngestRecord::new(
                        row,
                        col,
                        ast_id,
                        Some(Arc::<str>::from(key.clone())),
                    );
                    if let Some((order, family, owner)) = source_proof {
                        formula = formula.with_source_proof(order, family, owner);
                    } else if deferred_source.is_some() {
                        formula = formula.with_source_proof(
                            crate::engine::SourceFormulaOrder::new(
                                staged_order_base.saturating_add(entry_index as u64),
                            ),
                            None,
                            None,
                        );
                    }
                    formulas.push(formula);
                }
            }

            let batch = FormulaIngestBatch::new(sheet.clone(), formulas);
            if let Some((report, preparation)) = deferred_source {
                direct.push((batch, report, preparation));
            } else if let Some((report, families, partitions)) = deferred_fallback {
                let source_batch = crate::engine::FormulaCompressedSourceBatch::with_proposals(
                    batch.sheet_name.clone(),
                    report,
                    families,
                    partitions,
                );
                compressed.push((batch, source_batch));
            } else if !batch.is_empty() {
                ordinary.push(batch);
            }
        }
        Ok((ordinary, compressed, direct))
    }

    /// Begin bulk Arrow ingest for base values (Phase A)
    pub fn begin_bulk_ingest_arrow(
        &mut self,
    ) -> crate::engine::arrow_ingest::ArrowBulkIngestBuilder<'_, R> {
        crate::engine::arrow_ingest::ArrowBulkIngestBuilder::new(self)
    }

    /// Begin bulk updates to Arrow store (Phase C)
    pub fn begin_bulk_update_arrow(
        &mut self,
    ) -> crate::engine::arrow_ingest::ArrowBulkUpdateBuilder<'_, R> {
        crate::engine::arrow_ingest::ArrowBulkUpdateBuilder::new(self)
    }

    fn ensure_known_sheet_id(&self, sheet: &str) -> Result<SheetId, crate::engine::EditorError> {
        self.graph.sheet_id(sheet).ok_or(
            crate::engine::graph::editor::vertex_editor::EditorError::InvalidName {
                name: sheet.to_string(),
                reason: "Unknown sheet".to_string(),
            },
        )
    }

    fn normalize_row_1based(row_1based: u32) -> Result<u32, crate::engine::EditorError> {
        if row_1based == 0 {
            return Err(crate::engine::EditorError::OutOfBounds { row: 0, col: 0 });
        }
        Ok(row_1based - 1)
    }

    fn normalize_row_range_1based(
        start_row_1based: u32,
        end_row_1based: u32,
    ) -> Result<(u32, u32), crate::engine::EditorError> {
        if start_row_1based == 0 || end_row_1based == 0 {
            return Err(crate::engine::EditorError::OutOfBounds { row: 0, col: 0 });
        }
        if start_row_1based > end_row_1based {
            return Err(crate::engine::EditorError::TransactionFailed {
                reason: "Row range start is greater than end".to_string(),
            });
        }
        Ok((start_row_1based - 1, end_row_1based - 1))
    }

    fn invalidate_row_visibility_mask_cache(&self) {
        if let Ok(mut cache) = self.row_visibility_mask_cache.write() {
            cache.clear();
        }
    }

    fn set_row_hidden_by_sheet_id(
        &mut self,
        sheet_id: SheetId,
        row0: u32,
        hidden: bool,
        source: RowVisibilitySource,
    ) -> bool {
        let changed = {
            let state = self.row_visibility.entry(sheet_id).or_default();
            state.set_row_hidden(row0, hidden, source)
        };

        let remove_entry = self
            .row_visibility
            .get(&sheet_id)
            .map(|state| state.is_empty())
            .unwrap_or(false);
        if remove_entry {
            self.row_visibility.remove(&sheet_id);
        }

        if changed {
            self.invalidate_row_visibility_mask_cache();
        }

        changed
    }

    fn set_rows_hidden_by_sheet_id(
        &mut self,
        sheet_id: SheetId,
        start_row0: u32,
        end_row0: u32,
        hidden: bool,
        source: RowVisibilitySource,
    ) -> bool {
        let changed = {
            let state = self.row_visibility.entry(sheet_id).or_default();
            state.set_rows_hidden(start_row0, end_row0, hidden, source)
        };

        let remove_entry = self
            .row_visibility
            .get(&sheet_id)
            .map(|state| state.is_empty())
            .unwrap_or(false);
        if remove_entry {
            self.row_visibility.remove(&sheet_id);
        }

        if changed {
            self.invalidate_row_visibility_mask_cache();
        }

        changed
    }

    fn shift_row_visibility_insert(&mut self, sheet_id: SheetId, before0: u32, count: u32) {
        if count == 0 {
            return;
        }
        let mut changed = false;
        let remove_entry = if let Some(state) = self.row_visibility.get_mut(&sheet_id) {
            changed = state.insert_rows(before0, count);
            state.is_empty()
        } else {
            false
        };
        if remove_entry {
            self.row_visibility.remove(&sheet_id);
        }
        if changed {
            self.invalidate_row_visibility_mask_cache();
        }
    }

    fn shift_row_visibility_delete(&mut self, sheet_id: SheetId, start0: u32, count: u32) {
        if count == 0 {
            return;
        }
        let mut changed = false;
        let remove_entry = if let Some(state) = self.row_visibility.get_mut(&sheet_id) {
            changed = state.delete_rows(start0, count);
            state.is_empty()
        } else {
            false
        };
        if remove_entry {
            self.row_visibility.remove(&sheet_id);
        }
        if changed {
            self.invalidate_row_visibility_mask_cache();
        }
    }

    fn apply_inverse_row_visibility_event(&mut self, event: &crate::engine::ChangeEvent) {
        if let crate::engine::ChangeEvent::SetRowVisibility {
            sheet_id,
            row0,
            source,
            old_hidden,
            ..
        } = event
        {
            let _ = self.set_row_hidden_by_sheet_id(*sheet_id, *row0, *old_hidden, *source);
        }
    }

    fn apply_forward_row_visibility_event(&mut self, event: &crate::engine::ChangeEvent) {
        if let crate::engine::ChangeEvent::SetRowVisibility {
            sheet_id,
            row0,
            source,
            new_hidden,
            ..
        } = event
        {
            let _ = self.set_row_hidden_by_sheet_id(*sheet_id, *row0, *new_hidden, *source);
        }
    }

    fn apply_inverse_row_visibility_events(&mut self, events: &[crate::engine::ChangeEvent]) {
        for event in events.iter().rev() {
            self.apply_inverse_row_visibility_event(event);
        }
    }

    fn apply_forward_row_visibility_events(&mut self, events: &[crate::engine::ChangeEvent]) {
        for event in events {
            self.apply_forward_row_visibility_event(event);
        }
    }

    fn apply_inverse_staged_formula_event(&mut self, event: &crate::engine::ChangeEvent) {
        if let crate::engine::ChangeEvent::StagedFormulaCellChanged {
            sheet,
            row,
            col,
            old,
            ..
        } = event
        {
            self.apply_staged_formula_cell(sheet, *row, *col, old.as_deref());
        }
    }

    fn apply_forward_staged_formula_event(&mut self, event: &crate::engine::ChangeEvent) {
        if let crate::engine::ChangeEvent::StagedFormulaCellChanged {
            sheet,
            row,
            col,
            new,
            ..
        } = event
        {
            self.apply_staged_formula_cell(sheet, *row, *col, new.as_deref());
        }
    }

    /// Set a single cell's staged formula text to `target` (clearing it when
    /// `None`). Used by undo/redo replay of per-cell staged-formula deltas.
    fn apply_staged_formula_cell(&mut self, sheet: &str, row: u32, col: u32, target: Option<&str>) {
        match target {
            Some(text) => self.stage_formula_text(sheet, row, col, text.to_string()),
            None => {
                self.clear_staged_formula_text(sheet, row, col);
            }
        }
    }

    pub fn set_row_hidden(
        &mut self,
        sheet: &str,
        row_1based: u32,
        hidden: bool,
        source: RowVisibilitySource,
    ) -> Result<(), crate::engine::EditorError> {
        self.observe_function_semantic_epoch()
            .map_err(crate::engine::EditorError::Excel)?;
        self.observe_function_semantic_epoch()
            .map_err(crate::engine::EditorError::Excel)?;
        let sheet_id = self.ensure_known_sheet_id(sheet)?;
        let row0 = Self::normalize_row_1based(row_1based)?;
        if self.set_row_hidden_by_sheet_id(sheet_id, row0, hidden, source) {
            self.record_formula_plane_structural_change(StructuralScope::Region(
                Region::whole_row(sheet_id, row0),
            ));
            self.mark_data_edited();
        }
        Ok(())
    }

    pub fn set_rows_hidden(
        &mut self,
        sheet: &str,
        start_row_1based: u32,
        end_row_1based: u32,
        hidden: bool,
        source: RowVisibilitySource,
    ) -> Result<(), crate::engine::EditorError> {
        let sheet_id = self.ensure_known_sheet_id(sheet)?;
        let (start_row0, end_row0) =
            Self::normalize_row_range_1based(start_row_1based, end_row_1based)?;
        if self.set_rows_hidden_by_sheet_id(sheet_id, start_row0, end_row0, hidden, source) {
            if start_row0 == end_row0 {
                self.record_formula_plane_structural_change(StructuralScope::Region(
                    Region::whole_row(sheet_id, start_row0),
                ));
            } else {
                self.record_formula_plane_structural_change(StructuralScope::Sheet(sheet_id));
            }
            self.mark_data_edited();
        }
        Ok(())
    }

    pub fn is_row_hidden(
        &self,
        sheet: &str,
        row_1based: u32,
        source: Option<RowVisibilitySource>,
    ) -> Option<bool> {
        let sheet_id = self.graph.sheet_id(sheet)?;
        let row0 = row_1based.checked_sub(1)?;
        Some(
            self.row_visibility
                .get(&sheet_id)
                .map(|state| state.is_row_hidden(row0, source))
                .unwrap_or(false),
        )
    }

    pub fn row_visibility_version(&self, sheet: &str) -> Option<u64> {
        let sheet_id = self.graph.sheet_id(sheet)?;
        Some(
            self.row_visibility
                .get(&sheet_id)
                .map(|state| state.version())
                .unwrap_or(0),
        )
    }

    fn build_row_visibility_mask_for_view(
        &self,
        view: &RangeView<'_>,
        mode: VisibilityMaskMode,
    ) -> Option<std::sync::Arc<arrow_array::BooleanArray>> {
        let sheet_rows = view.sheet().nrows as usize;
        if sheet_rows == 0 || view.start_row() >= sheet_rows {
            return Some(std::sync::Arc::new(arrow_array::BooleanArray::new_null(0)));
        }

        let sheet_id = self.graph.sheet_id(view.sheet_name())?;
        let start_row0 = view.start_row() as u32;
        let end_row0 = view.end_row().min(sheet_rows.saturating_sub(1)) as u32;
        let version = self
            .row_visibility
            .get(&sheet_id)
            .map(|state| state.version())
            .unwrap_or(0);
        let key = VisibilityMaskCacheKey {
            sheet_id,
            start_row0,
            end_row0,
            mode,
            version,
        };

        if let Ok(cache) = self.row_visibility_mask_cache.read()
            && let Some(mask) = cache.get(&key)
        {
            #[cfg(test)]
            visibility_mask_test_hooks::inc_hit();
            return Some(mask.clone());
        }

        #[cfg(test)]
        visibility_mask_test_hooks::inc_miss();

        let state = self.row_visibility.get(&sheet_id);
        let mut out = Vec::with_capacity((end_row0 - start_row0 + 1) as usize);
        for row0 in start_row0..=end_row0 {
            let manual_hidden = state
                .map(|s| s.is_row_hidden(row0, Some(RowVisibilitySource::Manual)))
                .unwrap_or(false);
            let filter_hidden = state
                .map(|s| s.is_row_hidden(row0, Some(RowVisibilitySource::Filter)))
                .unwrap_or(false);

            let include = match mode {
                VisibilityMaskMode::IncludeAll => true,
                VisibilityMaskMode::ExcludeManualHidden => !manual_hidden,
                VisibilityMaskMode::ExcludeFilterHidden => !filter_hidden,
                VisibilityMaskMode::ExcludeManualOrFilterHidden => {
                    !(manual_hidden || filter_hidden)
                }
            };
            out.push(include);
        }

        let mask = std::sync::Arc::new(arrow_array::BooleanArray::from(out));
        if let Ok(mut cache) = self.row_visibility_mask_cache.write() {
            const MAX_CACHE_ENTRIES: usize = 4096;
            if cache.len() >= MAX_CACHE_ENTRIES {
                cache.clear();
                #[cfg(test)]
                visibility_mask_test_hooks::inc_eviction();
            }
            cache.insert(key, mask.clone());
        }

        Some(mask)
    }

    fn editor_error_to_excel(error: crate::engine::EditorError) -> ExcelError {
        match error {
            crate::engine::EditorError::Excel(error) => error,
            other => ExcelError::new(ExcelErrorKind::Value).with_message(other.to_string()),
        }
    }

    fn observe_function_semantic_epoch(&mut self) -> Result<bool, ExcelError> {
        let changes =
            crate::function_registry::semantic_changes_since(self.function_semantic_epoch_seen);
        let global_changed = changes.epoch != self.function_semantic_epoch_seen;
        let provider_revision = self.resolver.planning_semantic_revision();
        let provider_changed = provider_revision != self.function_provider_revision_seen;
        if !global_changed && !provider_changed {
            return Ok(false);
        }

        let changed = changes.keys.into_iter().collect::<BTreeSet<_>>();
        let sheets: BTreeSet<_> = self
            .graph
            .formula_authority()
            .plane
            .spans
            .active_spans()
            .filter_map(|span| {
                let Some(template) = self
                    .graph
                    .formula_authority()
                    .plane
                    .templates
                    .get(span.template_id)
                else {
                    return (provider_changed || global_changed && !changes.complete)
                        .then_some(span.domain.sheet_id());
                };
                let Some(ast) = self
                    .graph
                    .data_store()
                    .reconstruct_ast_node(template.ast_id, self.graph.sheet_reg())
                else {
                    return (provider_changed || global_changed && !changes.complete)
                        .then_some(span.domain.sheet_id());
                };
                let global_affected = global_changed
                    && (!changes.complete || Self::ast_uses_changed_function(&ast, &changed));
                let provider_affected = provider_changed && Self::ast_contains_function(&ast);
                (global_affected || provider_affected).then_some(span.domain.sheet_id())
            })
            .collect();
        let invalidated = !sheets.is_empty();
        for sheet_id in sheets {
            self.demote_spans_preserving_computed_overlays(sheet_id, Region::whole_sheet(sheet_id))
                .map_err(Self::editor_error_to_excel)?;
        }
        if global_changed && !changed.is_empty() || provider_changed {
            self.cached_static_schedule = None;
        }
        self.function_semantic_epoch_seen = changes.epoch;
        self.function_provider_revision_seen = provider_revision;
        Ok(invalidated)
    }

    pub(crate) fn ast_uses_changed_function(
        ast: &ASTNode,
        changed: &BTreeSet<(String, String)>,
    ) -> bool {
        match &ast.node_type {
            ASTNodeType::Function { name, args } => {
                let normalized = name.to_uppercase();
                let mut spellings = vec![(String::new(), normalized.clone())];
                let mut stripped = normalized.as_str();
                loop {
                    let Some(rest) = ["_XLFN.", "_XLL.", "_XLWS."]
                        .iter()
                        .find_map(|prefix| stripped.strip_prefix(prefix))
                    else {
                        break;
                    };
                    stripped = rest;
                    spellings.push((String::new(), stripped.to_string()));
                }
                let resolved = crate::function_registry::resolve("", name);
                let directly_changed = spellings.iter().any(|spelling| changed.contains(spelling))
                    || resolved.as_ref().is_some_and(|resolved| {
                        changed.contains(&(
                            resolved.namespace.clone(),
                            resolved.canonical_name.clone(),
                        ))
                    });
                directly_changed
                    || resolved.is_none()
                    || args
                        .iter()
                        .any(|arg| Self::ast_uses_changed_function(arg, changed))
            }
            ASTNodeType::Call { callee, args } => {
                Self::ast_uses_changed_function(callee, changed)
                    || args
                        .iter()
                        .any(|arg| Self::ast_uses_changed_function(arg, changed))
            }
            ASTNodeType::UnaryOp { expr, .. } => Self::ast_uses_changed_function(expr, changed),
            ASTNodeType::BinaryOp { left, right, .. } => {
                Self::ast_uses_changed_function(left, changed)
                    || Self::ast_uses_changed_function(right, changed)
            }
            ASTNodeType::Array(rows) => rows
                .iter()
                .flatten()
                .any(|node| Self::ast_uses_changed_function(node, changed)),
            _ => false,
        }
    }

    fn ast_contains_function(ast: &ASTNode) -> bool {
        match &ast.node_type {
            ASTNodeType::Function { .. } => true,
            ASTNodeType::Call { callee, args } => {
                Self::ast_contains_function(callee) || args.iter().any(Self::ast_contains_function)
            }
            ASTNodeType::UnaryOp { expr, .. } => Self::ast_contains_function(expr),
            ASTNodeType::BinaryOp { left, right, .. } => {
                Self::ast_contains_function(left) || Self::ast_contains_function(right)
            }
            ASTNodeType::Array(rows) => rows.iter().flatten().any(Self::ast_contains_function),
            ASTNodeType::Literal(_) | ASTNodeType::Omitted | ASTNodeType::Reference { .. } => false,
        }
    }

    fn demote_span_containing_cell_for_write(
        &mut self,
        sheet_id: SheetId,
        row0: u32,
        col0: u32,
    ) -> Result<(), crate::engine::EditorError> {
        if self.config.formula_plane_mode == FormulaPlaneMode::Off {
            return Ok(());
        }
        let placement = PlacementCoord::new(sheet_id, row0, col0);
        let inside_active_span = self
            .graph
            .formula_authority()
            .plane
            .spans
            .find_at(placement)
            .is_some();
        if inside_active_span {
            self.demote_spans_preserving_computed_overlays(
                sheet_id,
                Region::point(sheet_id, row0, col0),
            )?;
        }
        Ok(())
    }

    fn demote_spans_preserving_computed_overlays(
        &mut self,
        _sheet_id: SheetId,
        affected_region: Region,
    ) -> Result<(), crate::engine::EditorError> {
        // Per-cell write inside a span (or whole-sheet demote via remove_sheet):
        // not a structural axis shift. Demote every span whose result or read
        // region intersects `affected_region`; leave disjoint spans untouched.
        self.demote_spans_for_structural_op_impl(None, affected_region, false)
    }

    fn structural_row_region(sheet_id: SheetId, start_row0: u32) -> Region {
        Region::rows_from(sheet_id, start_row0)
    }

    fn structural_col_region(sheet_id: SheetId, start_col0: u32) -> Region {
        Region::cols_from(sheet_id, start_col0)
    }

    fn structural_dirty_region_for_domain(
        domain: &PlacementDomain,
        op: StructuralOp,
    ) -> Option<Region> {
        let (sheet_id, row_start, row_end, col_start, col_end) = match domain {
            PlacementDomain::RowRun {
                sheet_id,
                row_start,
                row_end,
                col,
            } => (*sheet_id, *row_start, *row_end, *col, *col),
            PlacementDomain::ColRun {
                sheet_id,
                row,
                col_start,
                col_end,
            } => (*sheet_id, *row, *row, *col_start, *col_end),
            PlacementDomain::Rect {
                sheet_id,
                row_start,
                row_end,
                col_start,
                col_end,
            } => (*sheet_id, *row_start, *row_end, *col_start, *col_end),
        };
        match op {
            StructuralOp::InsertRows {
                sheet_id: edited,
                before,
                ..
            } if sheet_id == edited && row_end >= before => Some(Region::rect(
                sheet_id,
                row_start.max(before),
                row_end,
                col_start,
                col_end,
            )),
            StructuralOp::DeleteRows {
                sheet_id: edited,
                start,
                ..
            } if sheet_id == edited && row_end >= start => Some(Region::rect(
                sheet_id,
                row_start.max(start),
                row_end,
                col_start,
                col_end,
            )),
            StructuralOp::InsertColumns {
                sheet_id: edited,
                before,
                ..
            } if sheet_id == edited && col_end >= before => Some(Region::rect(
                sheet_id,
                row_start,
                row_end,
                col_start.max(before),
                col_end,
            )),
            StructuralOp::DeleteColumns {
                sheet_id: edited,
                start,
                ..
            } if sheet_id == edited && col_end >= start => Some(Region::rect(
                sheet_id,
                row_start,
                row_end,
                col_start.max(start),
                col_end,
            )),
            _ => None,
        }
    }

    fn span_result_region_intersects_affected(
        span: &crate::formula_plane::runtime::FormulaSpan,
        affected_region: &Region,
    ) -> bool {
        Region::from_domain(span.result_region.domain()).intersects(affected_region)
    }

    fn span_any_read_region_intersects_affected(
        plane: &FormulaPlane,
        span: &crate::formula_plane::runtime::FormulaSpan,
        affected_region: &Region,
    ) -> bool {
        span.read_summary_id
            .and_then(|read_summary_id| plane.span_read_summaries.get(read_summary_id))
            .is_some_and(|summary| {
                summary
                    .dependencies
                    .iter()
                    .any(|dependency| dependency.read_region.intersects(affected_region))
            })
    }

    fn insert_formula_plane_dirty_coords_for_span(
        &self,
        span_ref: FormulaSpanRef,
        dirty: ProducerDirtyDomain,
        out: &mut FxHashSet<(SheetId, u32, u32)>,
    ) -> Result<(), crate::engine::EditorError> {
        let authority = self.graph.formula_authority();
        let span = authority.plane.spans.get(span_ref).ok_or_else(|| {
            ExcelError::new(ExcelErrorKind::NImpl)
                .with_message("FormulaPlane dirty transfer referenced a stale span")
        })?;
        match dirty {
            ProducerDirtyDomain::Whole => {
                out.extend(
                    span.domain
                        .iter()
                        .map(|coord| (coord.sheet_id, coord.row, coord.col)),
                );
            }
            ProducerDirtyDomain::Cells(cells) => {
                out.extend(cells.into_iter().filter_map(|key| {
                    let coord = PlacementCoord::new(key.sheet_id, key.row, key.col);
                    span.domain
                        .contains(coord)
                        .then_some((coord.sheet_id, coord.row, coord.col))
                }));
            }
            ProducerDirtyDomain::Regions(regions) => {
                out.extend(span.domain.iter().filter_map(|coord| {
                    let key = crate::formula_plane::region_index::RegionKey::from(coord);
                    regions
                        .iter()
                        .any(|region| region.contains_key(key))
                        .then_some((coord.sheet_id, coord.row, coord.col))
                }));
            }
        }
        Ok(())
    }

    fn compute_current_formula_plane_dirty_result_coords(
        &self,
    ) -> Result<FxHashSet<(SheetId, u32, u32)>, crate::engine::EditorError> {
        use crate::formula_plane::producer::compute_dirty_closure;

        let authority = self.graph.formula_authority();
        let span_refs = authority.active_span_refs();
        let span_refs_by_id = span_refs
            .iter()
            .copied()
            .map(|span_ref| (span_ref.id, span_ref))
            .collect::<BTreeMap<_, _>>();
        let mut dirty_coords = FxHashSet::default();

        for span_ref in self.graph.pending_formula_dirty_whole_spans() {
            if span_refs_by_id.get(&span_ref.id) == Some(&span_ref) {
                self.insert_formula_plane_dirty_coords_for_span(
                    span_ref,
                    ProducerDirtyDomain::Whole,
                    &mut dirty_coords,
                )?;
            }
        }
        for (span_ref, region) in self.graph.pending_formula_dirty_span_regions() {
            if span_refs_by_id.get(&span_ref.id) == Some(&span_ref) {
                self.insert_formula_plane_dirty_coords_for_span(
                    span_ref,
                    ProducerDirtyDomain::Regions(vec![region]),
                    &mut dirty_coords,
                )?;
            }
        }

        let pending_changed_regions = self
            .graph
            .pending_formula_dirty_regions()
            .collect::<Vec<_>>();
        if pending_changed_regions.is_empty() {
            return Ok(dirty_coords);
        }

        let closure = compute_dirty_closure(
            &authority.consumer_reads,
            pending_changed_regions,
            |producer| authority.producer_results.producer_result_region(producer),
        );
        if closure.incomplete {
            for span_ref in span_refs {
                self.insert_formula_plane_dirty_coords_for_span(
                    span_ref,
                    ProducerDirtyDomain::Whole,
                    &mut dirty_coords,
                )?;
            }
            return Ok(dirty_coords);
        }
        for work in closure.work {
            let FormulaProducerId::Span(span_id) = work.producer else {
                continue;
            };
            let Some(span_ref) = span_refs_by_id.get(&span_id).copied() else {
                continue;
            };
            self.insert_formula_plane_dirty_coords_for_span(
                span_ref,
                work.dirty,
                &mut dirty_coords,
            )?;
        }
        for fallback in closure.fallbacks {
            let FormulaProducerId::Span(span_id) = fallback.consumer else {
                continue;
            };
            let Some(span_ref) = span_refs_by_id.get(&span_id).copied() else {
                continue;
            };
            self.insert_formula_plane_dirty_coords_for_span(
                span_ref,
                ProducerDirtyDomain::Whole,
                &mut dirty_coords,
            )?;
        }

        Ok(dirty_coords)
    }

    /// Demote active FormulaPlane spans affected by a structural edit on `sheet_id`.
    ///
    /// This is the conservative Option-A correctness path for structural edits: rather than
    /// attempting to transform FormulaPlane span domains/templates/indexes, materialize each span
    /// placement as an ordinary legacy graph formula at its current coordinate, remove the span,
    /// and let the existing VertexEditor structural machinery shift/delete those vertices and
    /// adjust their ASTs.  Spans whose formula domain is on `sheet_id` are affected directly; spans
    /// on other sheets are also affected when one of their retained read regions targets
    /// `sheet_id`, because those read-region coordinates become stale after row/column shifts.
    fn demote_spans_for_structural_op(
        &mut self,
        op: StructuralOp,
        affected_region: Region,
    ) -> Result<(), crate::engine::EditorError> {
        if op.count() == 0 {
            return Ok(());
        }
        // #171: after an axis edit, retained read-summary relocation cannot be
        // used as a proof of disconnection. Fail closed for this engine.
        self.legacy_island_structural_summaries_trusted = false;
        self.demote_spans_for_structural_op_impl(Some(op), affected_region, true)
    }

    fn indexed_structural_candidate_span_refs(
        &self,
        affected_region: Region,
    ) -> Result<Vec<FormulaSpanRef>, crate::engine::EditorError> {
        use crate::formula_plane::region_index::BoundedRegionQueryResult;

        let authority = self.graph.formula_authority();
        if authority.indexed_plane_epoch() != authority.plane.epoch().0 {
            return Err(ExcelError::new(ExcelErrorKind::NImpl)
                .with_message("FormulaPlane structural candidate indexes are stale")
                .into());
        }
        let indexed_region = match affected_region.axis_ranges() {
            (
                crate::formula_plane::region_index::AxisRange::From(start),
                crate::formula_plane::region_index::AxisRange::All,
            ) => Region {
                sheet_id: affected_region.sheet_id(),
                rows: crate::formula_plane::region_index::AxisRange::Span(start, u32::MAX),
                cols: crate::formula_plane::region_index::AxisRange::All,
            },
            (
                crate::formula_plane::region_index::AxisRange::All,
                crate::formula_plane::region_index::AxisRange::From(start),
            ) => Region {
                sheet_id: affected_region.sheet_id(),
                rows: crate::formula_plane::region_index::AxisRange::All,
                cols: crate::formula_plane::region_index::AxisRange::Span(start, u32::MAX),
            },
            _ => affected_region,
        };
        let max_candidates = self.config.max_formula_plane_cache_candidates;
        let result_query = match authority
            .producer_results
            .query_bounded(indexed_region, max_candidates)
        {
            BoundedRegionQueryResult::Complete(result) => result,
            BoundedRegionQueryResult::Incomplete {
                observed_candidates,
            } => {
                return Err(ExcelError::new(ExcelErrorKind::NImpl)
                    .with_message(format!(
                        "FormulaPlane structural result candidate limit exceeded: observed {observed_candidates}, limit {max_candidates}"
                    ))
                    .into());
            }
        };
        let remaining = max_candidates.saturating_sub(result_query.matches.len());
        let read_query = match authority
            .consumer_reads
            .query_changed_region_bounded(indexed_region, remaining)
        {
            BoundedRegionQueryResult::Complete(result) => result,
            BoundedRegionQueryResult::Incomplete { .. } => {
                return Err(ExcelError::new(ExcelErrorKind::NImpl)
                    .with_message("FormulaPlane structural read candidate limit exceeded")
                    .into());
            }
        };

        let mut ids = BTreeSet::new();
        for matched in result_query.matches {
            if let FormulaProducerId::Span(id) = matched.value.producer {
                ids.insert(id);
            }
        }
        for matched in read_query.matches {
            if let FormulaProducerId::Span(id) = matched.value.consumer {
                ids.insert(id);
            }
        }

        ids.into_iter()
            .map(|id| {
                authority.plane.spans.current_ref(id).ok_or_else(|| {
                    crate::engine::EditorError::Excel(
                        ExcelError::new(ExcelErrorKind::NImpl)
                            .with_message("FormulaPlane structural index referenced a stale span"),
                    )
                })
            })
            .collect()
    }

    fn demote_spans_for_structural_op_impl(
        &mut self,
        op: Option<StructuralOp>,
        affected_region: Region,
        clear_computed_overlays: bool,
    ) -> Result<(), crate::engine::EditorError> {
        struct SpanPlan {
            span_ref: FormulaSpanRef,
            sheet_id: SheetId,
            ast: ASTNode,
            origin_row: u32,
            origin_col: u32,
            binding_set_id: Option<crate::formula_plane::runtime::SpanBindingSetId>,
            placements: Vec<(u32, u32)>,
        }

        fn substitute_literal_slots_for_template_placement(
            ast: &ASTNode,
            binding: &[LiteralValue],
        ) -> ASTNode {
            fn clone_with_slots(
                ast: &ASTNode,
                binding: &[LiteralValue],
                next: &mut usize,
                in_array: bool,
            ) -> ASTNode {
                let node_type = match &ast.node_type {
                    ASTNodeType::Literal(_) if !in_array => {
                        let value = binding.get(*next).cloned().unwrap_or(LiteralValue::Empty);
                        *next = next.saturating_add(1);
                        ASTNodeType::Literal(value)
                    }
                    ASTNodeType::Literal(value) => ASTNodeType::Literal(value.clone()),
                    ASTNodeType::Omitted => ASTNodeType::Omitted,
                    ASTNodeType::Reference {
                        original,
                        reference,
                    } => ASTNodeType::Reference {
                        original: original.clone(),
                        reference: reference.clone(),
                    },
                    ASTNodeType::UnaryOp { op, expr } => ASTNodeType::UnaryOp {
                        op: op.clone(),
                        expr: Box::new(clone_with_slots(expr, binding, next, in_array)),
                    },
                    ASTNodeType::BinaryOp { op, left, right } => ASTNodeType::BinaryOp {
                        op: op.clone(),
                        left: Box::new(clone_with_slots(left, binding, next, in_array)),
                        right: Box::new(clone_with_slots(right, binding, next, in_array)),
                    },
                    ASTNodeType::Function { name, args } => ASTNodeType::Function {
                        name: name.clone(),
                        args: args
                            .iter()
                            .map(|arg| clone_with_slots(arg, binding, next, in_array))
                            .collect(),
                    },
                    ASTNodeType::Call { callee, args } => ASTNodeType::Call {
                        callee: Box::new(clone_with_slots(callee, binding, next, in_array)),
                        args: args
                            .iter()
                            .map(|arg| clone_with_slots(arg, binding, next, in_array))
                            .collect(),
                    },
                    ASTNodeType::Array(rows) => ASTNodeType::Array(
                        rows.iter()
                            .map(|row| {
                                row.iter()
                                    .map(|cell| clone_with_slots(cell, binding, next, true))
                                    .collect()
                            })
                            .collect(),
                    ),
                };
                ASTNode::new(node_type, ast.source_token.clone())
            }
            let mut next = 0usize;
            clone_with_slots(ast, binding, &mut next, false)
        }

        let span_refs = self.indexed_structural_candidate_span_refs(affected_region)?;
        self.formula_plane_structural_span_candidates = self
            .formula_plane_structural_span_candidates
            .saturating_add(span_refs.len() as u64);
        if span_refs.is_empty() {
            return Ok(());
        }
        let dirty_span_coords = if clear_computed_overlays {
            FxHashSet::default()
        } else {
            self.compute_current_formula_plane_dirty_result_coords()?
        };

        /// A template AST rewrite accompanying a span shift: the op displaced
        /// the target of an absolute read, which origin relocation cannot
        /// repoint (issue #168). The adjusted AST is re-interned as a fresh
        /// arena AST + template record at the apply site; keys are re-derived
        /// from the rewritten AST so the new record can never collide with
        /// the (immutable, possibly shared) pre-rewrite template.
        struct SpanTemplateRewrite {
            adjusted_ast: ASTNode,
            exact_canonical_key: Arc<str>,
            parameterized_canonical_key: Arc<str>,
            formula_text: Option<Arc<str>>,
            /// Canonical form of the rewritten AST at the new origin, used to
            /// rebuild the binding set's template-derived slot data (the
            /// literal slot map is keyed by arena node ids of the template
            /// AST; value-ref slot patterns carry canonical reference
            /// coordinates — both go stale across a rewrite).
            canonical_expr: crate::formula_plane::template_canonical::CanonicalExpr,
            value_ref_slots: Arc<[crate::formula_plane::runtime::ValueRefSlotDescriptor]>,
        }

        struct ShiftPlan {
            span_ref: FormulaSpanRef,
            template_id: crate::formula_plane::ids::FormulaTemplateId,
            new_origin_row: u32,
            new_origin_col: u32,
            new_domain: crate::formula_plane::runtime::PlacementDomain,
            new_read_summary: Option<SpanReadSummary>,
            binding_set_id: Option<crate::formula_plane::runtime::SpanBindingSetId>,
            force_binding_residual_axes: bool,
            rewrite: Option<SpanTemplateRewrite>,
            dirty_region: Option<Region>,
        }

        /// StructuralOp and ShiftOperation are field-for-field identical
        /// (both 0-based); the adjuster type is the legacy shared one.
        fn shift_operation_for(
            op: StructuralOp,
        ) -> crate::engine::graph::editor::reference_adjuster::ShiftOperation {
            use crate::engine::graph::editor::reference_adjuster::ShiftOperation;
            match op {
                StructuralOp::InsertRows {
                    sheet_id,
                    before,
                    count,
                } => ShiftOperation::InsertRows {
                    sheet_id,
                    before,
                    count,
                },
                StructuralOp::DeleteRows {
                    sheet_id,
                    start,
                    count,
                } => ShiftOperation::DeleteRows {
                    sheet_id,
                    start,
                    count,
                },
                StructuralOp::InsertColumns {
                    sheet_id,
                    before,
                    count,
                } => ShiftOperation::InsertColumns {
                    sheet_id,
                    before,
                    count,
                },
                StructuralOp::DeleteColumns {
                    sheet_id,
                    start,
                    count,
                } => ShiftOperation::DeleteColumns {
                    sheet_id,
                    start,
                    count,
                },
            }
        }

        /// Split a straddled span into an unshifted upper half (which keeps the
        /// span id via `replace_span_geometry`) and a shifted lower half (a
        /// fresh span). Domains and origins here are POST-insert for the lower
        /// half, mirroring `ShiftPlan`.
        struct SplitPlan {
            span_ref: FormulaSpanRef,
            sheet_id: SheetId,
            template_id: crate::formula_plane::ids::FormulaTemplateId,
            binding_set_id: Option<crate::formula_plane::runtime::SpanBindingSetId>,
            is_constant_result: bool,
            upper_domain: crate::formula_plane::runtime::PlacementDomain,
            upper_read_summary: Option<SpanReadSummary>,
            lower_new_origin_row: u32,
            lower_new_origin_col: u32,
            lower_new_domain: crate::formula_plane::runtime::PlacementDomain,
            lower_new_read_summary: Option<SpanReadSummary>,
            lower_force_binding_residual_axes: bool,
            lower_overlay_refs: Vec<crate::formula_plane::runtime::FormulaOverlayRef>,
            upper_dirty_region: Option<Region>,
            lower_dirty_region: Option<Region>,
        }

        fn checked_shift_u32(value: u32, delta: i64) -> Option<u32> {
            u32::try_from(i64::from(value).checked_add(delta)?).ok()
        }

        /// Structural transform of a read summary for a NO-REWRITE shift.
        /// Regions move with the op; projection rules keep their absolute
        /// bounds (the AST is untouched) but must shift their RELATIVE
        /// bounds by `-origin_delta`: rules store placement-relative
        /// offsets, which equal `authored_coordinate - template_origin`,
        /// and a moved origin over an unchanged AST changes that difference
        /// (otherwise incremental dirty projection silently goes stale —
        /// issue #168 family). Rewrite plans do NOT use this transform;
        /// their summaries are re-derived from the rewritten canonical
        /// template instead.
        fn shifted_read_summary(
            read_summary: &SpanReadSummary,
            new_result_region: Region,
            op: StructuralOp,
            row_delta: i64,
            col_delta: i64,
            origin_row_delta: i64,
            origin_col_delta: i64,
        ) -> Option<SpanReadSummary> {
            let mut dependencies = Vec::with_capacity(read_summary.dependencies.len());
            for dependency in &read_summary.dependencies {
                let read_region = match op.classify_region(dependency.read_region) {
                    crate::formula_plane::structural_shift::AxisShiftCase::OtherSheet
                    | crate::formula_plane::structural_shift::AxisShiftCase::EntirelyBelow => {
                        dependency.read_region
                    }
                    crate::formula_plane::structural_shift::AxisShiftCase::EntirelyAboveShift {
                        ..
                    } => dependency
                        .read_region
                        .project_through_axis_shift(row_delta, col_delta)?,
                    crate::formula_plane::structural_shift::AxisShiftCase::Straddles
                    | crate::formula_plane::structural_shift::AxisShiftCase::DeleteFullyContains => {
                        return None;
                    }
                };
                dependencies.push(crate::formula_plane::producer::SpanReadDependency {
                    read_region,
                    projection: dependency
                        .projection
                        .with_relative_offsets_shifted(-origin_row_delta, -origin_col_delta),
                });
            }
            Some(SpanReadSummary {
                result_region: new_result_region,
                dependencies,
            })
        }

        fn compact_axis_through_delete(
            min: u32,
            max: u32,
            start: u32,
            count: u32,
        ) -> Option<(u32, u32)> {
            let end = start.saturating_add(count);
            if max < start || min >= end {
                return Some((min.saturating_sub(count), max.saturating_sub(count)));
            }
            let keeps_left = min < start;
            let keeps_right = max >= end;
            match (keeps_left, keeps_right) {
                (false, false) => None,
                (true, false) => Some((min, start.checked_sub(1)?)),
                (false, true) => Some((start, max.checked_sub(count)?)),
                (true, true) => Some((min, max.checked_sub(count)?)),
            }
        }

        fn compact_domain_through_delete(
            domain: &PlacementDomain,
            op: StructuralOp,
        ) -> Option<PlacementDomain> {
            match (domain, op) {
                (
                    PlacementDomain::RowRun {
                        sheet_id,
                        row_start,
                        row_end,
                        col,
                    },
                    StructuralOp::DeleteRows { start, count, .. },
                ) => {
                    let (row_start, row_end) =
                        compact_axis_through_delete(*row_start, *row_end, start, count)?;
                    Some(PlacementDomain::row_run(
                        *sheet_id, row_start, row_end, *col,
                    ))
                }
                (
                    PlacementDomain::Rect {
                        sheet_id,
                        row_start,
                        row_end,
                        col_start,
                        col_end,
                    },
                    StructuralOp::DeleteRows { start, count, .. },
                ) => {
                    let (row_start, row_end) =
                        compact_axis_through_delete(*row_start, *row_end, start, count)?;
                    Some(PlacementDomain::rect(
                        *sheet_id, row_start, row_end, *col_start, *col_end,
                    ))
                }
                (
                    PlacementDomain::ColRun {
                        sheet_id,
                        row,
                        col_start,
                        col_end,
                    },
                    StructuralOp::DeleteColumns { start, count, .. },
                ) => {
                    let (col_start, col_end) =
                        compact_axis_through_delete(*col_start, *col_end, start, count)?;
                    Some(PlacementDomain::col_run(
                        *sheet_id, *row, col_start, col_end,
                    ))
                }
                (
                    PlacementDomain::Rect {
                        sheet_id,
                        row_start,
                        row_end,
                        col_start,
                        col_end,
                    },
                    StructuralOp::DeleteColumns { start, count, .. },
                ) => {
                    let (col_start, col_end) =
                        compact_axis_through_delete(*col_start, *col_end, start, count)?;
                    Some(PlacementDomain::rect(
                        *sheet_id, *row_start, *row_end, col_start, col_end,
                    ))
                }
                _ => None,
            }
        }

        fn compact_axis_range_through_delete(
            axis: crate::formula_plane::region_index::AxisRange,
            start: u32,
            count: u32,
        ) -> Option<crate::formula_plane::region_index::AxisRange> {
            use crate::formula_plane::region_index::AxisRange;
            match axis {
                AxisRange::Point(point) => compact_axis_through_delete(point, point, start, count)
                    .map(|(point, _)| AxisRange::Point(point)),
                AxisRange::Span(min, max) => compact_axis_through_delete(min, max, start, count)
                    .map(|(min, max)| AxisRange::Span(min, max)),
                AxisRange::All => Some(AxisRange::All),
                AxisRange::From(_) | AxisRange::To(_) => None,
            }
        }

        fn compact_region_through_delete(region: Region, op: StructuralOp) -> Option<Region> {
            let (rows, cols) = region.axis_ranges();
            match op {
                StructuralOp::DeleteRows {
                    sheet_id,
                    start,
                    count,
                } if region.sheet_id() == sheet_id => Some(Region {
                    sheet_id,
                    rows: compact_axis_range_through_delete(rows, start, count)?,
                    cols,
                }),
                StructuralOp::DeleteColumns {
                    sheet_id,
                    start,
                    count,
                } if region.sheet_id() == sheet_id => Some(Region {
                    sheet_id,
                    rows,
                    cols: compact_axis_range_through_delete(cols, start, count)?,
                }),
                _ => Some(region),
            }
        }

        fn compact_read_summary_through_delete(
            read_summary: &SpanReadSummary,
            new_result_region: Region,
            op: StructuralOp,
        ) -> Option<SpanReadSummary> {
            let mut dependencies = Vec::with_capacity(read_summary.dependencies.len());
            for dependency in &read_summary.dependencies {
                let read_region = match op.classify_region(dependency.read_region) {
                    crate::formula_plane::structural_shift::AxisShiftCase::OtherSheet
                    | crate::formula_plane::structural_shift::AxisShiftCase::EntirelyBelow => {
                        dependency.read_region
                    }
                    crate::formula_plane::structural_shift::AxisShiftCase::EntirelyAboveShift {
                        ..
                    } => {
                        let (row_delta, col_delta) = op.axis_shift_delta();
                        dependency
                            .read_region
                            .project_through_axis_shift(row_delta, col_delta)?
                    }
                    crate::formula_plane::structural_shift::AxisShiftCase::Straddles => {
                        compact_region_through_delete(dependency.read_region, op)?
                    }
                    crate::formula_plane::structural_shift::AxisShiftCase::DeleteFullyContains => {
                        return None;
                    }
                };
                dependencies.push(crate::formula_plane::producer::SpanReadDependency {
                    read_region,
                    projection: dependency.projection,
                });
            }
            Some(SpanReadSummary {
                result_region: new_result_region,
                dependencies,
            })
        }

        /// Re-derive a span read summary for a sub-domain of the original
        /// result region by replaying each retained projection rule against
        /// the half's result region — the same derivation ingest performs in
        /// `SpanReadSummary::from_formula_summary`, minus the dependency
        /// re-analysis. Returns None (caller demotes) when any rule cannot
        /// produce explicit read regions.
        fn rederive_read_summary_for_result(
            read_summary: &SpanReadSummary,
            result_region: Region,
        ) -> Option<SpanReadSummary> {
            let mut dependencies = Vec::with_capacity(read_summary.dependencies.len());
            for dependency in &read_summary.dependencies {
                let sheet_id = dependency.read_region.sheet_id();
                let read_regions = dependency
                    .projection
                    .read_regions_for_result(sheet_id, result_region)
                    .ok()?;
                for read_region in read_regions {
                    let dependency = crate::formula_plane::producer::SpanReadDependency {
                        read_region,
                        projection: dependency.projection,
                    };
                    if !dependencies.contains(&dependency) {
                        dependencies.push(dependency);
                    }
                }
            }
            Some(SpanReadSummary {
                result_region,
                dependencies,
            })
        }

        /// Plan a conservative span split for a mid-domain insert. Returns
        /// None whenever the split is not provably clean — missing template,
        /// masked span, non-trivial literal bindings, an unsplittable domain,
        /// a half that does not re-classify to NoOp (upper) / Shift (lower),
        /// or an overlay punch-out that straddles the boundary — in which case
        /// the caller falls back to demoting the whole span.
        fn plan_span_split(
            authority: &crate::formula_plane::authority::FormulaAuthority,
            span: &crate::formula_plane::runtime::FormulaSpan,
            span_ref: FormulaSpanRef,
            read_summary: Option<&SpanReadSummary>,
            op: StructuralOp,
        ) -> Option<SplitPlan> {
            use crate::formula_plane::structural_shift::{AxisShiftCase, split_domain_at};

            if span.intrinsic_mask_id.is_some() {
                // v1 does not slice intrinsic masks.
                return None;
            }
            let binding_set = span
                .binding_set_id
                .and_then(|id| authority.plane.binding_sets.get(id));
            if binding_set.is_some_and(|binding_set| !binding_set.is_single_literal_binding()) {
                // Dictionary/affine per-placement literal bindings are keyed by
                // domain ordinal; splitting re-bases the lower half's ordinals.
                // Only trivially-uniform bindings are safe to carry across.
                return None;
            }

            let (upper_domain, lower_domain) = split_domain_at(&span.domain, op)?;
            let upper_result_region = Region::from_domain(&upper_domain);
            let lower_result_region = Region::from_domain(&lower_domain);
            let (upper_read_summary, lower_read_summary) = match read_summary {
                Some(summary) => (
                    Some(rederive_read_summary_for_result(
                        summary,
                        upper_result_region,
                    )?),
                    Some(rederive_read_summary_for_result(
                        summary,
                        lower_result_region,
                    )?),
                ),
                None => (None, None),
            };

            // Re-classify each half in the pre-insert frame. The upper half
            // must be a strict no-op (unshifted result, unshifted reads); the
            // lower half must be a clean whole-span shift.
            let upper_span = crate::formula_plane::runtime::FormulaSpan {
                domain: upper_domain.clone(),
                result_region: ResultRegion::scalar_cells(upper_domain.clone()),
                ..span.clone()
            };
            if classify_span_for_op(&upper_span, upper_read_summary.as_ref(), op)
                != SpanShiftPlan::NoOp
            {
                return None;
            }
            let lower_span = crate::formula_plane::runtime::FormulaSpan {
                domain: lower_domain.clone(),
                result_region: ResultRegion::scalar_cells(lower_domain.clone()),
                ..span.clone()
            };
            let SpanShiftPlan::Shift {
                row_delta,
                col_delta,
                origin_row_delta,
                origin_col_delta,
                rewrite_absolute_reads,
            } = classify_span_for_op(&lower_span, lower_read_summary.as_ref(), op)
            else {
                return None;
            };
            if rewrite_absolute_reads {
                // A displaced absolute read in the lower half implies the
                // upper half reads it too and cannot be a NoOp, so this is
                // unreachable when the upper check above passed; keep the
                // guard so a future classifier change cannot silently skip
                // the template rewrite.
                return None;
            }

            // Span relocation is the ownership boundary for demotion and
            // formula lookup. Canonically shared templates may have a different
            // authoring origin, so never derive split provenance from them.
            let lower_new_origin_row =
                checked_shift_u32(span.ast_relocation.anchor_row, origin_row_delta)?;
            let lower_new_origin_col =
                checked_shift_u32(span.ast_relocation.anchor_col, origin_col_delta)?;
            let lower_new_domain = lower_domain.project_through_axis_shift(row_delta, col_delta)?;
            let lower_new_result_region = Region::from_domain(&lower_new_domain);
            let lower_new_read_summary = match lower_read_summary.as_ref() {
                Some(summary) => Some(shifted_read_summary(
                    summary,
                    lower_new_result_region,
                    op,
                    row_delta,
                    col_delta,
                    origin_row_delta,
                    origin_col_delta,
                )?),
                None => None,
            };

            // Overlay punch-outs sourced from this span: entries entirely
            // before the boundary stay with the (id-retaining) upper half;
            // entries at/after the boundary transfer to the new lower span.
            // A straddling entry means the split is not clean.
            let mut lower_overlay_refs = Vec::new();
            for overlay_ref in authority
                .plane
                .formula_overlay
                .refs_for_source_span(span_ref)
            {
                let entry = authority.plane.formula_overlay.get(overlay_ref)?;
                match op.classify_region(Region::from_domain(&entry.domain)) {
                    AxisShiftCase::OtherSheet | AxisShiftCase::EntirelyBelow => {}
                    AxisShiftCase::EntirelyAboveShift { .. } => {
                        lower_overlay_refs.push(overlay_ref);
                    }
                    AxisShiftCase::Straddles | AxisShiftCase::DeleteFullyContains => {
                        return None;
                    }
                }
            }

            let lower_force_binding_residual_axes = binding_set.is_some_and(|binding_set| {
                !binding_set.value_ref_slots.is_empty()
                    && (origin_row_delta != 0 || origin_col_delta != 0)
            });

            Some(SplitPlan {
                span_ref,
                sheet_id: span.sheet_id,
                template_id: span.template_id,
                binding_set_id: span.binding_set_id,
                is_constant_result: span.is_constant_result,
                upper_domain,
                upper_read_summary,
                lower_new_origin_row,
                lower_new_origin_col,
                lower_new_domain,
                lower_new_read_summary,
                lower_force_binding_residual_axes,
                lower_overlay_refs,
                upper_dirty_region: None,
                lower_dirty_region: None,
            })
        }

        /// Carry a 1-based template origin coordinate through a delete of
        /// `count` rows/columns starting at 0-based `start`. Returns None when
        /// the delete removes the origin coordinate itself: the template's
        /// relative reference deltas are anchored there, so the caller must
        /// demote rather than guess a new anchor.
        fn origin_coord_through_delete(origin: u32, start: u32, count: u32) -> Option<u32> {
            let origin0 = origin.checked_sub(1)?;
            let end = start.saturating_add(count);
            if origin0 < start {
                Some(origin)
            } else if origin0 >= end {
                Some(origin - count)
            } else {
                None
            }
        }

        /// Carry the template origin through a delete instead of rebasing it
        /// to the compacted domain's start. Rebasing is only correct when the
        /// origin coincides with the domain start; split/shifted spans keep
        /// their original origin (Shift{origin_delta: 0} convention), and a
        /// head-overlapping delete moves the domain start away from the
        /// origin, so rebasing silently re-anchors every relative read.
        fn origin_through_delete(
            origin_row: u32,
            origin_col: u32,
            op: StructuralOp,
        ) -> Option<(u32, u32)> {
            match op {
                StructuralOp::DeleteRows { start, count, .. } => Some((
                    origin_coord_through_delete(origin_row, start, count)?,
                    origin_col,
                )),
                StructuralOp::DeleteColumns { start, count, .. } => Some((
                    origin_row,
                    origin_coord_through_delete(origin_col, start, count)?,
                )),
                StructuralOp::InsertRows { .. } | StructuralOp::InsertColumns { .. } => None,
            }
        }

        let mut shift_plans = Vec::new();
        let mut split_plans = Vec::new();
        let mut remove_refs = Vec::new();
        let mut demote_refs = Vec::new();
        for span_ref in span_refs {
            let authority = self.graph.formula_authority();
            let Some(span) = authority.plane.spans.get(span_ref) else {
                continue;
            };
            let read_summary = span
                .read_summary_id
                .and_then(|id| authority.plane.span_read_summaries.get(id));
            let Some(op) = op else {
                // Non-structural demote path (per-cell write into span, or
                // remove_sheet's whole-sheet sweep). Only demote spans whose
                // result or read region intersects affected_region; leave
                // disjoint spans untouched.
                let result_region_affected =
                    Self::span_result_region_intersects_affected(span, &affected_region);
                let read_region_affected = Self::span_any_read_region_intersects_affected(
                    &authority.plane,
                    span,
                    &affected_region,
                );
                if result_region_affected || read_region_affected {
                    demote_refs.push(span_ref);
                }
                continue;
            };
            match classify_span_for_op(span, read_summary, op) {
                SpanShiftPlan::NoOp => {}
                SpanShiftPlan::Remove => {
                    remove_refs.push(span_ref);
                }
                SpanShiftPlan::Demote {
                    reason:
                        crate::formula_plane::structural_shift::SpanDemoteReason::DeletePartiallyOverlaps,
                } => {
                    let binding_compaction_safe = span
                        .binding_set_id
                        .and_then(|id| authority.plane.binding_sets.get(id))
                        .is_none_or(|binding_set| binding_set.is_single_literal_binding());
                    // Compaction projects read regions through the delete but
                    // keeps the template AST: an absolute read whose target
                    // the delete displaces would keep its stale coordinate
                    // (issue #168), so demote to the per-cell path instead.
                    let absolute_reads_compaction_safe = read_summary.is_none_or(|summary| {
                        !crate::formula_plane::structural_shift::summary_has_displaced_absolute_read(
                            summary, op,
                        )
                    });
                    if binding_compaction_safe
                        && absolute_reads_compaction_safe
                        && let Some(new_domain) = compact_domain_through_delete(&span.domain, op)
                    {
                        let new_result_region = Region::from_domain(&new_domain);
                        let new_read_summary = if let Some(summary) = read_summary {
                            compact_read_summary_through_delete(summary, new_result_region, op)
                        } else {
                            None
                        };
                        let Some(template) = authority.plane.templates.get(span.template_id) else {
                            return Err(ExcelError::new(ExcelErrorKind::Ref)
                                .with_message(
                                    "FormulaPlane delete compaction found a span with a missing template",
                                )
                                .into());
                        };
                        let carried_origin =
                            origin_through_delete(template.origin_row, template.origin_col, op);
                        if (read_summary.is_none() || new_read_summary.is_some())
                            && let Some((new_origin_row, new_origin_col)) = carried_origin
                        {
                            let force_binding_residual_axes = span
                                .binding_set_id
                                .and_then(|id| authority.plane.binding_sets.get(id))
                                .is_some_and(|binding_set| {
                                    !binding_set.value_ref_slots.is_empty()
                                        && (new_origin_row != template.origin_row
                                            || new_origin_col != template.origin_col)
                                });
                            let dirty_region =
                                Self::structural_dirty_region_for_domain(&new_domain, op);
                            shift_plans.push(ShiftPlan {
                                span_ref,
                                template_id: span.template_id,
                                new_origin_row,
                                new_origin_col,
                                new_domain,
                                new_read_summary,
                                binding_set_id: span.binding_set_id,
                                force_binding_residual_axes,
                                rewrite: None,
                                dirty_region,
                            });
                        } else {
                            demote_refs.push(span_ref);
                        }
                    } else {
                        demote_refs.push(span_ref);
                    }
                }
                SpanShiftPlan::Demote { .. } => {
                    demote_refs.push(span_ref);
                }
                SpanShiftPlan::Split => {
                    match plan_span_split(authority, span, span_ref, read_summary, op) {
                        Some(mut plan) => {
                            plan.upper_dirty_region =
                                Self::structural_dirty_region_for_domain(&plan.upper_domain, op);
                            plan.lower_dirty_region = Self::structural_dirty_region_for_domain(
                                &plan.lower_new_domain,
                                op,
                            );
                            split_plans.push(plan);
                        }
                        // Not provably clean: demote the whole span (the
                        // pre-split conservative path).
                        None => demote_refs.push(span_ref),
                    }
                }
                SpanShiftPlan::Shift {
                    row_delta,
                    col_delta,
                    origin_row_delta,
                    origin_col_delta,
                    rewrite_absolute_reads,
                } => {
                    let Some(template) = authority.plane.templates.get(span.template_id) else {
                        return Err(ExcelError::new(ExcelErrorKind::Ref)
                            .with_message("FormulaPlane shift found a span with a missing template")
                            .into());
                    };
                    let Some(new_origin_row) =
                        checked_shift_u32(template.origin_row, origin_row_delta)
                    else {
                        return Err(ExcelError::new(ExcelErrorKind::Ref)
                            .with_message("FormulaPlane shift overflowed template origin row")
                            .into());
                    };
                    let Some(new_origin_col) =
                        checked_shift_u32(template.origin_col, origin_col_delta)
                    else {
                        return Err(ExcelError::new(ExcelErrorKind::Ref)
                            .with_message("FormulaPlane shift overflowed template origin column")
                            .into());
                    };
                    let Some(new_domain) =
                        span.domain.project_through_axis_shift(row_delta, col_delta)
                    else {
                        return Err(ExcelError::new(ExcelErrorKind::Ref)
                            .with_message("FormulaPlane shift overflowed span domain")
                            .into());
                    };
                    let new_result_region = Region::from_domain(&new_domain);
                    let force_binding_residual_axes = span
                        .binding_set_id
                        .and_then(|id| authority.plane.binding_sets.get(id))
                        .is_some_and(|binding_set| {
                            !binding_set.value_ref_slots.is_empty()
                                && (origin_row_delta != 0 || origin_col_delta != 0)
                        });
                    let rewrite_and_summary = if rewrite_absolute_reads {
                        // Reify the (immutable, possibly shared) template
                        // AST and repoint its displaced references through
                        // the shared adjuster — the same relocation the
                        // per-cell path applies, so span-ON stays equal to
                        // span-OFF (issue #168). Canonical keys are
                        // re-derived from the rewritten AST at the new
                        // origin, so the fresh record cannot collide with
                        // the pre-rewrite template.
                        //
                        // FRAME GUARD: the adjuster relocates by AUTHORED
                        // coordinate, but a template's authoring frame may
                        // diverge from its domain (split lower halves keep
                        // the original anchor; pinned-origin shifts move the
                        // domain without the origin). The rewrite is only
                        // equivalent to per-cell adjustment when every
                        // relative read's authored coordinate classifies
                        // against the op boundary the same way its read
                        // region does — otherwise the rewrite shears
                        // relative reads by the op count. Demote instead;
                        // see rewrite_frame_is_sound for the full invariant.
                        let frame_sound = read_summary.is_some_and(|summary| {
                            crate::formula_plane::structural_shift::rewrite_frame_is_sound(
                                summary,
                                template.origin_row,
                                template.origin_col,
                                op,
                            )
                        });
                        if !frame_sound {
                            demote_refs.push(span_ref);
                            continue;
                        }
                        let Some(ast) = self
                            .graph
                            .data_store()
                            .retrieve_ast(template.ast_id, self.graph.sheet_reg())
                        else {
                            demote_refs.push(span_ref);
                            continue;
                        };
                        let shift_op = shift_operation_for(op);
                        let adjuster =
                            crate::engine::graph::editor::reference_adjuster::ReferenceAdjuster::new();
                        let context = crate::engine::graph::editor::reference_adjuster::ReferenceContext::new(
                            span.sheet_id,
                            self.graph.sheet_reg(),
                        );
                        let Some(adjusted_ast) =
                            adjuster.adjust_ast_if_changed_in_context(&ast, &shift_op, &context)
                        else {
                            // The classifier saw a displaced absolute read,
                            // so an unchanged AST is a contract violation;
                            // demote conservatively rather than shift with a
                            // stale template.
                            demote_refs.push(span_ref);
                            continue;
                        };
                        let canonical = crate::formula_plane::template_canonical::canonicalize_template(
                            &adjusted_ast,
                            new_origin_row,
                            new_origin_col,
                        );
                        if !canonical.labels.is_authority_supported() {
                            demote_refs.push(span_ref);
                            continue;
                        }
                        // The rewrite touches only references; the literal
                        // slot layout must survive unchanged or the binding
                        // set's per-placement literal bindings no longer
                        // line up. Demote defensively if it differs.
                        let literal_slots_compatible = span
                            .binding_set_id
                            .and_then(|id| authority.plane.binding_sets.get(id))
                            .is_none_or(|binding_set| {
                                binding_set.literal_slots.as_ref()
                                    == canonical.literal_slot_descriptors.as_ref()
                            });
                        if !literal_slots_compatible {
                            demote_refs.push(span_ref);
                            continue;
                        }
                        // Value-ref slot patterns are re-derived from the
                        // rewritten canonical template so memoized reads
                        // resolve the repointed coordinates (issue #168).
                        // Placement-relative memo KEYS are additionally
                        // protected by force_binding_residual_axes below
                        // (the rewrite always moves the origin, so the
                        // existing origin-delta condition fires).
                        let value_ref_slots = Arc::from(
                            crate::formula_plane::placement::value_ref_slot_descriptors(
                                &canonical.expr,
                            )
                            .into_boxed_slice(),
                        );
                        // The read summary is RE-DERIVED from the rewritten
                        // canonical template rather than structurally
                        // transformed: a structural transform would keep the
                        // old projection rules, whose absolute indices (and
                        // relative offsets, via the moved origin) no longer
                        // match the rewritten AST — incremental writes to
                        // the repointed targets would then silently fail to
                        // dirty the span. Re-derivation rebuilds rules in
                        // the (rewritten AST, new origin) frame, keeping
                        // `result_region == domain region` by construction.
                        let dependency_summary =
                            crate::formula_plane::dependency_summary::summarize_canonical_template(
                                &canonical,
                            );
                        let rewritten_result_region =
                            ResultRegion::scalar_cells(new_domain.clone());
                        let Ok(rederived_summary) = SpanReadSummary::from_formula_summary(
                            span.sheet_id,
                            &rewritten_result_region,
                            &dependency_summary,
                            self.graph.sheet_reg(),
                        ) else {
                            demote_refs.push(span_ref);
                            continue;
                        };
                        let formula_text = Some(Arc::<str>::from(
                            formualizer_parse::pretty::canonical_formula(&adjusted_ast),
                        ));
                        Some((
                            SpanTemplateRewrite {
                                exact_canonical_key: Arc::<str>::from(canonical.key.payload()),
                                parameterized_canonical_key: Arc::<str>::from(
                                    canonical.parameterized_key.payload(),
                                ),
                                formula_text,
                                canonical_expr: canonical.expr,
                                value_ref_slots,
                                adjusted_ast,
                            },
                            rederived_summary,
                        ))
                    } else {
                        None
                    };
                    let (rewrite, new_read_summary) = match rewrite_and_summary {
                        Some((rewrite, summary)) => (Some(rewrite), Some(summary)),
                        None => {
                            let new_read_summary = if let Some(summary) = read_summary {
                                Some(
                                    shifted_read_summary(
                                        summary,
                                        new_result_region,
                                        op,
                                        row_delta,
                                        col_delta,
                                        origin_row_delta,
                                        origin_col_delta,
                                    )
                                    .ok_or_else(|| {
                                        ExcelError::new(ExcelErrorKind::Ref).with_message(
                                            "FormulaPlane shift could not project read summary",
                                        )
                                    })?,
                                )
                            } else {
                                None
                            };
                            (None, new_read_summary)
                        }
                    };
                    let dirty_region = Self::structural_dirty_region_for_domain(&new_domain, op);
                    shift_plans.push(ShiftPlan {
                        span_ref,
                        template_id: span.template_id,
                        new_origin_row,
                        new_origin_col,
                        new_domain,
                        new_read_summary,
                        binding_set_id: span.binding_set_id,
                        force_binding_residual_axes,
                        rewrite,
                        dirty_region,
                    });
                }
            }
        }
        let span_geometry_changed =
            !shift_plans.is_empty() || !split_plans.is_empty() || !remove_refs.is_empty();
        let mut span_dirty_deltas = Vec::new();
        if span_geometry_changed {
            // Rewritten template ASTs must be interned into the graph's AST
            // arena before the authority is borrowed mutably; the literal
            // slot map is keyed by the freshly interned arena node ids.
            let mut prepared_shift_plans = Vec::with_capacity(shift_plans.len());
            for plan in shift_plans {
                let rewrite_prepared = plan.rewrite.as_ref().map(|rewrite| {
                    let ast_id = self.graph.store_ast(&rewrite.adjusted_ast);
                    let template_slot_map =
                        crate::formula_plane::placement::build_template_slot_map(
                            ast_id,
                            self.graph.data_store(),
                            &rewrite.canonical_expr,
                        );
                    (ast_id, template_slot_map)
                });
                prepared_shift_plans.push((plan, rewrite_prepared));
            }
            let authority = self.graph.formula_authority_mut();
            for span_ref in remove_refs {
                authority.plane.remove_overlays_for_source_span(span_ref);
                authority.plane.remove_span(span_ref);
            }
            for (plan, rewrite_prepared) in prepared_shift_plans {
                let dirty_region = plan.dirty_region;
                let (template_id, rewrite_slots) = if let Some(rewrite) = plan.rewrite {
                    let Some((ast_id, template_slot_map)) = rewrite_prepared else {
                        return Err(ExcelError::new(ExcelErrorKind::Ref)
                            .with_message("FormulaPlane shift lost a rewritten template AST")
                            .into());
                    };
                    let Some(template_id) = authority.plane.intern_rewritten_template(
                        plan.template_id,
                        ast_id,
                        rewrite.exact_canonical_key,
                        rewrite.parameterized_canonical_key,
                        rewrite.formula_text,
                        plan.new_origin_row,
                        plan.new_origin_col,
                    ) else {
                        return Err(ExcelError::new(ExcelErrorKind::Ref)
                            .with_message("FormulaPlane shift could not intern rewritten template")
                            .into());
                    };
                    (
                        template_id,
                        Some((template_slot_map, rewrite.value_ref_slots)),
                    )
                } else {
                    let Some(template_id) = authority.plane.intern_shifted_template_origin(
                        plan.template_id,
                        plan.new_origin_row,
                        plan.new_origin_col,
                    ) else {
                        return Err(ExcelError::new(ExcelErrorKind::Ref)
                            .with_message("FormulaPlane shift could not clone template origin")
                            .into());
                    };
                    (template_id, None)
                };
                if let Some((template_slot_map, value_ref_slots)) = rewrite_slots
                    && let Some(binding_set_id) = plan.binding_set_id
                {
                    authority.plane.set_binding_template_slots(
                        binding_set_id,
                        template_slot_map,
                        value_ref_slots,
                    );
                }
                if let Some(binding_set_id) = plan.binding_set_id {
                    let Some(template) = authority.plane.templates.get(template_id) else {
                        return Err(ExcelError::new(ExcelErrorKind::Ref)
                            .with_message("FormulaPlane shift could not find shifted template")
                            .into());
                    };
                    let (ast_id, origin_row, origin_col) =
                        (template.ast_id, template.origin_row, template.origin_col);
                    authority.plane.set_binding_template_anchor(
                        binding_set_id,
                        ast_id,
                        origin_row,
                        origin_col,
                    );
                }
                let read_summary_id = plan
                    .new_read_summary
                    .map(|summary| authority.plane.insert_span_read_summary(summary));
                let result_region = ResultRegion::scalar_cells(plan.new_domain.clone());
                if !authority.plane.replace_span_geometry(
                    plan.span_ref,
                    template_id,
                    plan.new_domain,
                    result_region,
                    read_summary_id,
                ) {
                    return Err(ExcelError::new(ExcelErrorKind::Ref)
                        .with_message("FormulaPlane shift could not update span geometry")
                        .into());
                }
                if let Some(region) = dirty_region {
                    span_dirty_deltas.push((plan.span_ref, region));
                }
                if plan.force_binding_residual_axes
                    && let Some(binding_set_id) = plan.binding_set_id
                {
                    // Value-ref memoization keys are placement-relative. When a
                    // structural op moves the formula origin while keeping some
                    // precedents fixed (e.g. insert a column before a formula
                    // family that reads column A), those keys no longer name
                    // the same producer cells. Keep correctness by forcing
                    // placement offsets into the key so memoization falls back
                    // to per-placement work rather than broadcasting stale
                    // representative values.
                    authority.plane.force_binding_residual_axes(binding_set_id);
                }
            }
            for plan in split_plans {
                let upper_dirty_region = plan.upper_dirty_region;
                let lower_dirty_region = plan.lower_dirty_region;
                let Some(split_relocation) = authority
                    .plane
                    .spans
                    .get(plan.span_ref)
                    .map(|span| span.ast_relocation)
                else {
                    return Err(ExcelError::new(ExcelErrorKind::Ref)
                        .with_message("FormulaPlane split lost its anchor AST state")
                        .into());
                };
                // Lower half: a fresh span at the POST-insert coordinates,
                // mirroring the Shift arm's template/binding handling.
                let Some(lower_template_id) = authority.plane.intern_shifted_template_origin(
                    plan.template_id,
                    plan.lower_new_origin_row,
                    plan.lower_new_origin_col,
                ) else {
                    return Err(ExcelError::new(ExcelErrorKind::Ref)
                        .with_message("FormulaPlane split could not clone template origin")
                        .into());
                };
                let lower_binding_set_id = if let Some(binding_set_id) = plan.binding_set_id {
                    let Some(source) = authority.plane.binding_sets.get(binding_set_id) else {
                        return Err(ExcelError::new(ExcelErrorKind::Ref)
                            .with_message(
                                "FormulaPlane split found a span with a missing binding set",
                            )
                            .into());
                    };
                    // Safe to clone wholesale: `plan_span_split` only accepts
                    // single-literal-binding sets, whose per-placement lookups
                    // are ordinal-independent.
                    let clone = source.clone();
                    let new_binding_set_id = authority.plane.insert_binding_set(clone);
                    let Some(template) = authority.plane.templates.get(lower_template_id) else {
                        return Err(ExcelError::new(ExcelErrorKind::Ref)
                            .with_message("FormulaPlane split could not find shifted template")
                            .into());
                    };
                    let (ast_id, origin_row, origin_col) =
                        (template.ast_id, template.origin_row, template.origin_col);
                    authority.plane.set_binding_template_anchor(
                        new_binding_set_id,
                        ast_id,
                        origin_row,
                        origin_col,
                    );
                    Some(new_binding_set_id)
                } else {
                    None
                };
                let lower_read_summary_id = plan
                    .lower_new_read_summary
                    .map(|summary| authority.plane.insert_span_read_summary(summary));
                let lower_result_region = ResultRegion::scalar_cells(plan.lower_new_domain.clone());
                let lower_ref = authority.plane.insert_span_with_ast_relocation(
                    crate::formula_plane::runtime::NewFormulaSpan {
                        sheet_id: plan.sheet_id,
                        template_id: lower_template_id,
                        domain: plan.lower_new_domain,
                        result_region: lower_result_region,
                        intrinsic_mask_id: None,
                        read_summary_id: lower_read_summary_id,
                        binding_set_id: lower_binding_set_id,
                        is_constant_result: plan.is_constant_result,
                    },
                    crate::formula_plane::runtime::SpanAstRelocation {
                        ast_id: split_relocation.ast_id,
                        anchor_row: plan.lower_new_origin_row,
                        anchor_col: plan.lower_new_origin_col,
                    },
                );
                if let Some(region) = lower_dirty_region {
                    span_dirty_deltas.push((lower_ref, region));
                }
                if let Some(binding_set_id) = lower_binding_set_id {
                    authority
                        .plane
                        .set_binding_span_ref(binding_set_id, lower_ref);
                    if plan.lower_force_binding_residual_axes {
                        // Same contract as the Shift arm: a moved origin with
                        // stationary value-ref precedents invalidates
                        // placement-relative memoization keys.
                        authority.plane.force_binding_residual_axes(binding_set_id);
                    }
                }
                // The lower half inherits the parent's defined-name
                // invalidation registrations; the upper half keeps them by
                // retaining the span id.
                let name_keys = authority.plane.span_registered_name_keys(plan.span_ref.id);
                if !name_keys.is_empty() {
                    authority
                        .plane
                        .register_span_name_dependents(lower_ref, &name_keys);
                }
                for overlay_ref in plan.lower_overlay_refs {
                    if !authority
                        .plane
                        .set_overlay_source_span(overlay_ref, Some(lower_ref))
                    {
                        return Err(ExcelError::new(ExcelErrorKind::Ref)
                            .with_message(
                                "FormulaPlane split could not re-point overlay provenance",
                            )
                            .into());
                    }
                }
                // Upper half: keep the span id, truncate the domain, and swap
                // in a summary re-derived for the truncated result region.
                let upper_read_summary_id = plan
                    .upper_read_summary
                    .map(|summary| authority.plane.insert_span_read_summary(summary));
                let upper_result_region = ResultRegion::scalar_cells(plan.upper_domain.clone());
                if !authority.plane.replace_span_geometry_with_ast_relocation(
                    plan.span_ref,
                    plan.template_id,
                    split_relocation,
                    plan.upper_domain,
                    upper_result_region,
                    upper_read_summary_id,
                ) {
                    return Err(ExcelError::new(ExcelErrorKind::Ref)
                        .with_message("FormulaPlane split could not update span geometry")
                        .into());
                }
                if let Some(region) = upper_dirty_region {
                    span_dirty_deltas.push((plan.span_ref, region));
                }
            }
            authority.rebuild_indexes();
        }
        for (span_ref, region) in span_dirty_deltas {
            self.graph.mark_formula_span_region_dirty(span_ref, region);
        }

        let mut span_plans = Vec::new();
        for span_ref in demote_refs {
            let authority = self.graph.formula_authority();
            let Some(span) = authority.plane.spans.get(span_ref) else {
                continue;
            };
            let relocation = span.ast_relocation;
            let ast = self
                .graph
                .data_store()
                .retrieve_ast(relocation.ast_id, self.graph.sheet_reg())
                .ok_or_else(|| {
                    ExcelError::new(ExcelErrorKind::Ref).with_message(
                        "FormulaPlane demotion could not retrieve the span anchor AST",
                    )
                })?;
            let placements = span
                .domain
                .iter()
                .map(|placement| (placement.row + 1, placement.col + 1))
                .collect();
            span_plans.push(SpanPlan {
                span_ref,
                sheet_id: span.sheet_id,
                ast,
                origin_row: relocation.anchor_row,
                origin_col: relocation.anchor_col,
                binding_set_id: span.binding_set_id,
                placements,
            });
        }
        if span_plans.is_empty() {
            return Ok(());
        }

        let mut relocated = Vec::new();
        let mut placement_cells = Vec::new();
        for plan in &span_plans {
            for &(row, col) in &plan.placements {
                let row_delta = i64::from(row) - i64::from(plan.origin_row);
                let col_delta = i64::from(col) - i64::from(plan.origin_col);
                let bound_ast = if let Some(binding_set_id) = plan.binding_set_id {
                    let authority = self.graph.formula_authority();
                    if let Some(binding_set) = authority.plane.binding_sets.get(binding_set_id) {
                        if binding_set.is_single_literal_binding() {
                            plan.ast.clone()
                        } else {
                            let placement = crate::formula_plane::runtime::PlacementCoord::new(
                                plan.sheet_id,
                                row.saturating_sub(1),
                                col.saturating_sub(1),
                            );
                            let binding =
                                authority.plane.spans.get(plan.span_ref).and_then(|span| {
                                    binding_set
                                        .literal_bindings_for_placement(&span.domain, placement)
                                });
                            if let Some(binding) = binding {
                                substitute_literal_slots_for_template_placement(
                                    &plan.ast,
                                    binding.as_ref(),
                                )
                            } else {
                                plan.ast.clone()
                            }
                        }
                    } else {
                        plan.ast.clone()
                    }
                } else {
                    plan.ast.clone()
                };
                let ast = relocate_ast_for_template_placement(&bound_ast, row_delta, col_delta)?;
                relocated.push((plan.sheet_id, row, col, ast));
                placement_cells.push((plan.sheet_id, row, col));
            }
        }
        let planned_by_sheet = {
            let mut pipeline = self.ingest_pipeline();
            let mut planned_by_sheet: BTreeMap<
                SheetId,
                Vec<(u32, u32, AstNodeId, DependencyPlanRow)>,
            > = BTreeMap::new();
            for (formula_sheet_id, row, col, ast) in relocated {
                let placement =
                    CellRef::new(formula_sheet_id, Coord::from_excel(row, col, true, true));
                let ingested =
                    pipeline.ingest_formula(FormulaAstInput::Tree(ast), placement, None)?;
                planned_by_sheet.entry(formula_sheet_id).or_default().push((
                    row,
                    col,
                    ingested.ast_id,
                    ingested.dep_plan,
                ));
            }
            planned_by_sheet
        };
        {
            let authority = self.graph.formula_authority_mut();
            for plan in &span_plans {
                authority
                    .plane
                    .remove_overlays_for_source_span(plan.span_ref);
                authority.plane.remove_span(plan.span_ref);
            }
            authority.rebuild_indexes();
        }
        if clear_computed_overlays {
            // Only clear placement cells whose coordinate intersects the affected
            // structural region. The structural-op contract preserves cells
            // BEFORE the structural boundary; the legacy `clear_computed_overlay_after_*`
            // call honors that. Demoting a span whose footprint straddles the
            // boundary still must not clear cells before the boundary, even
            // though the span as a whole is demoted.
            self.clear_computed_overlay_cells_in_region(&placement_cells, &affected_region);
        }
        for (formula_sheet_id, planned) in planned_by_sheet {
            let sheet_name = self.graph.sheet_name(formula_sheet_id).to_string();
            self.graph
                .bulk_set_formulas_with_plans(&sheet_name, planned)?;
        }
        if !clear_computed_overlays {
            for (formula_sheet_id, row, col) in &placement_cells {
                let row0 = row.saturating_sub(1);
                let col0 = col.saturating_sub(1);
                if dirty_span_coords.contains(&(*formula_sheet_id, row0, col0)) {
                    continue;
                }
                let cell =
                    CellRef::new(*formula_sheet_id, Coord::from_excel(*row, *col, true, true));
                if let Some(&vertex_id) = self.graph.get_vertex_id_for_address(&cell) {
                    self.graph.set_dirty(vertex_id, false);
                }
            }
        }
        Ok(())
    }

    /// Prepare an exact-ref, additions-only refinement of FormulaPlane spans
    /// into legacy graph formulas. All fallible relocation, dependency analysis,
    /// identifier reservation, and conflict checks happen before commit.
    pub(crate) fn prepare_formula_span_demotion(
        &mut self,
        span_refs: &[FormulaSpanRef],
    ) -> Result<PreparedFormulaSpanDemotion, FormulaSpanDemotionError> {
        #[cfg(test)]
        let fault = self
            .formula_span_demotion_fault_for_test
            .take()
            .unwrap_or_default();
        #[cfg(not(test))]
        let fault = FormulaSpanDemotionFault::None;

        if fault == FormulaSpanDemotionFault::AstPreparation {
            return Err(FormulaSpanDemotionError::Injected(fault));
        }

        fn substitute_literal_slots(ast: &ASTNode, binding: &[LiteralValue]) -> ASTNode {
            fn visit(
                ast: &ASTNode,
                binding: &[LiteralValue],
                next: &mut usize,
                in_array: bool,
            ) -> ASTNode {
                let node_type = match &ast.node_type {
                    ASTNodeType::Literal(_) if !in_array => {
                        let value = binding.get(*next).cloned().unwrap_or(LiteralValue::Empty);
                        *next = next.saturating_add(1);
                        ASTNodeType::Literal(value)
                    }
                    ASTNodeType::Literal(value) => ASTNodeType::Literal(value.clone()),
                    ASTNodeType::Omitted => ASTNodeType::Omitted,
                    ASTNodeType::Reference {
                        original,
                        reference,
                    } => ASTNodeType::Reference {
                        original: original.clone(),
                        reference: reference.clone(),
                    },
                    ASTNodeType::UnaryOp { op, expr } => ASTNodeType::UnaryOp {
                        op: op.clone(),
                        expr: Box::new(visit(expr, binding, next, in_array)),
                    },
                    ASTNodeType::BinaryOp { op, left, right } => ASTNodeType::BinaryOp {
                        op: op.clone(),
                        left: Box::new(visit(left, binding, next, in_array)),
                        right: Box::new(visit(right, binding, next, in_array)),
                    },
                    ASTNodeType::Function { name, args } => ASTNodeType::Function {
                        name: name.clone(),
                        args: args
                            .iter()
                            .map(|arg| visit(arg, binding, next, in_array))
                            .collect(),
                    },
                    ASTNodeType::Call { callee, args } => ASTNodeType::Call {
                        callee: Box::new(visit(callee, binding, next, in_array)),
                        args: args
                            .iter()
                            .map(|arg| visit(arg, binding, next, in_array))
                            .collect(),
                    },
                    ASTNodeType::Array(rows) => ASTNodeType::Array(
                        rows.iter()
                            .map(|row| {
                                row.iter()
                                    .map(|cell| visit(cell, binding, next, true))
                                    .collect()
                            })
                            .collect(),
                    ),
                };
                ASTNode::new(node_type, ast.source_token.clone())
            }
            let mut next = 0;
            visit(ast, binding, &mut next, false)
        }

        struct SpanMaterialization {
            span_ref: FormulaSpanRef,
            sheet_id: SheetId,
            ast: ASTNode,
            origin_row: u32,
            origin_col: u32,
            binding_set_id: Option<crate::formula_plane::runtime::SpanBindingSetId>,
            domain: PlacementDomain,
        }

        let request_id = self
            .active_evaluation_resource_request
            .as_ref()
            .map(|request| request.request_id);
        let resource_error =
            |reason: formualizer_common::ResourceExhaustionReason, limit: u64, observed: u64| {
                FormulaSpanDemotionError::Resource(
                    crate::engine::ResourceLedgerError::Exhausted(
                        formualizer_common::ResourceExhaustionDetail {
                            reason,
                            limit,
                            observed,
                            request_id,
                        },
                    )
                    .into_excel_error(),
                )
            };
        let authority = self.graph.formula_authority();
        let expected_plane_epoch = authority.plane.epoch().0;
        let expected_indexes_epoch = authority.indexes_epoch();
        let expected_indexed_plane_epoch = authority.indexed_plane_epoch();
        let mut unique = Vec::new();
        unique.try_reserve_exact(span_refs.len()).map_err(|_| {
            resource_error(
                formualizer_common::ResourceExhaustionReason::ScratchMemory,
                u64::MAX,
                span_refs.len() as u64,
            )
        })?;
        let mut plans = Vec::new();
        plans.try_reserve_exact(span_refs.len()).map_err(|_| {
            resource_error(
                formualizer_common::ResourceExhaustionReason::ScratchMemory,
                u64::MAX,
                span_refs.len() as u64,
            )
        })?;
        let mut placement_count = 0usize;
        let mut placements_by_sheet: BTreeMap<SheetId, u64> = BTreeMap::new();
        for &span_ref in span_refs {
            if unique.contains(&span_ref) {
                continue;
            }
            unique.push(span_ref);
            let span = authority
                .plane
                .spans
                .get(span_ref)
                .ok_or(FormulaSpanDemotionError::InvalidSpan)?;
            let relocation = span.ast_relocation;
            let ast = self
                .graph
                .data_store()
                .retrieve_ast(relocation.ast_id, self.graph.sheet_reg())
                .ok_or(FormulaSpanDemotionError::InvalidSpan)?;
            let count = usize::try_from(span.domain.cell_count())
                .map_err(|_| FormulaSpanDemotionError::CountOverflow)?;
            placement_count = placement_count
                .checked_add(count)
                .ok_or(FormulaSpanDemotionError::CountOverflow)?;
            if u64::try_from(placement_count)
                .map_err(|_| FormulaSpanDemotionError::CountOverflow)?
                > self.workbook_load_limits.max_formula_plane_fallback_cells
            {
                return Err(resource_error(
                    formualizer_common::ResourceExhaustionReason::MaterializationCells,
                    self.workbook_load_limits.max_formula_plane_fallback_cells,
                    placement_count as u64,
                ));
            }
            let sheet_count = placements_by_sheet.entry(span.sheet_id).or_default();
            *sheet_count = sheet_count
                .checked_add(span.domain.cell_count())
                .ok_or(FormulaSpanDemotionError::CountOverflow)?;
            if *sheet_count > self.workbook_load_limits.max_sheet_logical_cells {
                return Err(resource_error(
                    formualizer_common::ResourceExhaustionReason::Admission,
                    self.workbook_load_limits.max_sheet_logical_cells,
                    *sheet_count,
                ));
            }
            let domain_in_bounds = match &span.domain {
                PlacementDomain::RowRun { row_end, col, .. } => {
                    *row_end < self.workbook_load_limits.max_sheet_rows
                        && *col < self.workbook_load_limits.max_sheet_cols
                }
                PlacementDomain::ColRun { row, col_end, .. } => {
                    *row < self.workbook_load_limits.max_sheet_rows
                        && *col_end < self.workbook_load_limits.max_sheet_cols
                }
                PlacementDomain::Rect {
                    row_end, col_end, ..
                } => {
                    *row_end < self.workbook_load_limits.max_sheet_rows
                        && *col_end < self.workbook_load_limits.max_sheet_cols
                }
            };
            if !domain_in_bounds {
                return Err(resource_error(
                    formualizer_common::ResourceExhaustionReason::Admission,
                    u64::from(self.workbook_load_limits.max_sheet_rows)
                        .saturating_mul(u64::from(self.workbook_load_limits.max_sheet_cols)),
                    span.domain.cell_count(),
                ));
            }
            plans.push(SpanMaterialization {
                span_ref,
                sheet_id: span.sheet_id,
                ast,
                origin_row: relocation.anchor_row,
                origin_col: relocation.anchor_col,
                binding_set_id: span.binding_set_id,
                domain: span.domain.clone(),
            });
        }
        let mut relocated = Vec::new();
        relocated.try_reserve_exact(placement_count).map_err(|_| {
            resource_error(
                formualizer_common::ResourceExhaustionReason::ScratchMemory,
                u64::MAX,
                placement_count as u64,
            )
        })?;
        for plan in &plans {
            for coord in plan.domain.iter() {
                let row = coord.row.saturating_add(1);
                let col = coord.col.saturating_add(1);
                let bound_ast = if let Some(binding_set_id) = plan.binding_set_id {
                    let authority = self.graph.formula_authority();
                    let binding_set = authority
                        .plane
                        .binding_sets
                        .get(binding_set_id)
                        .ok_or(FormulaSpanDemotionError::InvalidSpan)?;
                    if binding_set.is_single_literal_binding() {
                        plan.ast.clone()
                    } else {
                        let placement = PlacementCoord::new(
                            plan.sheet_id,
                            row.saturating_sub(1),
                            col.saturating_sub(1),
                        );
                        let span = authority
                            .plane
                            .spans
                            .get(plan.span_ref)
                            .ok_or(FormulaSpanDemotionError::InvalidSpan)?;
                        let binding = binding_set
                            .literal_bindings_for_placement(&span.domain, placement)
                            .ok_or(FormulaSpanDemotionError::InvalidSpan)?;
                        substitute_literal_slots(&plan.ast, binding.as_ref())
                    }
                } else {
                    plan.ast.clone()
                };
                let row_delta = i64::from(row) - i64::from(plan.origin_row);
                let col_delta = i64::from(col) - i64::from(plan.origin_col);
                let ast = relocate_ast_for_template_placement(&bound_ast, row_delta, col_delta)
                    .map_err(FormulaSpanDemotionError::AstPreparation)?;
                relocated.push((plan.sheet_id, row, col, ast));
            }
        }

        let mut analyzed = Vec::new();
        analyzed.try_reserve_exact(relocated.len()).map_err(|_| {
            resource_error(
                formualizer_common::ResourceExhaustionReason::ScratchMemory,
                u64::MAX,
                relocated.len() as u64,
            )
        })?;
        {
            let mut pipeline = self.ingest_pipeline();
            for (sheet_id, row, col, ast) in relocated {
                let placement = CellRef::new(sheet_id, Coord::from_excel(row, col, true, true));
                let ingested = pipeline
                    .ingest_formula(FormulaAstInput::Tree(ast), placement, None)
                    .map_err(FormulaSpanDemotionError::AstPreparation)?;
                analyzed.push((sheet_id, row, col, ingested.ast_id, ingested.dep_plan));
            }
        }

        if fault == FormulaSpanDemotionFault::LegacyGraphPreparation {
            return Err(FormulaSpanDemotionError::Injected(fault));
        }
        let legacy_graph = self
            .graph
            .prepare_legacy_graph_plan_multi_sheet(analyzed)
            .map_err(FormulaSpanDemotionError::LegacyGraph)?;
        self.prepared_legacy_admission(&legacy_graph, placement_count as u64)
            .map_err(FormulaSpanDemotionError::Resource)?;

        Ok(PreparedFormulaSpanDemotion {
            span_refs: unique,
            expected_plane_epoch,
            expected_indexes_epoch,
            expected_indexed_plane_epoch,
            placement_count,
            legacy_graph,
            fault,
        })
    }

    pub(crate) fn validate_prepared_formula_span_demotion(
        &self,
        prepared: &PreparedFormulaSpanDemotion,
    ) -> Result<(), FormulaSpanDemotionError> {
        let authority = self.graph.formula_authority();
        if authority.plane.epoch().0 != prepared.expected_plane_epoch
            || authority.indexes_epoch() != prepared.expected_indexes_epoch
            || authority.indexed_plane_epoch() != prepared.expected_indexed_plane_epoch
            || prepared
                .span_refs
                .iter()
                .any(|span_ref| authority.plane.spans.get(*span_ref).is_none())
        {
            return Err(FormulaSpanDemotionError::StaleAuthority);
        }
        self.graph
            .validate_prepared_legacy_graph_plan(&prepared.legacy_graph)
            .map_err(FormulaSpanDemotionError::LegacyGraph)
    }

    /// Validate every recoverable assumption and fault before the first
    /// mutation, then compose the existing prevalidated graph append with exact
    /// authority removal. Allocator OOM/panic remains process-fatal, matching
    /// the E2/E3 prepared-transaction contract; there is no recoverable branch
    /// after graph application begins.
    pub(crate) fn commit_prepared_formula_span_demotion(
        &mut self,
        prepared: PreparedFormulaSpanDemotion,
    ) -> Result<FormulaSpanDemotionReport, FormulaSpanDemotionError> {
        self.prepared_legacy_admission(&prepared.legacy_graph, prepared.placement_count as u64)
            .map_err(FormulaSpanDemotionError::Resource)?;
        if prepared.fault == FormulaSpanDemotionFault::FinalLegacyGraphValidation {
            return Err(FormulaSpanDemotionError::Injected(prepared.fault));
        }
        self.graph
            .validate_prepared_legacy_graph_plan(&prepared.legacy_graph)
            .map_err(FormulaSpanDemotionError::LegacyGraph)?;
        if prepared.fault == FormulaSpanDemotionFault::FinalAuthorityValidation {
            return Err(FormulaSpanDemotionError::Injected(prepared.fault));
        }
        {
            let authority = self.graph.formula_authority();
            if authority.plane.epoch().0 != prepared.expected_plane_epoch
                || authority.indexes_epoch() != prepared.expected_indexes_epoch
                || authority.indexed_plane_epoch() != prepared.expected_indexed_plane_epoch
                || prepared
                    .span_refs
                    .iter()
                    .any(|span_ref| authority.plane.spans.get(*span_ref).is_none())
            {
                return Err(FormulaSpanDemotionError::StaleAuthority);
            }
        }
        if matches!(
            prepared.fault,
            FormulaSpanDemotionFault::AllocationReservation
                | FormulaSpanDemotionFault::BeforeFirstMutation
        ) {
            return Err(FormulaSpanDemotionError::Injected(prepared.fault));
        }

        let PreparedFormulaSpanDemotion {
            span_refs,
            placement_count,
            legacy_graph,
            ..
        } = prepared;
        let _ = self
            .graph
            .apply_prevalidated_legacy_graph_plan(legacy_graph);
        let authority = self.graph.formula_authority_mut();
        for span_ref in &span_refs {
            authority.plane.remove_overlays_for_source_span(*span_ref);
            let _ = authority.plane.remove_span(*span_ref);
        }
        let _ = authority.rebuild_indexes();
        self.mark_topology_edited();
        Ok(FormulaSpanDemotionReport {
            spans_demoted: span_refs.len(),
            placements_materialized: placement_count,
        })
    }

    #[cfg(test)]
    pub(crate) fn set_formula_span_demotion_fault_for_test(
        &mut self,
        fault: FormulaSpanDemotionFault,
    ) {
        self.formula_span_demotion_fault_for_test = Some(fault);
    }

    #[cfg(test)]
    pub(crate) fn force_non_cycle_schedule_fallback_for_test(&mut self) {
        self.force_non_cycle_schedule_fallback_for_test = true;
    }

    #[cfg(test)]
    pub(crate) fn mixed_topology_index_builds_for_test(&self) -> u64 {
        self.mixed_topology_index_builds_for_test
    }

    /// Collect the [`FormulaSpanRef`]s for span producers the mixed scheduler
    /// reported as cycle members (gotcha G8, refs #112). These spans must be
    /// demoted to legacy so the cycle members are resolved on the legacy SCC
    /// path; see [`Self::demote_cyclic_spans`].
    fn collect_cyclic_span_refs(
        &self,
        schedule: &MixedSchedule,
        span_refs_by_id: &BTreeMap<FormulaSpanId, FormulaSpanRef>,
    ) -> Vec<FormulaSpanRef> {
        let mut refs = Vec::new();
        for fallback in &schedule.fallbacks {
            if fallback.reason != MixedScheduleFallbackReason::CycleDetected {
                continue;
            }
            if let FormulaProducerId::Span(span_id) = fallback.producer
                && let Some(span_ref) = span_refs_by_id.get(&span_id)
                && !refs.contains(span_ref)
            {
                refs.push(*span_ref);
            }
        }
        refs
    }

    /// Demote the given cyclic spans to legacy graph vertices so their member
    /// cells participate in the legacy Tarjan SCC pass (gotcha G8, refs #112).
    ///
    /// Uses one exact-ref prepared transaction for every cyclic span reported
    /// by this schedule. All recoverable validation and injected faults precede
    /// the first graph/authority mutation, so a multi-span or multi-sheet cycle
    /// cannot publish only an earlier subset.
    fn demote_cyclic_spans(&mut self, span_refs: &[FormulaSpanRef]) -> Result<(), ExcelError> {
        let materialization_started = crate::instant::FzInstant::now();
        let prepared = self
            .prepare_formula_span_demotion(span_refs)
            .map_err(|error| {
                if let FormulaSpanDemotionError::Resource(error) = error {
                    error
                } else {
                    ExcelError::new(ExcelErrorKind::NImpl).with_message(format!(
                        "FormulaPlane cycle-member span demotion preparation failed: {error}"
                    ))
                }
            })?;
        let report = self
            .commit_prepared_formula_span_demotion(prepared)
            .map_err(|error| {
                ExcelError::new(ExcelErrorKind::NImpl).with_message(format!(
                    "FormulaPlane cycle-member span demotion commit failed: {error}"
                ))
            })?;
        self.observe_materialization(
            report.placements_materialized,
            true,
            materialization_started.elapsed(),
        );
        self.formula_plane_cycle_member_span_demotions = self
            .formula_plane_cycle_member_span_demotions
            .saturating_add(report.spans_demoted as u64);
        Self::record_shadow_fallback_reason(
            &mut self.formula_ingest_report_total,
            PlacementFallbackReason::CycleMember,
            report.spans_demoted as u64,
        );
        Ok(())
    }

    /// Evaluate residual *legacy-only* cyclic SCCs before the FormulaPlane
    /// mixed schedule runs (gotcha G8, refs #112).
    ///
    /// After cyclic spans are demoted to legacy ([`Self::demote_cyclic_spans`]),
    /// every cycle member is a graph vertex, so the cycle is now visible to the
    /// legacy Tarjan pass and lives entirely among legacy producers. The mixed
    /// schedule treats any cycle as not authoritative-safe; rather than abandon
    /// the surviving spans by falling through to a pure-legacy `evaluate_all`,
    /// stamp/evaluate just the cyclic SCC units here (`handle_cycle_unit` honors
    /// `CycleDetection::Static` vs `Runtime`), clear their dirty flags, and let
    /// the mixed schedule proceed cycle-free over the surviving spans plus the
    /// acyclic legacy work.
    ///
    /// Returns the number of cyclic SCC units that stamped at least one cell.
    fn evaluate_legacy_cycle_prepass(&mut self) -> Result<usize, ExcelError> {
        let dirty = self.graph.get_evaluation_vertices();
        if dirty.is_empty() {
            return Ok(0);
        }
        let (schedule, _vdeps, _meta) = self.create_evaluation_schedule(&dirty)?;
        let dirty_set: FxHashSet<VertexId> = dirty.iter().copied().collect();
        let mut cycle_errors = 0usize;
        let mut stamped_vertices: Vec<VertexId> = Vec::new();
        for &unit in &schedule.units {
            let ScheduleUnit::Cycle(i) = unit else {
                continue;
            };
            let members = schedule.unit_cycle(i);
            let stamped = self.handle_cycle_unit(members, None, Some(&dirty_set), None)?;
            if stamped > 0 {
                cycle_errors += 1;
            }
            stamped_vertices.extend(members.iter().copied());
        }
        // Clear dirty only on the cyclic members so the subsequent mixed
        // schedule no longer sees them as dirty legacy producers (which is what
        // surfaced the cycle). Acyclic legacy work stays dirty and is scheduled
        // normally alongside the surviving spans.
        if !stamped_vertices.is_empty() {
            self.resource_checkpoint(0)?;
            self.graph.clear_dirty_flags(&stamped_vertices);
        }
        Ok(cycle_errors)
    }

    fn materialize_deferred_sheet_before_structural_edit(
        &mut self,
        sheet: &str,
    ) -> Result<(), crate::engine::EditorError> {
        if self.staged_formulas.contains_key(sheet) {
            self.build_graph_for_sheets([sheet])?;
        }
        Ok(())
    }

    /// Insert rows (1-based) and mirror into Arrow store when enabled
    pub fn insert_rows(
        &mut self,
        sheet: &str,
        before: u32,
        count: u32,
    ) -> Result<crate::engine::graph::editor::vertex_editor::ShiftSummary, crate::engine::EditorError>
    {
        if count == 0 {
            return Ok(crate::engine::graph::editor::vertex_editor::ShiftSummary::default());
        }
        self.observe_function_semantic_epoch()
            .map_err(crate::engine::EditorError::Excel)?;
        use crate::engine::graph::editor::vertex_editor::VertexEditor;
        self.materialize_deferred_sheet_before_structural_edit(sheet)?;
        let sheet_id = self.ensure_known_sheet_id(sheet)?;
        let before0 = before.saturating_sub(1);
        let affected_region = Self::structural_row_region(sheet_id, before0);
        let op = StructuralOp::InsertRows {
            sheet_id,
            before: before0,
            count,
        };
        self.demote_spans_for_structural_op(op, affected_region)?;
        let summary = {
            let mut editor = VertexEditor::new(&mut self.graph);
            editor.insert_rows(sheet_id, before0, count)?
        };
        if let Some(asheet) = self.arrow_sheets.sheet_mut(sheet) {
            let before0 = before0 as usize;
            asheet.insert_rows(before0, count as usize);
        }
        self.mark_moved_formula_vertices_dirty(&summary);
        self.clear_computed_overlay_after_row(sheet, before0 as usize);
        self.shift_row_visibility_insert(sheet_id, before0, count);
        self.record_formula_plane_structural_change(StructuralScope::Region(affected_region));
        self.mark_topology_edited();
        Ok(summary)
    }

    /// Delete rows (1-based) and mirror into Arrow store when enabled
    pub fn delete_rows(
        &mut self,
        sheet: &str,
        start: u32,
        count: u32,
    ) -> Result<crate::engine::graph::editor::vertex_editor::ShiftSummary, crate::engine::EditorError>
    {
        if count == 0 {
            return Ok(crate::engine::graph::editor::vertex_editor::ShiftSummary::default());
        }
        self.observe_function_semantic_epoch()
            .map_err(crate::engine::EditorError::Excel)?;
        use crate::engine::graph::editor::vertex_editor::VertexEditor;
        self.materialize_deferred_sheet_before_structural_edit(sheet)?;
        let sheet_id = self.ensure_known_sheet_id(sheet)?;
        let start0 = start.saturating_sub(1);
        let affected_region = Self::structural_row_region(sheet_id, start0);
        let op = StructuralOp::DeleteRows {
            sheet_id,
            start: start0,
            count,
        };
        self.demote_spans_for_structural_op(op, affected_region)?;
        let summary = {
            let mut editor = VertexEditor::new(&mut self.graph);
            editor.delete_rows(sheet_id, start0, count)?
        };
        if let Some(asheet) = self.arrow_sheets.sheet_mut(sheet) {
            let start0 = start0 as usize;
            asheet.delete_rows(start0, count as usize);
        }
        self.mark_moved_formula_vertices_dirty(&summary);
        self.clear_computed_overlay_after_row(sheet, start0 as usize);
        self.shift_row_visibility_delete(sheet_id, start0, count);
        self.record_formula_plane_structural_change(StructuralScope::Region(affected_region));
        self.mark_topology_edited();
        Ok(summary)
    }

    /// Insert columns (1-based) and mirror into Arrow store when enabled
    pub fn insert_columns(
        &mut self,
        sheet: &str,
        before: u32,
        count: u32,
    ) -> Result<crate::engine::graph::editor::vertex_editor::ShiftSummary, crate::engine::EditorError>
    {
        if count == 0 {
            return Ok(crate::engine::graph::editor::vertex_editor::ShiftSummary::default());
        }
        self.observe_function_semantic_epoch()
            .map_err(crate::engine::EditorError::Excel)?;
        use crate::engine::graph::editor::vertex_editor::VertexEditor;
        self.materialize_deferred_sheet_before_structural_edit(sheet)?;
        let sheet_id = self.graph.sheet_id(sheet).ok_or(
            crate::engine::graph::editor::vertex_editor::EditorError::InvalidName {
                name: sheet.to_string(),
                reason: "Unknown sheet".to_string(),
            },
        )?;
        let before0 = before.saturating_sub(1);
        let affected_region = Self::structural_col_region(sheet_id, before0);
        let op = StructuralOp::InsertColumns {
            sheet_id,
            before: before0,
            count,
        };
        self.demote_spans_for_structural_op(op, affected_region)?;
        let summary = {
            let mut editor = VertexEditor::new(&mut self.graph);
            editor.insert_columns(sheet_id, before0, count)?
        };
        if let Some(asheet) = self.arrow_sheets.sheet_mut(sheet) {
            let before0 = before0 as usize;
            asheet.insert_columns(before0, count as usize);
        }
        self.mark_moved_formula_vertices_dirty(&summary);
        self.clear_computed_overlay_after_col(sheet, before0 as usize);
        self.record_formula_plane_structural_change(StructuralScope::Region(affected_region));
        self.mark_topology_edited();
        Ok(summary)
    }

    /// Delete columns (1-based) and mirror into Arrow store when enabled
    pub fn delete_columns(
        &mut self,
        sheet: &str,
        start: u32,
        count: u32,
    ) -> Result<crate::engine::graph::editor::vertex_editor::ShiftSummary, crate::engine::EditorError>
    {
        if count == 0 {
            return Ok(crate::engine::graph::editor::vertex_editor::ShiftSummary::default());
        }
        self.observe_function_semantic_epoch()
            .map_err(crate::engine::EditorError::Excel)?;
        use crate::engine::graph::editor::vertex_editor::VertexEditor;
        self.materialize_deferred_sheet_before_structural_edit(sheet)?;
        let sheet_id = self.graph.sheet_id(sheet).ok_or(
            crate::engine::graph::editor::vertex_editor::EditorError::InvalidName {
                name: sheet.to_string(),
                reason: "Unknown sheet".to_string(),
            },
        )?;
        let start0 = start.saturating_sub(1);
        let affected_region = Self::structural_col_region(sheet_id, start0);
        let op = StructuralOp::DeleteColumns {
            sheet_id,
            start: start0,
            count,
        };
        self.demote_spans_for_structural_op(op, affected_region)?;
        let summary = {
            let mut editor = VertexEditor::new(&mut self.graph);
            editor.delete_columns(sheet_id, start0, count)?
        };
        if let Some(asheet) = self.arrow_sheets.sheet_mut(sheet) {
            let start0 = start0 as usize;
            asheet.delete_columns(start0, count as usize);
        }
        self.mark_moved_formula_vertices_dirty(&summary);
        self.clear_computed_overlay_after_col(sheet, start0 as usize);
        self.record_formula_plane_structural_change(StructuralScope::Region(affected_region));
        self.mark_topology_edited();
        Ok(summary)
    }
    /// Arrow-backed used row bounds across a column span (1-based inclusive cols).
    fn arrow_used_row_bounds(
        &self,
        sheet: &str,
        start_col: u32,
        end_col: u32,
    ) -> Option<(u32, u32)> {
        let a = self.sheet_store().sheet(sheet)?;
        if a.columns.is_empty() {
            return None;
        }
        let sc0 = start_col.saturating_sub(1) as usize;
        let ec0 = end_col.saturating_sub(1) as usize;
        let col_hi = a.columns.len().saturating_sub(1);
        if sc0 > col_hi {
            return None;
        }
        let ec0 = ec0.min(col_hi);
        // Pass-scoped cache with snapshot guard
        let snap = self.data_snapshot_id();
        let mut min_r0: Option<usize> = None;
        for ci in sc0..=ec0 {
            let sheet_id = self.graph.sheet_id(sheet)?;
            if let Some((Some(mv), _)) = self.row_bounds_cache.read().ok().and_then(|g| {
                g.as_ref()
                    .and_then(|c| c.get_row_bounds(sheet_id, ci, snap))
            }) {
                let mv = mv as usize;
                min_r0 = Some(min_r0.map(|m| m.min(mv)).unwrap_or(mv));
                continue;
            }
            // Compute and store
            let (min_c, max_c) = Self::scan_column_used_bounds(a, ci);
            if let Ok(mut g) = self.row_bounds_cache.write() {
                g.get_or_insert_with(|| RowBoundsCache::new(snap))
                    .put_row_bounds(sheet_id, ci, snap, (min_c, max_c));
            }
            if let Some(m) = min_c {
                min_r0 = Some(min_r0.map(|mm| mm.min(m as usize)).unwrap_or(m as usize));
            }
        }
        min_r0?;
        let mut max_r0: Option<usize> = None;
        for ci in sc0..=ec0 {
            let sheet_id = self.graph.sheet_id(sheet)?;
            if let Some((_, Some(mv))) = self.row_bounds_cache.read().ok().and_then(|g| {
                g.as_ref()
                    .and_then(|c| c.get_row_bounds(sheet_id, ci, snap))
            }) {
                let mv = mv as usize;
                max_r0 = Some(max_r0.map(|m| m.max(mv)).unwrap_or(mv));
                continue;
            }
            let (_min_c, max_c) = Self::scan_column_used_bounds(a, ci);
            if let Ok(mut g) = self.row_bounds_cache.write() {
                g.get_or_insert_with(|| RowBoundsCache::new(snap))
                    .put_row_bounds(sheet_id, ci, snap, (_min_c, max_c));
            }
            if let Some(m) = max_c {
                max_r0 = Some(max_r0.map(|mm| mm.max(m as usize)).unwrap_or(m as usize));
            }
        }
        match (min_r0, max_r0) {
            (Some(a0), Some(b0)) => Some(((a0 as u32) + 1, (b0 as u32) + 1)),
            _ => None,
        }
    }

    fn scan_column_used_bounds(
        a: &crate::arrow_store::ArrowSheet,
        ci: usize,
    ) -> (Option<u32>, Option<u32>) {
        let col = &a.columns[ci];

        // Min: scan dense chunks first, then sparse chunks in ascending index order.
        let mut min_r0: Option<u32> = None;
        for (chunk_idx, chunk) in col.chunks.iter().enumerate() {
            let tags = chunk.type_tag.values();
            for (off, &t) in tags.iter().enumerate() {
                let overlay_non_empty = chunk
                    .overlay
                    .get(off)
                    .map(|ov| !matches!(ov, crate::arrow_store::OverlayValue::Empty))
                    .unwrap_or(false)
                    || chunk
                        .computed_overlay
                        .get(off)
                        .map(|ov| !matches!(ov, crate::arrow_store::OverlayValue::Empty))
                        .unwrap_or(false);
                if overlay_non_empty || t != crate::arrow_store::TypeTag::Empty as u8 {
                    let Some(&chunk_start) = a.chunk_starts.get(chunk_idx) else {
                        break;
                    };
                    let row0 = chunk_start + off;
                    min_r0 = Some(row0 as u32);
                    break;
                }
            }
            if min_r0.is_some() {
                break;
            }
        }
        if min_r0.is_none() && !col.sparse_chunks.is_empty() {
            let mut sparse_idxs: Vec<usize> = col.sparse_chunks.keys().copied().collect();
            sparse_idxs.sort_unstable();
            for chunk_idx in sparse_idxs {
                let Some(chunk) = col.sparse_chunks.get(&chunk_idx) else {
                    continue;
                };
                let Some(&chunk_start) = a.chunk_starts.get(chunk_idx) else {
                    continue;
                };
                let tags = chunk.type_tag.values();
                for (off, &t) in tags.iter().enumerate() {
                    let overlay_non_empty = chunk
                        .overlay
                        .get(off)
                        .map(|ov| !matches!(ov, crate::arrow_store::OverlayValue::Empty))
                        .unwrap_or(false)
                        || chunk
                            .computed_overlay
                            .get(off)
                            .map(|ov| !matches!(ov, crate::arrow_store::OverlayValue::Empty))
                            .unwrap_or(false);
                    if overlay_non_empty || t != crate::arrow_store::TypeTag::Empty as u8 {
                        let row0 = chunk_start + off;
                        min_r0 = Some(row0 as u32);
                        break;
                    }
                }
                if min_r0.is_some() {
                    break;
                }
            }
        }

        // Max: scan sparse chunks in descending index order, then dense chunks in reverse.
        let mut max_r0: Option<u32> = None;
        if !col.sparse_chunks.is_empty() {
            let mut sparse_idxs: Vec<usize> = col.sparse_chunks.keys().copied().collect();
            sparse_idxs.sort_unstable_by(|a, b| b.cmp(a));
            for chunk_idx in sparse_idxs {
                let Some(chunk) = col.sparse_chunks.get(&chunk_idx) else {
                    continue;
                };
                let Some(&chunk_start) = a.chunk_starts.get(chunk_idx) else {
                    continue;
                };
                let tags = chunk.type_tag.values();
                for (rev_idx, &t) in tags.iter().enumerate().rev() {
                    let overlay_non_empty = chunk
                        .overlay
                        .get(rev_idx)
                        .map(|ov| !matches!(ov, crate::arrow_store::OverlayValue::Empty))
                        .unwrap_or(false)
                        || chunk
                            .computed_overlay
                            .get(rev_idx)
                            .map(|ov| !matches!(ov, crate::arrow_store::OverlayValue::Empty))
                            .unwrap_or(false);
                    if overlay_non_empty || t != crate::arrow_store::TypeTag::Empty as u8 {
                        let row0 = chunk_start + rev_idx;
                        max_r0 = Some(row0 as u32);
                        break;
                    }
                }
                if max_r0.is_some() {
                    break;
                }
            }
        }
        if max_r0.is_none() {
            for (chunk_idx, chunk) in col.chunks.iter().enumerate().rev() {
                let tags = chunk.type_tag.values();
                for (rev_idx, &t) in tags.iter().enumerate().rev() {
                    let overlay_non_empty = chunk
                        .overlay
                        .get(rev_idx)
                        .map(|ov| !matches!(ov, crate::arrow_store::OverlayValue::Empty))
                        .unwrap_or(false)
                        || chunk
                            .computed_overlay
                            .get(rev_idx)
                            .map(|ov| !matches!(ov, crate::arrow_store::OverlayValue::Empty))
                            .unwrap_or(false);
                    if overlay_non_empty || t != crate::arrow_store::TypeTag::Empty as u8 {
                        let Some(&chunk_start) = a.chunk_starts.get(chunk_idx) else {
                            break;
                        };
                        let row0 = chunk_start + rev_idx;
                        max_r0 = Some(row0 as u32);
                        break;
                    }
                }
                if max_r0.is_some() {
                    break;
                }
            }
        }

        (min_r0, max_r0)
    }

    /// Arrow-backed used column bounds across a row span (1-based inclusive rows).
    fn arrow_used_col_bounds(
        &self,
        sheet: &str,
        start_row: u32,
        end_row: u32,
    ) -> Option<(u32, u32)> {
        let a = self.sheet_store().sheet(sheet)?;
        if a.columns.is_empty() {
            return None;
        }
        let sr0 = start_row.saturating_sub(1) as usize;
        let er0 = end_row.saturating_sub(1) as usize;
        if sr0 > er0 {
            return None;
        }
        // Map start/end rows into chunk ranges
        // We will scan each column for any non-empty within [sr0..=er0]
        let mut min_c0: Option<usize> = None;
        let mut max_c0: Option<usize> = None;
        // Precompute chunk bounds for row range
        for (ci, col) in a.columns.iter().enumerate() {
            let mut any_in_range = false;

            let scan_chunk = |chunk_idx: usize, chunk: &crate::arrow_store::ColumnChunk| -> bool {
                let Some(&chunk_start) = a.chunk_starts.get(chunk_idx) else {
                    return false;
                };
                let chunk_len = chunk.type_tag.len();
                if chunk_len == 0 {
                    return false;
                }
                let chunk_end = chunk_start + chunk_len.saturating_sub(1);
                // check intersection
                if sr0 > chunk_end || er0 < chunk_start {
                    return false;
                }
                let start_off = sr0.max(chunk_start) - chunk_start;
                let end_off = er0.min(chunk_end) - chunk_start;
                let tags = chunk.type_tag.values();
                for off in start_off..=end_off {
                    let overlay_non_empty = chunk
                        .overlay
                        .get(off)
                        .map(|ov| !matches!(ov, crate::arrow_store::OverlayValue::Empty))
                        .unwrap_or(false)
                        || chunk
                            .computed_overlay
                            .get(off)
                            .map(|ov| !matches!(ov, crate::arrow_store::OverlayValue::Empty))
                            .unwrap_or(false);
                    if overlay_non_empty || tags[off] != crate::arrow_store::TypeTag::Empty as u8 {
                        return true;
                    }
                }
                false
            };

            for (chunk_idx, chunk) in col.chunks.iter().enumerate() {
                if scan_chunk(chunk_idx, chunk) {
                    any_in_range = true;
                    break;
                }
            }

            if !any_in_range && !col.sparse_chunks.is_empty() {
                for (&chunk_idx, chunk) in col.sparse_chunks.iter() {
                    if scan_chunk(chunk_idx, chunk) {
                        any_in_range = true;
                        break;
                    }
                }
            }

            if any_in_range {
                min_c0 = Some(min_c0.map(|m| m.min(ci)).unwrap_or(ci));
                max_c0 = Some(max_c0.map(|m| m.max(ci)).unwrap_or(ci));
            }
        }
        match (min_c0, max_c0) {
            (Some(a0), Some(b0)) => Some(((a0 as u32) + 1, (b0 as u32) + 1)),
            _ => None,
        }
    }

    fn formula_row_bounds_for_columns(
        &self,
        sheet: &str,
        start_col: u32,
        end_col: u32,
    ) -> Option<(u32, u32)> {
        let sheet_id = self.graph.sheet_id(sheet)?;
        let sc0 = start_col.saturating_sub(1);
        let ec0 = end_col.saturating_sub(1);
        let mut min_r0: Option<u32> = None;
        let mut max_r0: Option<u32> = None;

        if let Some(index) = self.graph.sheet_index(sheet_id) {
            for vid in index.vertices_in_col_range(sc0, ec0) {
                if !matches!(
                    self.graph.get_vertex_kind(vid),
                    VertexKind::FormulaScalar | VertexKind::FormulaArray
                ) {
                    continue;
                }
                let row0 = self.graph.vertex_coord(vid).row();
                min_r0 = Some(min_r0.map(|m| m.min(row0)).unwrap_or(row0));
                max_r0 = Some(max_r0.map(|m| m.max(row0)).unwrap_or(row0));
            }
        } else {
            for vid in self.graph.vertices_in_sheet(sheet_id) {
                if !matches!(
                    self.graph.get_vertex_kind(vid),
                    VertexKind::FormulaScalar | VertexKind::FormulaArray
                ) {
                    continue;
                }
                let coord = self.graph.vertex_coord(vid);
                let col0 = coord.col();
                if col0 < sc0 || col0 > ec0 {
                    continue;
                }
                let row0 = coord.row();
                min_r0 = Some(min_r0.map(|m| m.min(row0)).unwrap_or(row0));
                max_r0 = Some(max_r0.map(|m| m.max(row0)).unwrap_or(row0));
            }
        }

        match (min_r0, max_r0) {
            (Some(a0), Some(b0)) => Some((a0 + 1, b0 + 1)),
            _ => None,
        }
    }

    fn formula_col_bounds_for_rows(
        &self,
        sheet: &str,
        start_row: u32,
        end_row: u32,
    ) -> Option<(u32, u32)> {
        let sheet_id = self.graph.sheet_id(sheet)?;
        let sr0 = start_row.saturating_sub(1);
        let er0 = end_row.saturating_sub(1);
        let mut min_c0: Option<u32> = None;
        let mut max_c0: Option<u32> = None;

        if let Some(index) = self.graph.sheet_index(sheet_id) {
            for vid in index.vertices_in_row_range(sr0, er0) {
                if !matches!(
                    self.graph.get_vertex_kind(vid),
                    VertexKind::FormulaScalar | VertexKind::FormulaArray
                ) {
                    continue;
                }
                let col0 = self.graph.vertex_coord(vid).col();
                min_c0 = Some(min_c0.map(|m| m.min(col0)).unwrap_or(col0));
                max_c0 = Some(max_c0.map(|m| m.max(col0)).unwrap_or(col0));
            }
        } else {
            for vid in self.graph.vertices_in_sheet(sheet_id) {
                if !matches!(
                    self.graph.get_vertex_kind(vid),
                    VertexKind::FormulaScalar | VertexKind::FormulaArray
                ) {
                    continue;
                }
                let coord = self.graph.vertex_coord(vid);
                let row0 = coord.row();
                if row0 < sr0 || row0 > er0 {
                    continue;
                }
                let col0 = coord.col();
                min_c0 = Some(min_c0.map(|m| m.min(col0)).unwrap_or(col0));
                max_c0 = Some(max_c0.map(|m| m.max(col0)).unwrap_or(col0));
            }
        }

        match (min_c0, max_c0) {
            (Some(a0), Some(b0)) => Some((a0 + 1, b0 + 1)),
            _ => None,
        }
    }

    fn union_used_bounds(
        first: Option<(u32, u32)>,
        second: Option<(u32, u32)>,
    ) -> Option<(u32, u32)> {
        match (first, second) {
            (Some((a0, b0)), Some((a1, b1))) => Some((a0.min(a1), b0.max(b1))),
            (Some(bounds), None) | (None, Some(bounds)) => Some(bounds),
            (None, None) => None,
        }
    }

    /// Mirror a single cell value into the Arrow overlay if enabled.
    /// Handles capacity growth, per-chunk overlay set, and heuristic compaction.
    fn mirror_value_to_overlay(&mut self, sheet: &str, row: u32, col: u32, value: &LiteralValue) {
        if !(self.config.arrow_storage_enabled && self.config.delta_overlay_enabled) {
            return;
        }
        if self.arrow_sheets.sheet(sheet).is_none() {
            self.arrow_sheets
                .sheets
                .push(crate::arrow_store::ArrowSheet {
                    name: std::sync::Arc::<str>::from(sheet),
                    date_system: self.config.date_system,
                    columns: Vec::new(),
                    nrows: 0,
                    chunk_starts: Vec::new(),
                    chunk_rows: 32 * 1024,
                });
        }

        let row0 = row.saturating_sub(1) as usize;
        let col0 = col.saturating_sub(1) as usize;

        let asheet = self
            .arrow_sheets
            .sheet_mut(sheet)
            .expect("ArrowSheet must exist");

        let cur_cols = asheet.columns.len();
        if col0 >= cur_cols {
            asheet.insert_columns(cur_cols, (col0 + 1) - cur_cols);
        }

        if row0 >= asheet.nrows as usize {
            if asheet.columns.is_empty() {
                asheet.insert_columns(0, 1);
            }
            asheet.ensure_row_capacity(row0 + 1);
        }
        if let Some((ch_idx, in_off)) = asheet.chunk_of_row(row0) {
            let ov =
                crate::arrow_store::OverlayValue::from_literal_value(value, asheet.date_system);
            let computed_delta = if let Some(ch) = asheet.ensure_column_chunk_mut(col0, ch_idx) {
                let _ = ch.overlay.set(in_off, ov);
                // A user edit must invalidate any computed (formula/spill) overlay entry at
                // this cell. Otherwise, if the delta overlay later compacts into the base lanes
                // (clearing `overlay`), a stale `computed_overlay=Empty` could incorrectly mask
                // the edited base value under the read cascade.
                ch.computed_overlay.remove(in_off)
            } else {
                return;
            };
            // Heuristic compaction: > len/50 or > 1024
            let abs_threshold = 1024usize;
            let frac_den = 50usize;
            let freed = asheet.maybe_compact_chunk(col0, ch_idx, abs_threshold, frac_den);
            if freed > 0 {
                self.overlay_compactions = self.overlay_compactions.saturating_add(1);
            }
            self.adjust_computed_overlay_bytes(computed_delta);
        }
    }

    /// Remove a delta-overlay entry for a single cell (if present).
    ///
    /// This is used when transitioning a cell to a formula so that any previous user-edit overlay
    /// does not continue to mask computed overlay outputs.
    fn clear_delta_overlay_cell(&mut self, sheet: &str, row: u32, col: u32) {
        if !(self.config.arrow_storage_enabled && self.config.delta_overlay_enabled) {
            return;
        }
        let Some(asheet) = self.arrow_sheets.sheet_mut(sheet) else {
            return;
        };
        let row0 = row.saturating_sub(1) as usize;
        let col0 = col.saturating_sub(1) as usize;
        if row0 >= asheet.nrows as usize {
            return;
        }
        if col0 >= asheet.columns.len() {
            return;
        }
        let Some((ch_idx, in_off)) = asheet.chunk_of_row(row0) else {
            return;
        };
        if let Some(ch) = asheet.columns[col0].chunk_mut(ch_idx) {
            let _ = ch.overlay.remove(in_off);
        }
    }

    fn clear_computed_overlay_col_row_range(
        &mut self,
        sheet: &str,
        col0: usize,
        start_row0: usize,
        end_row0_exclusive: usize,
    ) {
        if !(self.config.arrow_storage_enabled && self.config.write_formula_overlay_enabled) {
            return;
        }
        if start_row0 >= end_row0_exclusive {
            return;
        }

        let Some(asheet) = self.arrow_sheets.sheet_mut(sheet) else {
            return;
        };
        if col0 >= asheet.columns.len() || start_row0 >= asheet.nrows as usize {
            return;
        }
        let end_row0_exclusive = end_row0_exclusive.min(asheet.nrows as usize);
        if start_row0 >= end_row0_exclusive {
            return;
        }

        let starts = asheet.chunk_starts.clone();
        let nrows = asheet.nrows as usize;
        let mut delta = 0isize;
        let Some(col) = asheet.columns.get_mut(col0) else {
            return;
        };
        for (chunk_idx, ch) in col.chunks.iter_mut().enumerate() {
            let Some(&chunk_start) = starts.get(chunk_idx) else {
                continue;
            };
            let chunk_end = starts
                .get(chunk_idx + 1)
                .copied()
                .unwrap_or(nrows)
                .min(chunk_start.saturating_add(ch.len()));
            let clear_start = start_row0.max(chunk_start);
            let clear_end = end_row0_exclusive.min(chunk_end);
            if clear_start >= clear_end {
                continue;
            }
            if clear_start == chunk_start && clear_end == chunk_end {
                delta = delta.saturating_sub(ch.computed_overlay.clear() as isize);
            } else {
                let start_in_chunk = clear_start.saturating_sub(chunk_start).min(ch.len());
                let end_in_chunk = clear_end.saturating_sub(chunk_start).min(ch.len());
                delta = delta.saturating_add(
                    ch.computed_overlay
                        .remove_range(start_in_chunk..end_in_chunk),
                );
            }
        }
        for (chunk_idx, ch) in &mut col.sparse_chunks {
            let Some(&chunk_start) = starts.get(*chunk_idx) else {
                continue;
            };
            let chunk_end = starts
                .get(*chunk_idx + 1)
                .copied()
                .unwrap_or(nrows)
                .min(chunk_start.saturating_add(ch.len()));
            let clear_start = start_row0.max(chunk_start);
            let clear_end = end_row0_exclusive.min(chunk_end);
            if clear_start >= clear_end {
                continue;
            }
            if clear_start == chunk_start && clear_end == chunk_end {
                delta = delta.saturating_sub(ch.computed_overlay.clear() as isize);
            } else {
                let start_in_chunk = clear_start.saturating_sub(chunk_start).min(ch.len());
                let end_in_chunk = clear_end.saturating_sub(chunk_start).min(ch.len());
                delta = delta.saturating_add(
                    ch.computed_overlay
                        .remove_range(start_in_chunk..end_in_chunk),
                );
            }
        }
        self.adjust_computed_overlay_bytes(delta);
    }

    fn clear_computed_overlay_cells_in_region(
        &mut self,
        cells: &[(SheetId, u32, u32)],
        affected_region: &Region,
    ) {
        let mut by_col: BTreeMap<(SheetId, u32), Vec<u32>> = BTreeMap::new();
        for (formula_sheet_id, row, col) in cells {
            let row0 = row.saturating_sub(1);
            let col0 = col.saturating_sub(1);
            let placement_region = Region::point(*formula_sheet_id, row0, col0);
            if placement_region.intersects(affected_region) {
                by_col
                    .entry((*formula_sheet_id, col0))
                    .or_default()
                    .push(row0);
            }
        }

        for ((formula_sheet_id, col0), mut rows) in by_col {
            rows.sort_unstable();
            rows.dedup();
            let sheet_name = self.graph.sheet_name(formula_sheet_id).to_string();
            let mut start = rows[0];
            let mut prev = rows[0];
            for row in rows.into_iter().skip(1) {
                if row == prev.saturating_add(1) {
                    prev = row;
                    continue;
                }
                self.clear_computed_overlay_col_row_range(
                    &sheet_name,
                    col0 as usize,
                    start as usize,
                    prev.saturating_add(1) as usize,
                );
                start = row;
                prev = row;
            }
            self.clear_computed_overlay_col_row_range(
                &sheet_name,
                col0 as usize,
                start as usize,
                prev.saturating_add(1) as usize,
            );
        }
    }

    fn clear_computed_overlay_after_row(&mut self, sheet: &str, start_row0: usize) {
        if !(self.config.arrow_storage_enabled && self.config.write_formula_overlay_enabled) {
            return;
        }

        let Some(asheet) = self.arrow_sheets.sheet_mut(sheet) else {
            return;
        };
        if start_row0 >= asheet.nrows as usize {
            return;
        }

        let starts = asheet.chunk_starts.clone();
        let nrows = asheet.nrows as usize;
        let mut delta = 0isize;
        for col in &mut asheet.columns {
            for (chunk_idx, ch) in col.chunks.iter_mut().enumerate() {
                let Some(&chunk_start) = starts.get(chunk_idx) else {
                    continue;
                };
                let chunk_end = starts
                    .get(chunk_idx + 1)
                    .copied()
                    .unwrap_or(nrows)
                    .min(chunk_start.saturating_add(ch.len()));
                if chunk_end <= start_row0 {
                    continue;
                }
                if chunk_start >= start_row0 {
                    delta = delta.saturating_sub(ch.computed_overlay.clear() as isize);
                } else {
                    let start_in_chunk = start_row0.saturating_sub(chunk_start).min(ch.len());
                    delta = delta
                        .saturating_add(ch.computed_overlay.remove_range(start_in_chunk..ch.len()));
                }
            }

            for (chunk_idx, ch) in &mut col.sparse_chunks {
                let Some(&chunk_start) = starts.get(*chunk_idx) else {
                    continue;
                };
                let chunk_end = starts
                    .get(*chunk_idx + 1)
                    .copied()
                    .unwrap_or(nrows)
                    .min(chunk_start.saturating_add(ch.len()));
                if chunk_end <= start_row0 {
                    continue;
                }
                if chunk_start >= start_row0 {
                    delta = delta.saturating_sub(ch.computed_overlay.clear() as isize);
                } else {
                    let start_in_chunk = start_row0.saturating_sub(chunk_start).min(ch.len());
                    delta = delta
                        .saturating_add(ch.computed_overlay.remove_range(start_in_chunk..ch.len()));
                }
            }
        }
        self.adjust_computed_overlay_bytes(delta);
    }

    fn clear_computed_overlay_after_col(&mut self, sheet: &str, start_col0: usize) {
        if !(self.config.arrow_storage_enabled && self.config.write_formula_overlay_enabled) {
            return;
        }

        let Some(asheet) = self.arrow_sheets.sheet_mut(sheet) else {
            return;
        };
        if start_col0 >= asheet.columns.len() {
            return;
        }

        let mut delta = 0isize;
        for col in asheet.columns.iter_mut().skip(start_col0) {
            for ch in &mut col.chunks {
                delta = delta.saturating_sub(ch.computed_overlay.clear() as isize);
            }
            for ch in col.sparse_chunks.values_mut() {
                delta = delta.saturating_sub(ch.computed_overlay.clear() as isize);
            }
        }
        self.adjust_computed_overlay_bytes(delta);
    }

    #[inline]
    fn literal_to_overlay_value(
        value: &LiteralValue,
        date_system: crate::engine::DateSystem,
    ) -> crate::arrow_store::OverlayValue {
        crate::arrow_store::OverlayValue::from_literal_value(value, date_system)
    }

    fn arrow_sheet_date_system(&self, sheet: &str) -> crate::engine::DateSystem {
        self.arrow_sheets
            .sheet(sheet)
            .map(|sheet| sheet.date_system)
            .unwrap_or(self.config.date_system)
    }

    /// Read a single cell's delta overlay entry (if present), preserving the distinction between
    /// absent and explicit `Empty`.
    fn read_delta_overlay_cell(&self, sheet: &str, row: u32, col: u32) -> Option<LiteralValue> {
        if !(self.config.arrow_storage_enabled && self.config.delta_overlay_enabled) {
            return None;
        }
        let asheet = self.arrow_sheets.sheet(sheet)?;
        let row0 = row.saturating_sub(1) as usize;
        let col0 = col.saturating_sub(1) as usize;
        if row0 >= asheet.nrows as usize || col0 >= asheet.columns.len() {
            return None;
        }
        let (ch_idx, in_off) = asheet.chunk_of_row(row0)?;
        let ch = asheet.columns[col0].chunk(ch_idx)?;
        ch.overlay
            .get_scalar(in_off)
            .map(|ov| ov.to_literal_for(asheet.date_system))
    }

    /// Read a single cell's computed overlay entry (if present), preserving the distinction
    /// between absent and explicit `Empty`.
    fn read_computed_overlay_cell(&self, sheet: &str, row: u32, col: u32) -> Option<LiteralValue> {
        if !(self.config.arrow_storage_enabled
            && self.config.delta_overlay_enabled
            && self.config.write_formula_overlay_enabled)
        {
            return None;
        }
        let asheet = self.arrow_sheets.sheet(sheet)?;
        let row0 = row.saturating_sub(1) as usize;
        let col0 = col.saturating_sub(1) as usize;
        if row0 >= asheet.nrows as usize || col0 >= asheet.columns.len() {
            return None;
        }
        let (ch_idx, in_off) = asheet.chunk_of_row(row0)?;
        let ch = asheet.columns[col0].chunk(ch_idx)?;
        ch.computed_overlay
            .get_scalar(in_off)
            .map(|ov| ov.to_literal_for(asheet.date_system))
    }

    fn set_delta_overlay_cell_raw(
        &mut self,
        sheet: &str,
        row: u32,
        col: u32,
        value: Option<LiteralValue>,
    ) {
        if !(self.config.arrow_storage_enabled && self.config.delta_overlay_enabled) {
            return;
        }

        self.ensure_arrow_sheet(sheet);
        let date_system = self.arrow_sheet_date_system(sheet);
        let ov_opt = value
            .as_ref()
            .map(|value| Self::literal_to_overlay_value(value, date_system));
        let row0 = row.saturating_sub(1) as usize;
        let col0 = col.saturating_sub(1) as usize;
        let asheet = self
            .arrow_sheets
            .sheet_mut(sheet)
            .expect("ArrowSheet must exist");

        let cur_cols = asheet.columns.len();
        if col0 >= cur_cols {
            asheet.insert_columns(cur_cols, (col0 + 1) - cur_cols);
        }
        if row0 >= asheet.nrows as usize {
            if asheet.columns.is_empty() {
                asheet.insert_columns(0, 1);
            }
            asheet.ensure_row_capacity(row0 + 1);
        }

        let Some((ch_idx, in_off)) = asheet.chunk_of_row(row0) else {
            return;
        };
        let Some(ch) = asheet.ensure_column_chunk_mut(col0, ch_idx) else {
            return;
        };

        if let Some(ov) = ov_opt {
            let _ = ch.overlay.set(in_off, ov);
        } else {
            let _ = ch.overlay.remove(in_off);
        }
    }

    fn set_computed_overlay_cell_raw(
        &mut self,
        sheet: &str,
        row: u32,
        col: u32,
        value: Option<LiteralValue>,
    ) {
        if !(self.config.arrow_storage_enabled
            && self.config.delta_overlay_enabled
            && self.config.write_formula_overlay_enabled)
        {
            return;
        }

        self.ensure_arrow_sheet(sheet);
        let date_system = self.arrow_sheet_date_system(sheet);
        let ov_opt = value
            .as_ref()
            .map(|value| Self::literal_to_overlay_value(value, date_system));
        let row0 = row.saturating_sub(1) as usize;
        let col0 = col.saturating_sub(1) as usize;
        let asheet = self
            .arrow_sheets
            .sheet_mut(sheet)
            .expect("ArrowSheet must exist");

        let cur_cols = asheet.columns.len();
        if col0 >= cur_cols {
            asheet.insert_columns(cur_cols, (col0 + 1) - cur_cols);
        }
        if row0 >= asheet.nrows as usize {
            if asheet.columns.is_empty() {
                asheet.insert_columns(0, 1);
            }
            asheet.ensure_row_capacity(row0 + 1);
        }

        let Some((ch_idx, in_off)) = asheet.chunk_of_row(row0) else {
            return;
        };
        let Some(ch) = asheet.ensure_column_chunk_mut(col0, ch_idx) else {
            return;
        };

        let delta = if let Some(ov) = ov_opt {
            ch.computed_overlay.set(in_off, ov)
        } else {
            ch.computed_overlay.remove(in_off)
        };
        self.adjust_computed_overlay_bytes(delta);
    }

    fn apply_arrow_undo_batch(&mut self, batch: &crate::engine::ArrowUndoBatch, undo: bool) {
        use crate::engine::ArrowOp;

        let iter: Box<dyn Iterator<Item = &ArrowOp>> = if undo {
            Box::new(batch.ops.iter().rev())
        } else {
            Box::new(batch.ops.iter())
        };

        for op in iter {
            match op {
                ArrowOp::SetDeltaCell {
                    sheet_id,
                    row0,
                    col0,
                    old,
                    new,
                } => {
                    let sheet = self.graph.sheet_name(*sheet_id).to_string();
                    let v = if undo { old.clone() } else { new.clone() };
                    self.set_delta_overlay_cell_raw(&sheet, row0 + 1, col0 + 1, v);
                }
                ArrowOp::SetComputedCell {
                    sheet_id,
                    row0,
                    col0,
                    old,
                    new,
                } => {
                    let sheet = self.graph.sheet_name(*sheet_id).to_string();
                    let v = if undo { old.clone() } else { new.clone() };
                    self.set_computed_overlay_cell_raw(&sheet, row0 + 1, col0 + 1, v);
                }
                ArrowOp::RestoreComputedRect {
                    sheet_id,
                    sr0,
                    sc0,
                    er0,
                    ec0,
                    old,
                    new,
                } => {
                    let sheet = self.graph.sheet_name(*sheet_id).to_string();
                    let vals = if undo { old } else { new };
                    let height = (*er0).saturating_sub(*sr0) as usize + 1;
                    let width = (*ec0).saturating_sub(*sc0) as usize + 1;
                    for r in 0..height {
                        for c in 0..width {
                            let v = vals
                                .get(r)
                                .and_then(|row| row.get(c))
                                .cloned()
                                .unwrap_or(LiteralValue::Empty);
                            self.set_computed_overlay_cell_raw(
                                &sheet,
                                *sr0 + 1 + r as u32,
                                *sc0 + 1 + c as u32,
                                Some(v),
                            );
                        }
                    }
                }
                ArrowOp::InsertRows {
                    sheet_id,
                    before0,
                    count,
                } => {
                    let sheet = self.graph.sheet_name(*sheet_id).to_string();
                    self.ensure_arrow_sheet(&sheet);
                    if let Some(asheet) = self.arrow_sheets.sheet_mut(&sheet) {
                        if undo {
                            asheet.delete_rows(*before0 as usize, *count as usize);
                        } else {
                            asheet.insert_rows(*before0 as usize, *count as usize);
                        }
                    }
                }
                ArrowOp::InsertCols {
                    sheet_id,
                    before0,
                    count,
                } => {
                    let sheet = self.graph.sheet_name(*sheet_id).to_string();
                    self.ensure_arrow_sheet(&sheet);
                    if let Some(asheet) = self.arrow_sheets.sheet_mut(&sheet) {
                        if undo {
                            asheet.delete_columns(*before0 as usize, *count as usize);
                        } else {
                            asheet.insert_columns(*before0 as usize, *count as usize);
                        }
                    }
                }
            }
        }
    }

    fn record_spill_ops_into_arrow_undo(
        &mut self,
        undo: &mut crate::engine::ArrowUndoBatch,
        events: &[crate::engine::ChangeEvent],
    ) {
        use crate::engine::ChangeEvent;
        use formualizer_common::LiteralValue;

        #[allow(clippy::type_complexity)]
        let rect_from_snapshot =
            |snap: &crate::engine::graph::editor::change_log::SpillSnapshot|
             -> Option<(SheetId, u32, u32, u32, u32, Vec<Vec<LiteralValue>>)> {
                if snap.target_cells.is_empty() {
                    return None;
                }
                let sheet_id = snap.target_cells[0].sheet_id;
                let sr0 = snap.target_cells[0].coord.row();
                let sc0 = snap.target_cells[0].coord.col();
                if snap.values.is_empty() || snap.values[0].is_empty() {
                    return None;
                }
                let h = snap.values.len() as u32;
                let w = snap.values[0].len() as u32;
                let er0 = sr0.saturating_add(h.saturating_sub(1));
                let ec0 = sc0.saturating_add(w.saturating_sub(1));
                Some((sheet_id, sr0, sc0, er0, ec0, snap.values.clone()))
            };

        for ev in events {
            match ev {
                ChangeEvent::SpillCommitted { old, new, .. } => {
                    if let Some((sid, sr0, sc0, er0, ec0, new_vals)) = rect_from_snapshot(new) {
                        let old_vals = if let Some(old_snap) = old {
                            rect_from_snapshot(old_snap)
                                .map(|(_, _, _, _, _, v)| v)
                                .unwrap_or_else(|| {
                                    vec![
                                        vec![LiteralValue::Empty; new_vals[0].len()];
                                        new_vals.len()
                                    ]
                                })
                        } else {
                            vec![vec![LiteralValue::Empty; new_vals[0].len()]; new_vals.len()]
                        };
                        undo.record_restore_computed_rect(
                            sid, sr0, sc0, er0, ec0, old_vals, new_vals,
                        );
                    }
                }
                ChangeEvent::SpillCleared { old, .. } => {
                    if let Some((sid, sr0, sc0, er0, ec0, old_vals)) = rect_from_snapshot(old) {
                        let new_vals =
                            vec![vec![LiteralValue::Empty; old_vals[0].len()]; old_vals.len()];
                        undo.record_restore_computed_rect(
                            sid, sr0, sc0, er0, ec0, old_vals, new_vals,
                        );
                    }
                }
                _ => {}
            }
        }
    }

    /// Mirror a value into the computed overlay (formula/spill outputs).
    ///
    /// This path is subject to `EvalConfig.max_overlay_memory_bytes`.
    /// If the cap is exceeded, computed overlays are compacted into base lanes.
    fn mirror_value_to_computed_overlay(
        &mut self,
        sheet: &str,
        row: u32,
        col: u32,
        value: &LiteralValue,
    ) {
        if !(self.config.arrow_storage_enabled
            && self.config.delta_overlay_enabled
            && self.config.write_formula_overlay_enabled)
        {
            return;
        }
        if self.computed_overlay_mirroring_disabled {
            return;
        }

        let date_system = self.arrow_sheet_date_system(sheet);
        let ov = Self::literal_to_overlay_value(value, date_system);
        self.write_computed_overlay_value_0based(
            sheet,
            row.saturating_sub(1),
            col.saturating_sub(1),
            ov,
        );
    }

    fn write_computed_overlay_value_0based(
        &mut self,
        sheet: &str,
        row0: u32,
        col0: u32,
        value: OverlayValue,
    ) {
        if !(self.config.arrow_storage_enabled
            && self.config.delta_overlay_enabled
            && self.config.write_formula_overlay_enabled)
        {
            return;
        }
        if self.computed_overlay_mirroring_disabled {
            return;
        }

        self.ensure_arrow_sheet(sheet);

        let row0 = row0 as usize;
        let col0 = col0 as usize;
        let asheet = self
            .arrow_sheets
            .sheet_mut(sheet)
            .expect("ArrowSheet must exist");

        let cur_cols = asheet.columns.len();
        if col0 >= cur_cols {
            asheet.insert_columns(cur_cols, (col0 + 1) - cur_cols);
        }

        if row0 >= asheet.nrows as usize {
            if asheet.columns.is_empty() {
                asheet.insert_columns(0, 1);
            }
            asheet.ensure_row_capacity(row0 + 1);
        }

        let Some((ch_idx, in_off)) = asheet.chunk_of_row(row0) else {
            return;
        };
        let Some(ch) = asheet.ensure_column_chunk_mut(col0, ch_idx) else {
            return;
        };

        let delta = ch.computed_overlay.set_scalar(in_off, value);
        self.adjust_computed_overlay_bytes(delta);

        if let Some(cap) = self.config.max_overlay_memory_bytes
            && self.computed_overlay_bytes_estimate > cap
        {
            self.disable_computed_overlay_mirroring_due_to_budget(cap);
        }
    }

    pub(crate) fn plan_computed_write_coalescing(
        &self,
        buffer: &ComputedWriteBuffer,
    ) -> ComputedWriteCoalescingPlan {
        self.plan_computed_write_coalescing_from_writes(buffer.writes().iter().cloned())
    }

    fn plan_owned_computed_write_coalescing(
        &self,
        writes: Vec<ComputedWrite>,
    ) -> ComputedWriteCoalescingPlan {
        self.plan_computed_write_coalescing_from_writes(writes)
    }

    fn plan_computed_write_coalescing_from_writes(
        &self,
        writes: impl IntoIterator<Item = ComputedWrite>,
    ) -> ComputedWriteCoalescingPlan {
        let mut groups: BTreeMap<ComputedWriteChunkKey, Vec<ComputedWriteChunkEntryPlan>> =
            BTreeMap::new();
        let mut input_cells = 0usize;

        for write in writes {
            match write {
                ComputedWrite::Cell {
                    seq,
                    sheet_id,
                    row0,
                    col0,
                    value,
                } => {
                    input_cells = input_cells.saturating_add(1);
                    self.push_computed_write_plan_entry(
                        &mut groups,
                        seq,
                        sheet_id,
                        row0,
                        col0,
                        value,
                    );
                }
                ComputedWrite::Rect {
                    seq,
                    sheet_id,
                    sr0,
                    sc0,
                    values,
                } => {
                    for (r_off, row) in values.into_iter().enumerate() {
                        for (c_off, value) in row.into_iter().enumerate() {
                            input_cells = input_cells.saturating_add(1);
                            self.push_computed_write_plan_entry(
                                &mut groups,
                                seq,
                                sheet_id,
                                sr0.saturating_add(r_off as u32),
                                sc0.saturating_add(c_off as u32),
                                value,
                            );
                        }
                    }
                }
            }
        }

        let mut plan = ComputedWriteCoalescingPlan {
            chunks: Vec::with_capacity(groups.len()),
            input_cells,
            coalesced_cells: 0,
            overwritten_cells: 0,
        };
        for (key, entries) in groups {
            let (chunk_plan, overwritten) = ComputedWriteChunkPlan::from_group(key, entries);
            plan.coalesced_cells = plan
                .coalesced_cells
                .saturating_add(chunk_plan.entries.len());
            plan.overwritten_cells = plan.overwritten_cells.saturating_add(overwritten);
            plan.chunks.push(chunk_plan);
        }
        debug_assert_eq!(
            plan.input_cells,
            plan.coalesced_cells.saturating_add(plan.overwritten_cells)
        );
        plan
    }

    fn push_computed_write_plan_entry(
        &self,
        groups: &mut BTreeMap<ComputedWriteChunkKey, Vec<ComputedWriteChunkEntryPlan>>,
        seq: u64,
        sheet_id: SheetId,
        row0: u32,
        col0: u32,
        value: OverlayValue,
    ) {
        let (chunk_idx, chunk_start_row0, row_in_chunk) =
            self.locate_computed_write_chunk(sheet_id, row0);
        let key = ComputedWriteChunkKey {
            sheet_id,
            col0,
            chunk_idx,
            chunk_start_row0,
        };
        groups
            .entry(key)
            .or_default()
            .push(ComputedWriteChunkEntryPlan {
                row_in_chunk,
                seq,
                value,
            });
    }

    fn locate_computed_write_chunk(&self, sheet_id: SheetId, row0: u32) -> (usize, u32, usize) {
        let sheet_name = self.graph.sheet_name(sheet_id);
        if let Some(sheet) = self.arrow_sheets.sheet(sheet_name) {
            return Self::locate_row_in_sheet_for_computed_write_plan(sheet, row0 as usize);
        }
        Self::locate_row_in_empty_sheet_for_computed_write_plan(row0 as usize, 32 * 1024)
    }

    fn locate_row_in_sheet_for_computed_write_plan(
        sheet: &crate::arrow_store::ArrowSheet,
        row0: usize,
    ) -> (usize, u32, usize) {
        if row0 < sheet.nrows as usize
            && let Some((chunk_idx, row_in_chunk)) = sheet.chunk_of_row(row0)
        {
            let chunk_start = sheet.chunk_starts.get(chunk_idx).copied().unwrap_or(0);
            return (chunk_idx, chunk_start as u32, row_in_chunk);
        }

        let chunk_rows = sheet.chunk_rows.max(1);
        if sheet.chunk_starts.is_empty() {
            return Self::locate_row_in_empty_sheet_for_computed_write_plan(row0, chunk_rows);
        }

        let mut chunk_idx = sheet.chunk_starts.len().saturating_sub(1);
        let mut chunk_start = sheet.chunk_starts[chunk_idx];
        while chunk_start.saturating_add(chunk_rows) <= row0 {
            chunk_idx = chunk_idx.saturating_add(1);
            chunk_start = chunk_start.saturating_add(chunk_rows);
        }
        (
            chunk_idx,
            chunk_start as u32,
            row0.saturating_sub(chunk_start),
        )
    }

    fn locate_row_in_empty_sheet_for_computed_write_plan(
        row0: usize,
        chunk_rows: usize,
    ) -> (usize, u32, usize) {
        let chunk_rows = chunk_rows.max(1);
        let chunk_idx = row0 / chunk_rows;
        let chunk_start = chunk_idx.saturating_mul(chunk_rows);
        (
            chunk_idx,
            chunk_start as u32,
            row0.saturating_sub(chunk_start),
        )
    }

    #[cfg(test)]
    pub(crate) fn debug_plan_computed_write_coalescing(
        &self,
        buffer: &ComputedWriteBuffer,
    ) -> ComputedWriteCoalescingPlan {
        self.plan_computed_write_coalescing(buffer)
    }

    fn record_computed_write_buffer_delta(
        &self,
        buffer: &ComputedWriteBuffer,
        delta: &mut DeltaCollector,
    ) {
        if delta.mode == DeltaMode::Off {
            return;
        }
        let mut final_values = BTreeMap::new();
        for write in buffer.writes() {
            match write {
                ComputedWrite::Cell {
                    sheet_id,
                    row0,
                    col0,
                    value,
                    ..
                } => {
                    final_values.insert((*sheet_id, *row0, *col0), value.clone());
                }
                ComputedWrite::Rect {
                    sheet_id,
                    sr0,
                    sc0,
                    values,
                    ..
                } => {
                    for (row_offset, row) in values.iter().enumerate() {
                        for (col_offset, value) in row.iter().enumerate() {
                            final_values.insert(
                                (
                                    *sheet_id,
                                    sr0.saturating_add(row_offset as u32),
                                    sc0.saturating_add(col_offset as u32),
                                ),
                                value.clone(),
                            );
                        }
                    }
                }
            }
        }
        for ((sheet_id, row0, col0), value) in final_values {
            let old = self
                .read_cell_value(self.graph.sheet_name(sheet_id), row0 + 1, col0 + 1)
                .unwrap_or(LiteralValue::Empty);
            if old != value.to_literal_for(self.config.date_system) {
                delta.record_cell(sheet_id, row0, col0);
            }
        }
    }

    pub(crate) fn flush_computed_write_buffer(
        &mut self,
        buffer: &mut ComputedWriteBuffer,
    ) -> Result<(), ExcelError> {
        if buffer.is_empty() {
            return Ok(());
        }

        // Keep ownership of all pending writes until the final request
        // checkpoint and bounded commit-window preflight succeed so failures
        // remain retry safe. The plan and flush that follow are prevalidated
        // and contain no cancellation point.
        self.resource_checkpoint(0)?;
        let commit_started = self.preflight_evaluation_commit_window(buffer.len())?;
        let plan = self.plan_owned_computed_write_coalescing(buffer.take_writes());
        self.flush_computed_write_plan(plan);
        self.observe_evaluation_commit_window(commit_started);

        Ok(())
    }

    fn flush_computed_write_plan(&mut self, plan: ComputedWriteCoalescingPlan) {
        for chunk in plan.chunks {
            self.flush_computed_write_chunk_plan(chunk);
        }
    }

    fn flush_computed_write_chunk_plan(&mut self, chunk: ComputedWriteChunkPlan) {
        match &chunk.shape {
            ComputedWriteChunkPlanShape::Point => {
                self.flush_computed_write_chunk_plan_as_points(chunk);
            }
            ComputedWriteChunkPlanShape::SparseOffsets { .. } => {
                self.flush_computed_write_chunk_plan_as_sparse_fragment_or_points(chunk);
            }
            ComputedWriteChunkPlanShape::DenseRange { .. } => {
                self.flush_computed_write_chunk_plan_as_dense_fragment(chunk);
            }
            ComputedWriteChunkPlanShape::RunRange { len, runs, .. } => {
                if Self::should_emit_computed_run_fragment(*len, *runs) {
                    self.flush_computed_write_chunk_plan_as_run_fragment(chunk);
                } else {
                    self.flush_computed_write_chunk_plan_as_dense_fragment(chunk);
                }
            }
        }
    }

    #[inline]
    fn should_emit_computed_run_fragment(len: usize, runs: usize) -> bool {
        runs <= len / 2
    }

    fn flush_computed_write_chunk_plan_as_points(&mut self, chunk: ComputedWriteChunkPlan) {
        let sheet_name = self.graph.sheet_name(chunk.sheet_id).to_string();
        for entry in chunk.entries {
            let row0 = chunk
                .chunk_start_row0
                .saturating_add(entry.row_in_chunk as u32);
            self.write_computed_overlay_value_0based(&sheet_name, row0, chunk.col0, entry.value);
        }
    }

    fn flush_computed_write_chunk_plan_as_sparse_fragment_or_points(
        &mut self,
        chunk: ComputedWriteChunkPlan,
    ) {
        let point_estimate = Self::computed_write_chunk_plan_point_estimate(&chunk);
        let sheet_id = chunk.sheet_id;
        let col0 = chunk.col0;
        let chunk_idx = chunk.chunk_idx;
        let chunk_start_row0 = chunk.chunk_start_row0;
        let items: Vec<(usize, OverlayValue)> = chunk
            .entries
            .into_iter()
            .map(|entry| (entry.row_in_chunk, entry.value))
            .collect();
        match OverlayFragment::sparse_offsets_if_estimated_smaller_than_points(
            items,
            point_estimate,
        ) {
            Some(Ok(fragment)) => {
                self.apply_computed_overlay_fragment(sheet_id, col0, chunk_idx, fragment);
            }
            Some(Err(cells)) => {
                self.flush_computed_overlay_cells_as_points(
                    sheet_id,
                    col0,
                    chunk_start_row0,
                    cells,
                );
            }
            None => {}
        }
    }

    #[inline]
    fn computed_write_chunk_plan_point_estimate(chunk: &ComputedWriteChunkPlan) -> usize {
        chunk
            .entries
            .iter()
            .map(|entry| ComputedWriteBuffer::estimate_value_bytes(&entry.value))
            .fold(0usize, usize::saturating_add)
    }

    fn flush_computed_overlay_cells_as_points(
        &mut self,
        sheet_id: SheetId,
        col0: u32,
        chunk_start_row0: u32,
        cells: Vec<(usize, OverlayValue)>,
    ) {
        let sheet_name = self.graph.sheet_name(sheet_id).to_string();
        for (row_in_chunk, value) in cells {
            let row0 = chunk_start_row0.saturating_add(row_in_chunk as u32);
            self.write_computed_overlay_value_0based(&sheet_name, row0, col0, value);
        }
    }

    fn flush_computed_write_chunk_plan_as_dense_fragment(&mut self, chunk: ComputedWriteChunkPlan) {
        if chunk.entries.is_empty() {
            return;
        }
        let start = chunk.entries[0].row_in_chunk;
        let values: Vec<OverlayValue> =
            chunk.entries.into_iter().map(|entry| entry.value).collect();
        if let Some(fragment) = OverlayFragment::dense_range(start, values) {
            self.apply_computed_overlay_fragment(
                chunk.sheet_id,
                chunk.col0,
                chunk.chunk_idx,
                fragment,
            );
        }
    }

    fn flush_computed_write_chunk_plan_as_run_fragment(&mut self, chunk: ComputedWriteChunkPlan) {
        if chunk.entries.is_empty() {
            return;
        }
        let start = chunk.entries[0].row_in_chunk;
        let values: Vec<OverlayValue> =
            chunk.entries.into_iter().map(|entry| entry.value).collect();
        if let Some(fragment) = OverlayFragment::run_range(start, values) {
            self.apply_computed_overlay_fragment(
                chunk.sheet_id,
                chunk.col0,
                chunk.chunk_idx,
                fragment,
            );
        }
    }

    fn apply_computed_overlay_fragment(
        &mut self,
        sheet_id: SheetId,
        col0: u32,
        chunk_idx: usize,
        fragment: OverlayFragment,
    ) {
        if !(self.config.arrow_storage_enabled
            && self.config.delta_overlay_enabled
            && self.config.write_formula_overlay_enabled)
        {
            return;
        }
        if self.computed_overlay_mirroring_disabled {
            return;
        }

        let sheet_name = self.graph.sheet_name(sheet_id).to_string();
        self.ensure_arrow_sheet(&sheet_name);

        let col0 = col0 as usize;
        let asheet = self
            .arrow_sheets
            .sheet_mut(&sheet_name)
            .expect("ArrowSheet must exist");

        let cur_cols = asheet.columns.len();
        if col0 >= cur_cols {
            asheet.insert_columns(cur_cols, (col0 + 1) - cur_cols);
        }

        let start_row0 = asheet
            .chunk_starts
            .get(chunk_idx)
            .copied()
            .unwrap_or_else(|| chunk_idx.saturating_mul(asheet.chunk_rows.max(1)));
        let required_rows =
            start_row0.saturating_add(fragment.max_covered_offset().saturating_add(1));
        if required_rows > asheet.nrows as usize {
            if asheet.columns.is_empty() {
                asheet.insert_columns(0, 1);
            }
            asheet.ensure_row_capacity(required_rows);
        }

        let Some(ch) = asheet.ensure_column_chunk_mut(col0, chunk_idx) else {
            return;
        };
        let delta = ch.computed_overlay.apply_fragment(fragment);
        self.adjust_computed_overlay_bytes(delta);

        if let Some(cap) = self.config.max_overlay_memory_bytes
            && self.computed_overlay_bytes_estimate > cap
        {
            self.disable_computed_overlay_mirroring_due_to_budget(cap);
        }
    }

    #[inline]
    fn adjust_computed_overlay_bytes(&mut self, delta: isize) {
        if delta >= 0 {
            self.computed_overlay_bytes_estimate = self
                .computed_overlay_bytes_estimate
                .saturating_add(delta as usize);
        } else {
            self.computed_overlay_bytes_estimate = self
                .computed_overlay_bytes_estimate
                .saturating_sub((-delta) as usize);
        }
    }

    fn clear_all_computed_overlays(&mut self) {
        let mut freed_total = 0usize;
        for sh in self.arrow_sheets.sheets.iter_mut() {
            for col in sh.columns.iter_mut() {
                for ch in col.chunks.iter_mut() {
                    freed_total = freed_total.saturating_add(ch.computed_overlay.clear());
                }
                for ch in col.sparse_chunks.values_mut() {
                    freed_total = freed_total.saturating_add(ch.computed_overlay.clear());
                }
            }
        }
        self.computed_overlay_bytes_estimate = self
            .computed_overlay_bytes_estimate
            .saturating_sub(freed_total);
    }

    fn disable_computed_overlay_mirroring_due_to_budget(&mut self, _cap: usize) {
        // Phase 1 (ticket 610): Arrow-truth is the only supported mode.
        // Handle budget pressure by compacting computed overlays into base lanes.
        self.compact_all_computed_overlays();
    }

    /// Fold all computed overlay entries across all sheets into their base arrays.
    /// This preserves data while freeing overlay memory, allowing mirroring to continue.
    fn compact_all_computed_overlays(&mut self) {
        let mut freed_total = 0usize;
        for sheet in self.arrow_sheets.sheets.iter_mut() {
            for col_idx in 0..sheet.columns.len() {
                // Dense chunks
                let num_dense = sheet.columns[col_idx].chunks.len();
                for ch_idx in 0..num_dense {
                    freed_total += sheet.compact_computed_overlay_chunk(col_idx, ch_idx);
                }
                // Sparse chunks
                let sparse_keys: Vec<usize> = sheet.columns[col_idx]
                    .sparse_chunks
                    .keys()
                    .copied()
                    .collect();
                for ch_idx in sparse_keys {
                    freed_total += sheet.compact_computed_overlay_sparse_chunk(col_idx, ch_idx);
                }
            }
        }
        self.computed_overlay_bytes_estimate = self
            .computed_overlay_bytes_estimate
            .saturating_sub(freed_total);
        self.overlay_compactions = self.overlay_compactions.saturating_add(1);
    }

    fn mirror_vertex_value_to_overlay(&mut self, vertex_id: VertexId, value: &LiteralValue) {
        let _ = self.record_vertex_value_to_overlay(vertex_id, value, None);
    }

    fn record_vertex_value_to_overlay(
        &mut self,
        vertex_id: VertexId,
        value: &LiteralValue,
        computed_writes: Option<&mut ComputedWriteBuffer>,
    ) -> Result<(), ExcelError> {
        if !(self.config.arrow_storage_enabled
            && self.config.delta_overlay_enabled
            && self.config.write_formula_overlay_enabled)
        {
            return Ok(());
        }
        if self.computed_overlay_mirroring_disabled {
            return Ok(());
        }
        if !matches!(
            self.graph.get_vertex_kind(vertex_id),
            VertexKind::FormulaScalar | VertexKind::FormulaArray
        ) {
            return Ok(());
        }
        let Some(cell) = self.graph.get_cell_ref(vertex_id) else {
            return Ok(());
        };
        let sheet_name = self.graph.sheet_name(cell.sheet_id).to_string();
        let date_system = self.arrow_sheet_date_system(&sheet_name);
        let ov = Self::literal_to_overlay_value(value, date_system);
        if let Some(buffer) = computed_writes {
            buffer.push_cell(cell.sheet_id, cell.coord.row(), cell.coord.col(), ov);
            if self.should_flush_computed_write_buffer(buffer) {
                self.flush_computed_write_buffer(buffer)?;
            }
        } else {
            self.write_computed_overlay_value_0based(
                &sheet_name,
                cell.coord.row(),
                cell.coord.col(),
                ov,
            );
        }
        Ok(())
    }

    #[inline]
    fn should_flush_computed_write_buffer(&self, buffer: &ComputedWriteBuffer) -> bool {
        self.config.max_overlay_memory_bytes.is_some_and(|cap| {
            if cap == 0 {
                return false;
            }
            self.computed_overlay_bytes_estimate
                .saturating_add(buffer.estimated_bytes())
                > cap
        })
    }

    /// Estimated memory usage for computed overlays (formula/spill mirroring).
    pub fn overlay_memory_usage(&self) -> usize {
        self.computed_overlay_bytes_estimate
    }

    #[cfg(test)]
    pub(crate) fn debug_overlay_compactions(&self) -> u64 {
        self.overlay_compactions
    }

    #[cfg(test)]
    pub(crate) fn debug_recompute_computed_overlay_bytes(&mut self) -> usize {
        let mut total = 0usize;
        for sheet in &self.arrow_sheets.sheets {
            for column in &sheet.columns {
                for chunk in &column.chunks {
                    total = total.saturating_add(chunk.computed_overlay.estimated_bytes());
                }
                for chunk in column.sparse_chunks.values() {
                    total = total.saturating_add(chunk.computed_overlay.estimated_bytes());
                }
            }
        }
        self.computed_overlay_bytes_estimate = total;
        total
    }

    fn resolve_sheet_locator_for_write(
        &mut self,
        loc: formualizer_common::SheetLocator<'_>,
        current_sheet: &str,
    ) -> Result<SheetId, ExcelError> {
        Ok(match loc {
            formualizer_common::SheetLocator::Id(id) => id,
            formualizer_common::SheetLocator::Name(name) => self.graph.sheet_id_mut(name.as_ref()),
            formualizer_common::SheetLocator::Current => self.graph.sheet_id_mut(current_sheet),
        })
    }

    fn resolve_sheet_locator_for_read(
        &self,
        loc: formualizer_common::SheetLocator<'_>,
        current_sheet: &str,
    ) -> Result<SheetId, ExcelError> {
        match loc {
            formualizer_common::SheetLocator::Id(id) => Ok(id),
            formualizer_common::SheetLocator::Name(name) => self
                .graph
                .sheet_id(name.as_ref())
                .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref)),
            formualizer_common::SheetLocator::Current => self
                .graph
                .sheet_id(current_sheet)
                .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref)),
        }
    }

    /// Set a cell value
    pub fn set_cell_value(
        &mut self,
        sheet: &str,
        row: u32,
        col: u32,
        value: LiteralValue,
    ) -> Result<(), ExcelError> {
        self.observe_function_semantic_epoch()?;
        let sheet_existed = self.graph.sheet_id(sheet).is_some();
        let sheet_id = self.graph.sheet_id_mut(sheet);
        let cell_ref = CellRef::new(sheet_id, Coord::from_excel(row, col, true, true));
        let replaced_formula =
            self.graph
                .get_vertex_id_for_address(&cell_ref)
                .is_some_and(|vertex| {
                    matches!(
                        self.graph.get_vertex_kind(*vertex),
                        VertexKind::FormulaScalar | VertexKind::FormulaArray
                    )
                });
        self.demote_span_containing_cell_for_write(
            sheet_id,
            row.saturating_sub(1),
            col.saturating_sub(1),
        )
        .map_err(Self::editor_error_to_excel)?;
        self.graph.set_cell_value(sheet, row, col, value.clone())?;
        self.record_formula_plane_changed_cell(sheet, row, col);
        if !sheet_existed || replaced_formula {
            self.mark_topology_edited();
        }
        // Mirror into Arrow overlay when enabled
        self.mirror_value_to_overlay(sheet, row, col, &value);
        // Advance snapshot to reflect external mutation
        self.snapshot_id
            .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        self.has_edited = true;
        Ok(())
    }

    /// Record a single-cell change in FormulaPlane authority so the next
    /// `evaluate_all` under `AuthoritativeExperimental` can derive bounded
    /// span work from `FormulaConsumerReadIndex` instead of recomputing every
    /// active span.
    fn record_formula_plane_changed_cell(&mut self, sheet: &str, row: u32, col: u32) {
        if self.config.formula_plane_mode == FormulaPlaneMode::Off {
            return;
        }
        let sheet_id = self.graph.sheet_id_mut(sheet);
        self.record_formula_plane_structural_change(StructuralScope::Cell {
            sheet: sheet_id,
            row: row.saturating_sub(1),
            col: col.saturating_sub(1),
        });
    }

    fn record_formula_plane_change_for_event(&mut self, event: &ChangeEvent) {
        if self.config.formula_plane_mode == FormulaPlaneMode::Off {
            return;
        }

        match event {
            ChangeEvent::SetValue { addr, .. } | ChangeEvent::SetFormula { addr, .. } => {
                self.record_formula_plane_structural_change(StructuralScope::Cell {
                    sheet: addr.sheet_id,
                    row: addr.coord.row(),
                    col: addr.coord.col(),
                });
            }
            ChangeEvent::SpillCommitted { new, .. } => {
                if let Some(scope) = Self::formula_plane_region_from_cells(&new.target_cells) {
                    self.record_formula_plane_structural_change(scope);
                }
            }
            ChangeEvent::SpillCleared { old, .. } => {
                if let Some(scope) = Self::formula_plane_region_from_cells(&old.target_cells) {
                    self.record_formula_plane_structural_change(scope);
                }
            }
            ChangeEvent::DefineName { .. }
            | ChangeEvent::UpdateName { .. }
            | ChangeEvent::DeleteName { .. }
            | ChangeEvent::NamedRangeAdjusted { .. } => {
                // Direct name events are preflighted by the logged-name APIs.
                // Structural entry points preflight spans before emitting a
                // NamedRangeAdjusted event. Epoch changes only rebuild caches.
                self.record_formula_plane_structural_change(StructuralScope::AllSheets);
            }
            ChangeEvent::VertexMoved { .. } | ChangeEvent::FormulaAdjusted { .. } => {
                // Structural entry points publish their axis delta once after
                // graph, Arrow, and span geometry commits.
            }
            ChangeEvent::SetRowVisibility { sheet_id, row0, .. } => {
                self.record_formula_plane_structural_change(StructuralScope::Region(
                    Region::whole_row(*sheet_id, *row0),
                ));
            }
            ChangeEvent::AddVertex { .. }
            | ChangeEvent::RemoveVertex { .. }
            | ChangeEvent::EdgeAdded { .. }
            | ChangeEvent::EdgeRemoved { .. }
            | ChangeEvent::CompoundStart { .. }
            | ChangeEvent::CompoundEnd { .. }
            | ChangeEvent::StagedFormulaCellChanged { .. } => {}
        }
    }

    fn record_formula_plane_structural_change(&mut self, scope: StructuralScope) {
        if self.config.formula_plane_mode == FormulaPlaneMode::Off {
            return;
        }

        match scope {
            StructuralScope::Cell { sheet, row, col } => {
                self.graph
                    .mark_formula_region_dirty(Region::point(sheet, row, col));
            }
            StructuralScope::Region(region) => {
                self.graph.mark_formula_region_dirty(region);
            }
            StructuralScope::Sheet(sheet_id) => {
                self.graph
                    .mark_formula_region_dirty(Region::whole_sheet(sheet_id));
            }
            StructuralScope::RemovedSheet(sheet_id) => {
                let removed_refs = {
                    let authority = self.graph.formula_authority();
                    authority
                        .active_span_refs()
                        .into_iter()
                        .filter(|span_ref| {
                            authority
                                .plane
                                .spans
                                .get(*span_ref)
                                .map(|span| span.sheet_id == sheet_id)
                                .unwrap_or(false)
                        })
                        .collect::<Vec<_>>()
                };

                {
                    let authority = self.graph.formula_authority_mut();
                    for span_ref in removed_refs {
                        authority.plane.remove_span(span_ref);
                    }
                    let _ = authority.rebuild_indexes();
                }
                self.graph
                    .mark_all_formula_spans_dirty(WholeSpanDirtyReason::GlobalInvalidation);
            }
            StructuralScope::OpaqueGlobal => {
                let _ = self.graph.formula_authority_mut().rebuild_indexes();
                self.graph
                    .mark_all_formula_spans_dirty(WholeSpanDirtyReason::GlobalInvalidation);
            }
            StructuralScope::AllSheets => {
                // Name/table mutations dirty their exact graph dependents,
                // and name-dependent spans are demoted by the name invalidation
                // registry. A topology rebuild is cache invalidation only.
                let _ = self.graph.formula_authority_mut().rebuild_indexes();
            }
        }
    }

    fn formula_plane_region_from_cells(cells: &[CellRef]) -> Option<StructuralScope> {
        let first = cells.first()?;
        let sheet_id = first.sheet_id;
        if cells.iter().any(|cell| cell.sheet_id != sheet_id) {
            return Some(StructuralScope::OpaqueGlobal);
        }
        let mut row_start = first.coord.row();
        let mut row_end = row_start;
        let mut col_start = first.coord.col();
        let mut col_end = col_start;
        for cell in cells.iter().skip(1) {
            row_start = row_start.min(cell.coord.row());
            row_end = row_end.max(cell.coord.row());
            col_start = col_start.min(cell.coord.col());
            col_end = col_end.max(cell.coord.col());
        }
        Some(StructuralScope::Region(Region::rect(
            sheet_id, row_start, row_end, col_start, col_end,
        )))
    }

    pub fn set_cell_value_ref(
        &mut self,
        cell: formualizer_common::SheetCellRef<'_>,
        current_sheet: &str,
        value: LiteralValue,
    ) -> Result<(), ExcelError> {
        let owned = cell.into_owned();
        let sheet_id = self.resolve_sheet_locator_for_write(owned.sheet, current_sheet)?;
        let sheet_name = self.graph.sheet_name(sheet_id).to_string();
        self.set_cell_value(
            &sheet_name,
            owned.coord.row() + 1,
            owned.coord.col() + 1,
            value,
        )
    }

    pub fn set_cell_formula_ref(
        &mut self,
        cell: formualizer_common::SheetCellRef<'_>,
        current_sheet: &str,
        ast: ASTNode,
    ) -> Result<(), ExcelError> {
        let owned = cell.into_owned();
        let sheet_id = self.resolve_sheet_locator_for_write(owned.sheet, current_sheet)?;
        let sheet_name = self.graph.sheet_name(sheet_id).to_string();
        self.set_cell_formula(
            &sheet_name,
            owned.coord.row() + 1,
            owned.coord.col() + 1,
            ast,
        )
    }

    pub fn get_cell_value_ref(
        &self,
        cell: formualizer_common::SheetCellRef<'_>,
        current_sheet: &str,
    ) -> Result<Option<LiteralValue>, ExcelError> {
        let owned = cell.into_owned();
        let sheet_id = self.resolve_sheet_locator_for_read(owned.sheet, current_sheet)?;
        let sheet_name = self.graph.sheet_name(sheet_id);
        Ok(self.get_cell_value(sheet_name, owned.coord.row() + 1, owned.coord.col() + 1))
    }

    pub fn resolve_range_view_sheet_ref<'c>(
        &'c self,
        r: &formualizer_common::SheetRef<'_>,
        current_sheet: &str,
    ) -> Result<RangeView<'c>, ExcelError> {
        use formualizer_common::SheetLocator;

        let sheet_to_opt_name = |loc: SheetLocator<'_>| -> Result<Option<String>, ExcelError> {
            match loc {
                SheetLocator::Current => Ok(None),
                SheetLocator::Name(name) => Ok(Some(name.as_ref().to_string())),
                SheetLocator::Id(id) => Ok(Some(self.graph.sheet_name(id).to_string())),
            }
        };

        let rt = match r {
            formualizer_common::SheetRef::Cell(cell) => ReferenceType::Cell {
                sheet: sheet_to_opt_name(cell.sheet.clone())?,
                row: cell.coord.row() + 1,
                col: cell.coord.col() + 1,
                row_abs: cell.coord.row_abs(),
                col_abs: cell.coord.col_abs(),
            },
            formualizer_common::SheetRef::Range(range) => ReferenceType::Range {
                sheet: sheet_to_opt_name(range.sheet.clone())?,
                start_row: range.start_row.map(|b| b.index + 1),
                start_col: range.start_col.map(|b| b.index + 1),
                end_row: range.end_row.map(|b| b.index + 1),
                end_col: range.end_col.map(|b| b.index + 1),
                start_row_abs: range.start_row.map(|b| b.abs).unwrap_or(false),
                start_col_abs: range.start_col.map(|b| b.abs).unwrap_or(false),
                end_row_abs: range.end_row.map(|b| b.abs).unwrap_or(false),
                end_col_abs: range.end_col.map(|b| b.abs).unwrap_or(false),
            },
        };

        crate::traits::EvaluationContext::resolve_range_view(self, &rt, current_sheet)
    }

    /// Set a cell formula
    pub fn set_cell_formula(
        &mut self,
        sheet: &str,
        row: u32,
        col: u32,
        ast: ASTNode,
    ) -> Result<(), ExcelError> {
        self.observe_function_semantic_epoch()?;
        let sheet_id = self.graph.sheet_id_mut(sheet);
        self.demote_span_containing_cell_for_write(
            sheet_id,
            row.saturating_sub(1),
            col.saturating_sub(1),
        )
        .map_err(Self::editor_error_to_excel)?;
        let placement = CellRef::new(sheet_id, Coord::from_excel(row, col, true, true));
        let ingested = {
            let mut pipeline = self.ingest_pipeline();
            pipeline.ingest_formula(FormulaAstInput::Tree(ast), placement, None)?
        };
        self.graph.set_cell_formula_with_plan(
            sheet,
            row,
            col,
            ingested.ast_id,
            &ingested.dep_plan,
            ingested.dep_plan.volatile,
            ingested.dep_plan.dynamic,
        )?;
        self.record_formula_plane_changed_cell(sheet, row, col);

        // If the cell previously held a user value in the delta overlay, it must not continue
        // to mask the formula result under Arrow-canonical reads (overlay precedence is
        // delta -> computed -> base). Remove the overlay entry instead of writing `Empty`,
        // because an explicit `Empty` overlay would still take precedence over computed values.
        self.clear_delta_overlay_cell(sheet, row, col);

        // Advance snapshot to reflect external mutation
        self.mark_topology_edited();
        Ok(())
    }

    /// Bulk set many formulas on a sheet. Skips per-cell snapshot bumping and minimizes edge rebuilds.
    pub fn bulk_set_formulas<I>(&mut self, sheet: &str, items: I) -> Result<usize, ExcelError>
    where
        I: IntoIterator<Item = (u32, u32, ASTNode)>,
    {
        let collected: Vec<(u32, u32, ASTNode)> = items.into_iter().collect();
        let edited_cells: Vec<(u32, u32)> = collected.iter().map(|(r, c, _)| (*r, *c)).collect();
        let sheet_id = self.graph.sheet_id_mut(sheet);
        let writes_inside_active_span = edited_cells.iter().any(|(row, col)| {
            let placement =
                PlacementCoord::new(sheet_id, row.saturating_sub(1), col.saturating_sub(1));
            self.graph
                .formula_authority()
                .plane
                .spans
                .find_at(placement)
                .is_some()
        });
        if writes_inside_active_span {
            self.demote_spans_preserving_computed_overlays(sheet_id, Region::whole_sheet(sheet_id))
                .map_err(Self::editor_error_to_excel)?;
        }
        let ingested = {
            let mut pipeline = self.ingest_pipeline();
            let inputs = collected.into_iter().map(|(row, col, ast)| {
                let placement = CellRef::new(sheet_id, Coord::from_excel(row, col, true, true));
                (FormulaAstInput::Tree(ast), placement, None)
            });
            pipeline.ingest_batch(inputs)?
        };
        let planned: Vec<(u32, u32, AstNodeId, DependencyPlanRow)> = ingested
            .into_iter()
            .map(|formula| {
                (
                    formula.placement.coord.row() + 1,
                    formula.placement.coord.col() + 1,
                    formula.ast_id,
                    formula.dep_plan,
                )
            })
            .collect();
        let n = self.graph.bulk_set_formulas_with_plans(sheet, planned)?;
        for (row, col) in edited_cells {
            self.record_formula_plane_changed_cell(sheet, row, col);
        }
        // Single topology bump after batch
        if n > 0 {
            self.mark_topology_edited();
        }
        Ok(n)
    }

    #[inline]
    fn normalize_public_cell_read(v: LiteralValue) -> Option<LiteralValue> {
        match v {
            LiteralValue::Empty => None,
            LiteralValue::Int(i) => Some(LiteralValue::Number(i as f64)),
            other => Some(other),
        }
    }

    /// Get a cell value
    pub fn get_cell_value(&self, sheet: &str, row: u32, col: u32) -> Option<LiteralValue> {
        self.read_cell_value(sheet, row, col)
            .and_then(Self::normalize_public_cell_read)
    }

    /// Unified internal read API for a single cell value (Arrow-truth).
    pub(crate) fn read_cell_value(&self, sheet: &str, row: u32, col: u32) -> Option<LiteralValue> {
        let asheet = self.sheet_store().sheet(sheet)?;
        let r0 = row.saturating_sub(1) as usize;
        let c0 = col.saturating_sub(1) as usize;
        let v = asheet.get_cell_value(r0, c0);
        if matches!(v, LiteralValue::Empty) {
            None
        } else {
            Some(v)
        }
    }

    /// Unified internal read API for a range of cell values (Arrow-truth).
    pub(crate) fn read_range_values(
        &self,
        sheet: &str,
        sr: u32,
        sc: u32,
        er: u32,
        ec: u32,
    ) -> RangeView<'_> {
        let Some(asheet) = self.sheet_store().sheet(sheet) else {
            return RangeView::from_owned_rows(Vec::new(), self.config.date_system);
        };
        if er < sr || ec < sc {
            return asheet.range_view(1, 1, 0, 0);
        }
        let sr0 = sr.saturating_sub(1) as usize;
        let sc0 = sc.saturating_sub(1) as usize;
        let er0 = er.saturating_sub(1) as usize;
        let ec0 = ec.saturating_sub(1) as usize;
        asheet.range_view(sr0, sc0, er0, ec0)
    }

    pub(crate) fn formula_plane_span_ast_at(
        &self,
        span_ref: FormulaSpanRef,
        placement: PlacementCoord,
    ) -> Option<ASTNode> {
        let authority = self.graph.formula_authority();
        let span = authority.plane.spans.get(span_ref)?;
        let relocation = span.ast_relocation;
        let mut ast = self
            .graph
            .data_store()
            .retrieve_ast(relocation.ast_id, self.graph.sheet_reg())?;
        if let Some(binding_set_id) = span.binding_set_id {
            let binding_set = authority.plane.binding_sets.get(binding_set_id)?;
            if !binding_set.is_single_literal_binding() {
                let binding =
                    binding_set.literal_bindings_for_placement(&span.domain, placement)?;
                ast = substitute_formula_plane_literal_slots(&ast, binding.as_ref());
            }
        }
        let row = placement.row.checked_add(1)?;
        let col = placement.col.checked_add(1)?;
        let row_delta = i64::from(row) - i64::from(relocation.anchor_row);
        let col_delta = i64::from(col) - i64::from(relocation.anchor_col);
        relocate_ast_for_template_placement(&ast, row_delta, col_delta).ok()
    }

    /// Get formula AST (if any) and current stored value for a cell
    pub fn get_cell(
        &self,
        sheet: &str,
        row: u32,
        col: u32,
    ) -> Option<(Option<formualizer_parse::ASTNode>, Option<LiteralValue>)> {
        let v = self.get_cell_value(sheet, row, col);
        let sheet_id = self.graph.sheet_id(sheet)?;
        let coord = Coord::from_excel(row, col, true, true);
        let cell = CellRef::new(sheet_id, coord);
        let placement =
            crate::formula_plane::runtime::PlacementCoord::new(sheet_id, coord.row(), coord.col());
        let handle = self
            .graph
            .formula_authority()
            .plane
            .resolve_formula_at(placement, None);
        match handle.resolution {
            crate::formula_plane::runtime::FormulaResolution::SpanPlacement { span, .. } => {
                // Span authority wins before graph lookup. Missing or invalid
                // relocation state is fail-closed: never expose a stale legacy
                // vertex for a coordinate owned by a span.
                let ast = self.formula_plane_span_ast_at(span, placement);
                return Some((ast, v));
            }
            crate::formula_plane::runtime::FormulaResolution::Overlay(overlay_ref) => {
                let ast = self
                    .graph
                    .formula_authority()
                    .plane
                    .formula_overlay
                    .get(overlay_ref)
                    .and_then(|overlay| match overlay.kind {
                        crate::formula_plane::runtime::FormulaOverlayEntryKind::FormulaOverride(
                            template_id,
                        ) => self
                            .graph
                            .formula_authority()
                            .plane
                            .templates
                            .get(template_id)
                            .and_then(|template| {
                                self.graph
                                    .data_store()
                                    .retrieve_ast(template.ast_id, self.graph.sheet_reg())
                            }),
                        _ => None,
                    });
                return Some((ast, v));
            }
            _ => {}
        }

        if let Some(vid) = self.graph.get_vertex_for_cell(&cell) {
            let ast = self.graph.get_formula_id(vid).and_then(|ast_id| {
                self.graph
                    .data_store()
                    .retrieve_ast(ast_id, self.graph.sheet_reg())
            });
            Some((ast, v))
        } else if v.is_some() {
            Some((None, v))
        } else {
            None
        }
    }

    /// Begin batch operations - defer CSR rebuilds for better performance
    pub fn begin_batch(&mut self) {
        self.graph.begin_batch();
    }

    /// End batch operations and trigger CSR rebuild
    pub fn end_batch(&mut self) {
        self.graph.end_batch();
    }

    /// Begin a deferred-dirty scope for a multi-edit batch: while active,
    /// every edit's dirty propagation queues its sources instead of running
    /// a full BFS per edit, and the outermost `end_deferred_dirty` flushes
    /// the union with ONE multi-source propagation (O(component) instead of
    /// O(edits × component)). See `DependencyGraph::begin_deferred_dirty`.
    ///
    /// Callers MUST run `end_deferred_dirty` on every exit path, including
    /// error returns; evaluation entry points `debug_assert` no scope leaked.
    pub fn begin_deferred_dirty(&mut self) {
        self.graph.begin_deferred_dirty();
    }

    /// End a deferred-dirty scope, flushing the queued propagation when the
    /// outermost scope closes. See `Engine::begin_deferred_dirty`.
    pub fn end_deferred_dirty(&mut self) {
        let _ = self.graph.end_deferred_dirty();
    }

    /// Total vertices processed by dirty-propagation BFS loops since graph
    /// creation. Perf-shape observability only (cross-crate tests assert
    /// batched edits propagate O(component), not O(edits × component)).
    pub fn dirty_propagation_visits(&self) -> u64 {
        self.graph.dirty_propagation_visits()
    }

    /// Evaluate a single vertex.
    /// This is the core of the sequential evaluation logic for Milestone 3.1.
    #[inline]
    fn record_cell_if_changed(
        delta: &mut DeltaCollector,
        cell: &CellRef,
        old: &LiteralValue,
        new: &LiteralValue,
    ) {
        if old != new {
            delta.record_cell(cell.sheet_id, cell.coord.row(), cell.coord.col());
        }
    }

    pub fn evaluate_vertex(&mut self, vertex_id: VertexId) -> Result<LiteralValue, ExcelError> {
        self.observe_evaluation_resource_request(EvaluationRequestKind::Vertex, |engine| {
            engine.observe_function_semantic_epoch()?;
            // A direct request selects exactly one vertex, regardless of its formula kind.
            engine.resource_checkpoint(1)?;
            let is_formula = engine.graph.vertex_exists(vertex_id)
                && matches!(
                    engine.graph.get_vertex_kind(vertex_id),
                    VertexKind::FormulaScalar | VertexKind::FormulaArray
                );
            if is_formula {
                engine.begin_evaluation_request();
                engine.graph.flush_pending_edge_deltas();
                let roots = [crate::engine::target_preparation::TargetProducer::Legacy(
                    vertex_id,
                )];
                if engine.config.formula_plane_mode == FormulaPlaneMode::AuthoritativeExperimental
                    && engine.graph.formula_authority().active_span_count() > 0
                {
                    engine.evaluate_authoritative_formula_plane_targets(&roots, None)?;
                } else {
                    engine.evaluate_legacy_target_roots(&roots, None)?;
                }
            } else if engine.config.formula_plane_mode
                == FormulaPlaneMode::AuthoritativeExperimental
                && engine.graph.formula_authority().active_span_count() > 0
            {
                engine.begin_evaluation_request();
                engine.graph.flush_pending_edge_deltas();
                engine.evaluate_authoritative_formula_plane(None, None)?;
            }
            engine.evaluate_vertex_impl(vertex_id, None)
        })
    }

    fn evaluate_vertex_impl(
        &mut self,
        vertex_id: VertexId,
        delta: Option<&mut DeltaCollector>,
    ) -> Result<LiteralValue, ExcelError> {
        // Preserve the direct evaluator's compatibility behavior for invalid IDs, literal cells,
        // names, and other non-formula vertices. Only formula publication needs the C1a final
        // deadline checkpoint and effects pipeline.
        if !self.graph.vertex_exists(vertex_id) {
            return Err(ExcelError::new(formualizer_common::ExcelErrorKind::Ref)
                .with_message(format!("Vertex not found: {vertex_id:?}")));
        }
        if self.active_resource_ledger.is_some()
            && matches!(
                self.graph.get_vertex_kind(vertex_id),
                VertexKind::FormulaScalar | VertexKind::FormulaArray
            )
        {
            let value = self
                .evaluate_vertex_immutable(vertex_id)
                .unwrap_or_else(LiteralValue::Error);
            let effects = self.plan_vertex_effects(vertex_id, value.clone(), None)?;
            // Do not publish the selected result until the outer request's deadline succeeds.
            self.resource_checkpoint(0)?;
            let mut delta = delta;
            for effect in &effects {
                self.apply_effect_with_computed_writes(effect, delta.as_deref_mut(), None, None)?;
            }
            return Ok(value);
        }

        let mut delta = delta;

        // Get vertex kind and check if it needs evaluation
        let kind = self.graph.get_vertex_kind(vertex_id);
        let sheet_id = self.graph.get_vertex_sheet_id(vertex_id);

        let ast_id = match kind {
            VertexKind::FormulaScalar | VertexKind::FormulaArray => {
                if let Some(ast_id) = self.graph.get_formula_id(vertex_id) {
                    ast_id
                } else {
                    return Ok(LiteralValue::Number(0.0));
                }
            }
            VertexKind::Empty | VertexKind::Cell => {
                if let Some(cell_ref) = self.graph.get_cell_ref(vertex_id) {
                    let sheet_name = self.graph.sheet_name(cell_ref.sheet_id);
                    let row = cell_ref.coord.row() + 1;
                    let col = cell_ref.coord.col() + 1;
                    if let Some(v) = self.read_cell_value(sheet_name, row, col) {
                        return Ok(v);
                    }
                }
                return Ok(LiteralValue::Number(0.0));
            }
            VertexKind::NamedScalar => {
                let value = self.evaluate_named_scalar(vertex_id, sheet_id)?;
                return Ok(value);
            }
            VertexKind::NamedArray => {
                let value = self.evaluate_named_array(vertex_id, sheet_id)?;
                return Ok(value);
            }
            VertexKind::InfiniteRange
            | VertexKind::Range
            | VertexKind::External
            | VertexKind::Table => {
                // Not directly evaluatable here.
                return Ok(LiteralValue::Number(0.0));
            }
        };

        // The interpreter uses a reference to the engine as the context.
        let sheet_name = self.graph.sheet_name(sheet_id);
        let cell_ref = self
            .graph
            .get_cell_ref(vertex_id)
            .expect("cell ref for vertex");
        let interpreter = Interpreter::new_with_cell(self, sheet_name, cell_ref);

        let result =
            interpreter.evaluate_arena_ast(ast_id, self.graph.data_store(), self.graph.sheet_reg());

        // If array result, perform spill from the anchor cell
        match result {
            Ok(cv) => {
                let result_literal =
                    crate::engine::result_finalization::finalize_formula_result(cv.into_literal());
                match result_literal {
                    LiteralValue::Array(rows) => {
                        // Update kind to FormulaArray for tracking
                        self.graph
                            .set_kind(vertex_id, crate::engine::vertex::VertexKind::FormulaArray);
                        // Build target cells rectangle starting from anchor
                        let anchor = self
                            .graph
                            .get_cell_ref(vertex_id)
                            .expect("cell ref for vertex");
                        let sheet_id = anchor.sheet_id;
                        let h = rows.len() as u32;
                        let w = rows.first().map(|r| r.len()).unwrap_or(0) as u32;

                        // Hard cap to avoid vertex explosion from huge dynamic arrays.
                        let spill_cells = (h as u64).saturating_mul(w as u64);
                        if spill_cells > self.config.spill.max_spill_cells as u64 {
                            self.clear_spill_projection_and_mirror(vertex_id, delta.as_deref_mut());
                            let spill_err = ExcelError::new(ExcelErrorKind::Spill)
                                .with_message("SpillTooLarge")
                                .with_extra(formualizer_common::ExcelErrorExtra::Spill {
                                    expected_rows: h,
                                    expected_cols: w,
                                });
                            let spill_val = LiteralValue::Error(spill_err.clone());
                            if let Some(d) = delta.as_deref_mut() {
                                let old = self
                                    .read_cell_value(
                                        self.graph.sheet_name(anchor.sheet_id),
                                        anchor.coord.row() + 1,
                                        anchor.coord.col() + 1,
                                    )
                                    .unwrap_or(LiteralValue::Empty);
                                if old != spill_val {
                                    d.record_cell(
                                        anchor.sheet_id,
                                        anchor.coord.row(),
                                        anchor.coord.col(),
                                    );
                                }
                            }
                            self.graph.update_vertex_value(vertex_id, spill_val.clone());
                            if self.config.arrow_storage_enabled
                                && self.config.delta_overlay_enabled
                                && self.config.write_formula_overlay_enabled
                            {
                                let sheet_name = self.graph.sheet_name(anchor.sheet_id).to_string();
                                self.mirror_value_to_computed_overlay(
                                    &sheet_name,
                                    anchor.coord.row() + 1,
                                    anchor.coord.col() + 1,
                                    &spill_val,
                                );
                            }
                            return Ok(spill_val);
                        }
                        // Bounds check to avoid out-of-range writes (align to AbsCoord capacity)
                        const PACKED_MAX_ROW: u32 = 1_048_575; // 20-bit max
                        const PACKED_MAX_COL: u32 = 16_383; // 14-bit max
                        let end_row = anchor.coord.row().saturating_add(h).saturating_sub(1);
                        let end_col = anchor.coord.col().saturating_add(w).saturating_sub(1);
                        if end_row > PACKED_MAX_ROW || end_col > PACKED_MAX_COL {
                            self.clear_spill_projection_and_mirror(vertex_id, delta.as_deref_mut());
                            let spill_err = ExcelError::new(ExcelErrorKind::Spill)
                                .with_message("Spill exceeds sheet bounds")
                                .with_extra(formualizer_common::ExcelErrorExtra::Spill {
                                    expected_rows: h,
                                    expected_cols: w,
                                });
                            let spill_val = LiteralValue::Error(spill_err.clone());
                            if let Some(d) = delta.as_deref_mut() {
                                let old = self
                                    .read_cell_value(
                                        self.graph.sheet_name(anchor.sheet_id),
                                        anchor.coord.row() + 1,
                                        anchor.coord.col() + 1,
                                    )
                                    .unwrap_or(LiteralValue::Empty);
                                if old != spill_val {
                                    d.record_cell(
                                        anchor.sheet_id,
                                        anchor.coord.row(),
                                        anchor.coord.col(),
                                    );
                                }
                            }
                            self.graph.update_vertex_value(vertex_id, spill_val.clone());
                            if self.config.arrow_storage_enabled
                                && self.config.delta_overlay_enabled
                                && self.config.write_formula_overlay_enabled
                            {
                                let sheet_name = self.graph.sheet_name(anchor.sheet_id).to_string();
                                self.mirror_value_to_computed_overlay(
                                    &sheet_name,
                                    anchor.coord.row() + 1,
                                    anchor.coord.col() + 1,
                                    &spill_val,
                                );
                            }
                            return Ok(spill_val);
                        }
                        let mut targets = Vec::new();
                        for r in 0..h {
                            for c in 0..w {
                                targets.push(self.graph.make_cell_ref_internal(
                                    sheet_id,
                                    anchor.coord.row() + r,
                                    anchor.coord.col() + c,
                                ));
                            }
                        }

                        // Plan spill via spill manager shim
                        match self.spill_mgr.reserve(
                            vertex_id,
                            anchor,
                            SpillShape { rows: h, cols: w },
                            SpillMeta {
                                epoch: self.recalc_epoch,
                                config: self.config.spill,
                            },
                        ) {
                            Ok(()) => {
                                // Commit: write values to grid
                                // Default conflict policy is Error + FirstWins; reserve() enforces in-flight locks
                                // and plan_spill_region enforces overlap with committed formulas/spills/values.
                                if let Err(e) = self.commit_spill_and_mirror(
                                    vertex_id,
                                    &targets,
                                    rows.clone(),
                                    delta.as_deref_mut(),
                                    None,
                                ) {
                                    // If commit fails, mark as error
                                    self.clear_spill_projection_and_mirror(
                                        vertex_id,
                                        delta.as_deref_mut(),
                                    );
                                    if let Some(d) = delta.as_deref_mut() {
                                        let old = self
                                            .read_cell_value(
                                                self.graph.sheet_name(anchor.sheet_id),
                                                anchor.coord.row() + 1,
                                                anchor.coord.col() + 1,
                                            )
                                            .unwrap_or(LiteralValue::Empty);
                                        let new = LiteralValue::Error(e.clone());
                                        if old != new {
                                            d.record_cell(
                                                anchor.sheet_id,
                                                anchor.coord.row(),
                                                anchor.coord.col(),
                                            );
                                        }
                                    }
                                    let err_val = LiteralValue::Error(e.clone());
                                    self.graph.update_vertex_value(vertex_id, err_val.clone());
                                    if self.config.arrow_storage_enabled
                                        && self.config.delta_overlay_enabled
                                        && self.config.write_formula_overlay_enabled
                                    {
                                        let sheet_name =
                                            self.graph.sheet_name(anchor.sheet_id).to_string();
                                        self.mirror_value_to_computed_overlay(
                                            &sheet_name,
                                            anchor.coord.row() + 1,
                                            anchor.coord.col() + 1,
                                            &err_val,
                                        );
                                    }
                                    return Ok(err_val);
                                }
                                // Anchor shows the top-left value, like Excel
                                let top_left = rows
                                    .first()
                                    .and_then(|r| r.first())
                                    .cloned()
                                    .unwrap_or(LiteralValue::Empty);
                                self.graph.update_vertex_value(vertex_id, top_left.clone());
                                Ok(top_left)
                            }
                            Err(e) => {
                                self.clear_spill_projection_and_mirror(
                                    vertex_id,
                                    delta.as_deref_mut(),
                                );
                                let spill_err = ExcelError::new(ExcelErrorKind::Spill)
                                    .with_message(
                                        e.message.unwrap_or_else(|| "Spill blocked".to_string()),
                                    )
                                    .with_extra(formualizer_common::ExcelErrorExtra::Spill {
                                        expected_rows: h,
                                        expected_cols: w,
                                    });
                                let spill_val = LiteralValue::Error(spill_err.clone());
                                if let Some(d) = delta.as_deref_mut() {
                                    let old = self
                                        .read_cell_value(
                                            self.graph.sheet_name(anchor.sheet_id),
                                            anchor.coord.row() + 1,
                                            anchor.coord.col() + 1,
                                        )
                                        .unwrap_or(LiteralValue::Empty);
                                    if old != spill_val {
                                        d.record_cell(
                                            anchor.sheet_id,
                                            anchor.coord.row(),
                                            anchor.coord.col(),
                                        );
                                    }
                                }
                                self.graph.update_vertex_value(vertex_id, spill_val.clone());
                                if self.config.arrow_storage_enabled
                                    && self.config.delta_overlay_enabled
                                    && self.config.write_formula_overlay_enabled
                                {
                                    let sheet_name =
                                        self.graph.sheet_name(anchor.sheet_id).to_string();
                                    self.mirror_value_to_computed_overlay(
                                        &sheet_name,
                                        anchor.coord.row() + 1,
                                        anchor.coord.col() + 1,
                                        &spill_val,
                                    );
                                }
                                Ok(spill_val)
                            }
                        }
                    }
                    other => {
                        // Scalar result: store value and ensure any previous spill is cleared
                        let spill_cells = self
                            .graph
                            .spill_cells_for_anchor(vertex_id)
                            .map(|cells| cells.to_vec())
                            .unwrap_or_default();
                        if let Some(d) = delta.as_deref_mut()
                            && let Some(anchor) = self.graph.get_cell_ref_for_vertex(vertex_id)
                        {
                            if spill_cells.is_empty() {
                                let old = self
                                    .read_cell_value(
                                        self.graph.sheet_name(anchor.sheet_id),
                                        anchor.coord.row() + 1,
                                        anchor.coord.col() + 1,
                                    )
                                    .unwrap_or(LiteralValue::Empty);
                                if old != other {
                                    d.record_cell(
                                        anchor.sheet_id,
                                        anchor.coord.row(),
                                        anchor.coord.col(),
                                    );
                                }
                            } else {
                                for cell in spill_cells.iter() {
                                    let sheet_name = self.graph.sheet_name(cell.sheet_id);
                                    let old = self
                                        .get_cell_value(
                                            sheet_name,
                                            cell.coord.row() + 1,
                                            cell.coord.col() + 1,
                                        )
                                        .unwrap_or(LiteralValue::Empty);
                                    let new = if cell.sheet_id == anchor.sheet_id
                                        && cell.coord.row() == anchor.coord.row()
                                        && cell.coord.col() == anchor.coord.col()
                                    {
                                        other.clone()
                                    } else {
                                        LiteralValue::Empty
                                    };
                                    Self::record_cell_if_changed(d, cell, &old, &new);
                                }
                            }
                        }
                        self.graph.clear_spill_region(vertex_id);
                        if let Some(scope) = Self::formula_plane_region_from_cells(&spill_cells) {
                            self.record_formula_plane_structural_change(scope);
                        }
                        if self.config.arrow_storage_enabled
                            && self.config.delta_overlay_enabled
                            && self.config.write_formula_overlay_enabled
                        {
                            let empty = LiteralValue::Empty;
                            for cell in spill_cells.iter() {
                                let sheet_name = self.graph.sheet_name(cell.sheet_id).to_string();
                                self.mirror_value_to_computed_overlay(
                                    &sheet_name,
                                    cell.coord.row() + 1,
                                    cell.coord.col() + 1,
                                    &empty,
                                );
                            }
                        }
                        self.graph.update_vertex_value(vertex_id, other.clone());
                        // Optionally mirror into Arrow overlay for Arrow-backed reads
                        if self.config.arrow_storage_enabled
                            && self.config.delta_overlay_enabled
                            && self.config.write_formula_overlay_enabled
                        {
                            let anchor = self
                                .graph
                                .get_cell_ref(vertex_id)
                                .expect("cell ref for vertex");
                            let sheet_name = self.graph.sheet_name(anchor.sheet_id).to_string();
                            self.mirror_value_to_computed_overlay(
                                &sheet_name,
                                anchor.coord.row() + 1,
                                anchor.coord.col() + 1,
                                &other,
                            );
                        }
                        Ok(other)
                    }
                }
            }
            Err(e) => {
                // Runtime Excel error: store as a cell value instead of propagating
                // as an exception so bulk eval paths don't fail the whole pass.
                let spill_cells = self
                    .graph
                    .spill_cells_for_anchor(vertex_id)
                    .map(|cells| cells.to_vec())
                    .unwrap_or_default();
                let err_val = LiteralValue::Error(e.clone());
                if let Some(d) = delta
                    && let Some(anchor) = self.graph.get_cell_ref_for_vertex(vertex_id)
                {
                    if spill_cells.is_empty() {
                        let old = self
                            .read_cell_value(
                                self.graph.sheet_name(anchor.sheet_id),
                                anchor.coord.row() + 1,
                                anchor.coord.col() + 1,
                            )
                            .unwrap_or(LiteralValue::Empty);
                        if old != err_val {
                            d.record_cell(anchor.sheet_id, anchor.coord.row(), anchor.coord.col());
                        }
                    } else {
                        for cell in spill_cells.iter() {
                            let sheet_name = self.graph.sheet_name(cell.sheet_id);
                            let old = self
                                .get_cell_value(
                                    sheet_name,
                                    cell.coord.row() + 1,
                                    cell.coord.col() + 1,
                                )
                                .unwrap_or(LiteralValue::Empty);
                            let new = if cell.sheet_id == anchor.sheet_id
                                && cell.coord.row() == anchor.coord.row()
                                && cell.coord.col() == anchor.coord.col()
                            {
                                err_val.clone()
                            } else {
                                LiteralValue::Empty
                            };
                            Self::record_cell_if_changed(d, cell, &old, &new);
                        }
                    }
                }
                self.graph.clear_spill_region(vertex_id);
                if let Some(scope) = Self::formula_plane_region_from_cells(&spill_cells) {
                    self.record_formula_plane_structural_change(scope);
                }
                if self.config.arrow_storage_enabled
                    && self.config.delta_overlay_enabled
                    && self.config.write_formula_overlay_enabled
                {
                    let empty = LiteralValue::Empty;
                    for cell in spill_cells.iter() {
                        let sheet_name = self.graph.sheet_name(cell.sheet_id).to_string();
                        self.mirror_value_to_computed_overlay(
                            &sheet_name,
                            cell.coord.row() + 1,
                            cell.coord.col() + 1,
                            &empty,
                        );
                    }
                }
                self.graph.update_vertex_value(vertex_id, err_val.clone());
                if self.config.arrow_storage_enabled
                    && self.config.delta_overlay_enabled
                    && self.config.write_formula_overlay_enabled
                {
                    let anchor = self
                        .graph
                        .get_cell_ref(vertex_id)
                        .expect("cell ref for vertex");
                    let sheet_name = self.graph.sheet_name(anchor.sheet_id).to_string();
                    self.mirror_value_to_computed_overlay(
                        &sheet_name,
                        anchor.coord.row() + 1,
                        anchor.coord.col() + 1,
                        &err_val,
                    );
                }
                Ok(err_val)
            }
        }
    }

    fn evaluate_named_scalar(
        &mut self,
        vertex_id: VertexId,
        sheet_id: SheetId,
    ) -> Result<LiteralValue, ExcelError> {
        let named_range = self.graph.named_range_by_vertex(vertex_id).ok_or_else(|| {
            ExcelError::new(ExcelErrorKind::Name)
                .with_message("Named range metadata missing".to_string())
        })?;

        match &named_range.definition {
            NamedDefinition::Cell(cell_ref) => {
                let sheet_name = self.graph.sheet_name(cell_ref.sheet_id);
                let row = cell_ref.coord.row() + 1;
                let col = cell_ref.coord.col() + 1;

                if let Some(dep_vertex) = self.graph.get_vertex_for_cell(cell_ref)
                    && matches!(
                        self.graph.get_vertex_kind(dep_vertex),
                        VertexKind::FormulaScalar | VertexKind::FormulaArray
                    )
                {
                    // Graph does not cache cell/formula values; ensure the precedent is evaluated.
                    let value = self.evaluate_vertex(dep_vertex)?;
                    self.graph.update_vertex_value(vertex_id, value.clone());
                    Ok(value)
                } else {
                    let value = self
                        .get_cell_value(sheet_name, row, col)
                        .unwrap_or(LiteralValue::Empty);
                    self.graph.update_vertex_value(vertex_id, value.clone());
                    Ok(value)
                }
            }
            NamedDefinition::Literal(v) => {
                let out = v.clone();
                self.graph.update_vertex_value(vertex_id, out.clone());
                Ok(out)
            }
            NamedDefinition::Formula { ast, .. } => {
                let context_sheet = match named_range.scope {
                    NameScope::Sheet(id) => id,
                    NameScope::Workbook => sheet_id,
                };
                let sheet_name = self.graph.sheet_name(context_sheet);
                let cell_ref = self
                    .graph
                    .get_cell_ref(vertex_id)
                    .unwrap_or_else(|| self.graph.make_cell_ref(sheet_name, 0, 0));
                let interpreter = Interpreter::new_with_cell(self, sheet_name, cell_ref);
                match interpreter.evaluate_ast(ast) {
                    Ok(cv) => {
                        let value = cv.into_literal();
                        match value {
                            LiteralValue::Array(_) => {
                                let err = ExcelError::new(ExcelErrorKind::NImpl)
                                    .with_message("Array result in scalar named range".to_string());
                                let err_val = LiteralValue::Error(err.clone());
                                self.graph.update_vertex_value(vertex_id, err_val.clone());
                                Ok(err_val)
                            }
                            other => {
                                self.graph.update_vertex_value(vertex_id, other.clone());
                                Ok(other)
                            }
                        }
                    }
                    Err(err) => {
                        let err_val = LiteralValue::Error(err.clone());
                        self.graph.update_vertex_value(vertex_id, err_val.clone());
                        Ok(err_val)
                    }
                }
            }
            NamedDefinition::Range(_) => Err(ExcelError::new(ExcelErrorKind::Value)
                .with_message("Range-valued name evaluated as scalar".to_string())),
        }
    }

    fn evaluate_named_array(
        &mut self,
        vertex_id: VertexId,
        sheet_id: SheetId,
    ) -> Result<LiteralValue, ExcelError> {
        let named_range = self.graph.named_range_by_vertex(vertex_id).ok_or_else(|| {
            ExcelError::new(ExcelErrorKind::Name)
                .with_message("Named range metadata missing".to_string())
        })?;

        let out = match &named_range.definition {
            NamedDefinition::Range(range_ref) => {
                if range_ref.start.sheet_id != range_ref.end.sheet_id {
                    return Err(ExcelError::new(ExcelErrorKind::Ref)
                        .with_message("Named range cannot span sheets".to_string()));
                }

                let sheet_name = self.graph.sheet_name(range_ref.start.sheet_id);
                let sr0 = range_ref.start.coord.row();
                let sc0 = range_ref.start.coord.col();
                let er0 = range_ref.end.coord.row();
                let ec0 = range_ref.end.coord.col();
                if sr0 > er0 || sc0 > ec0 {
                    return Err(ExcelError::new(ExcelErrorKind::Ref)
                        .with_message("Invalid named range bounds".to_string()));
                }

                let h = (er0 - sr0 + 1) as usize;
                let w = (ec0 - sc0 + 1) as usize;
                let cell_count = (h as u64).saturating_mul(w as u64);
                if cell_count > self.config.spill.max_spill_cells as u64 {
                    return Err(ExcelError::new(ExcelErrorKind::NImpl).with_message(
                        "Named range too large to materialize as an array".to_string(),
                    ));
                }

                let mut rows = Vec::with_capacity(h);
                for r0 in sr0..=er0 {
                    let mut row = Vec::with_capacity(w);
                    for c0 in sc0..=ec0 {
                        let v = self
                            .get_cell_value(sheet_name, r0 + 1, c0 + 1)
                            .unwrap_or(LiteralValue::Empty);
                        row.push(v);
                    }
                    rows.push(row);
                }
                LiteralValue::Array(rows)
            }
            NamedDefinition::Cell(cell_ref) => {
                let sheet_name = self.graph.sheet_name(cell_ref.sheet_id);
                let row = cell_ref.coord.row() + 1;
                let col = cell_ref.coord.col() + 1;
                let v = self
                    .get_cell_value(sheet_name, row, col)
                    .unwrap_or(LiteralValue::Empty);
                LiteralValue::Array(vec![vec![v]])
            }
            NamedDefinition::Literal(v) => LiteralValue::Array(vec![vec![v.clone()]]),
            NamedDefinition::Formula { ast, .. } => {
                let context_sheet = match named_range.scope {
                    NameScope::Sheet(id) => id,
                    NameScope::Workbook => sheet_id,
                };
                let sheet_name = self.graph.sheet_name(context_sheet);
                let cell_ref = self
                    .graph
                    .get_cell_ref(vertex_id)
                    .unwrap_or_else(|| self.graph.make_cell_ref(sheet_name, 0, 0));
                let interpreter = Interpreter::new_with_cell(self, sheet_name, cell_ref);
                match interpreter.evaluate_ast(ast) {
                    Ok(cv) => {
                        let v = cv.into_literal();
                        match v {
                            LiteralValue::Array(_) => v,
                            other => LiteralValue::Array(vec![vec![other]]),
                        }
                    }
                    Err(err) => LiteralValue::Error(err),
                }
            }
        };

        self.graph.update_vertex_value(vertex_id, out.clone());
        Ok(out)
    }

    fn replan_exhausted_error(&self, limit: usize, context: &str) -> ExcelError {
        crate::engine::ResourceLedgerError::Exhausted(
            formualizer_common::ResourceExhaustionDetail {
                reason: formualizer_common::ResourceExhaustionReason::WorkUnits,
                limit: limit as u64,
                observed: limit.saturating_add(1) as u64,
                request_id: self
                    .active_evaluation_resource_request
                    .as_ref()
                    .map(|stats| stats.request_id),
            },
        )
        .into_excel_error()
        .with_message(format!("{context} did not converge after {limit} replans"))
    }

    fn transient_target_preparation_stale(error: &ExcelError) -> bool {
        matches!(
            &error.extra,
            formualizer_common::ExcelErrorExtra::PreparationStale {
                reason: formualizer_common::PreparationStaleReason::Semantic
                    | formualizer_common::PreparationStaleReason::Provider
            }
        )
    }

    fn prepare_graph_for_routed_evaluation(
        &mut self,
        targets: &[crate::engine::EvaluationTarget],
        options: &crate::engine::TargetEvalOptions<'_>,
    ) -> Result<crate::engine::PreparedTargetGraphReport, ExcelError> {
        const MAX_TRANSIENT_PREPARATION_RETRIES: usize = 2;
        let mut retries = 0usize;
        loop {
            match self.prepare_graph_for_targets_unobserved(targets, options) {
                Err(error)
                    if Self::transient_target_preparation_stale(&error)
                        && retries < MAX_TRANSIENT_PREPARATION_RETRIES =>
                {
                    retries = retries.saturating_add(1);
                }
                result => return result,
            }
        }
    }

    fn evaluate_mixed_targets(
        &mut self,
        targets: &[crate::engine::EvaluationTarget],
        delta: Option<&mut DeltaCollector>,
    ) -> Result<EvalResult, ExcelError> {
        let _source_cache = self.source_cache_session();
        let cancel = self.active_cancel_flag.clone();
        let options = crate::engine::TargetEvalOptions {
            request_id: self
                .active_evaluation_resource_request
                .as_ref()
                .map(|stats| stats.request_id),
            cancel,
            deadline: None,
            budgets: None,
            opaque_policy: crate::engine::OpaquePreparePolicy::Widen,
        };
        self.prepare_and_execute_target_recipe(targets, &options, delta)
    }

    fn prepare_and_execute_target_recipe(
        &mut self,
        targets: &[crate::engine::EvaluationTarget],
        options: &crate::engine::TargetEvalOptions<'_>,
        delta: Option<&mut DeltaCollector>,
    ) -> Result<EvalResult, ExcelError> {
        let preparation = self.prepare_graph_for_routed_evaluation(targets, options)?;
        self.execute_prepared_target_recipe(targets, &preparation.widened_scope, delta)
    }

    fn execute_prepared_target_recipe(
        &mut self,
        targets: &[crate::engine::EvaluationTarget],
        scope: &crate::engine::PrepareScope,
        delta: Option<&mut DeltaCollector>,
    ) -> Result<EvalResult, ExcelError> {
        if matches!(scope, crate::engine::PrepareScope::Workbook)
            && let Some(stats) = self.active_evaluation_resource_request.as_mut()
        {
            stats.workbook_exact_attempts = stats.workbook_exact_attempts.max(1);
        }
        let mut roots = self.resolve_target_producers(targets)?;
        if let crate::engine::PrepareScope::Sheets(sheets) = scope {
            let request_id = self
                .active_evaluation_resource_request
                .as_ref()
                .map(|request| request.request_id);
            let root_count = roots.len();
            let mut widened_roots =
                OrderedTargetProducers::from_ordered(std::mem::take(&mut roots))
                    .map_err(|_| target_root_allocation_error(root_count, request_id))?;
            let sheet_ids = sheets
                .iter()
                .filter_map(|sheet| self.graph.sheet_id(sheet))
                .collect::<FxHashSet<_>>();
            for vertex in self.graph.formula_vertices() {
                if sheet_ids.contains(&self.graph.get_vertex_sheet_id(vertex)) {
                    widened_roots
                        .push(crate::engine::target_preparation::TargetProducer::Legacy(
                            vertex,
                        ))
                        .map_err(|_| {
                            target_root_allocation_error(widened_roots.len() + 1, request_id)
                        })?;
                }
            }
            let authority = self.graph.formula_authority();
            for span_ref in authority.active_span_refs() {
                let Some(span) = authority.plane.spans.get(span_ref) else {
                    continue;
                };
                if sheet_ids.contains(&span.sheet_id) {
                    widened_roots
                        .push(crate::engine::target_preparation::TargetProducer::Span {
                            span_ref,
                            demanded: Region::from_domain(span.result_region.domain()),
                        })
                        .map_err(|_| {
                            target_root_allocation_error(widened_roots.len() + 1, request_id)
                        })?;
                }
            }
            roots = widened_roots.into_vec();
        }
        self.begin_evaluation_request();
        self.graph.flush_pending_edge_deltas();
        let workbook_scope = matches!(scope, crate::engine::PrepareScope::Workbook);
        if self.config.formula_plane_mode == FormulaPlaneMode::AuthoritativeExperimental
            && self.graph.formula_authority().active_span_count() > 0
        {
            if workbook_scope {
                self.evaluate_authoritative_formula_plane(None, delta)
            } else {
                self.evaluate_authoritative_formula_plane_targets(&roots, delta)
            }
        } else {
            if self.config.formula_plane_mode == FormulaPlaneMode::AuthoritativeExperimental {
                self.observe_topology_strategy(FormulaPlaneTopologyStrategy::SkippedNoActiveSpans);
            }
            if workbook_scope {
                if let Some(delta) = delta {
                    self.evaluate_all_with_delta_collector(delta)
                } else {
                    self.evaluate_all_legacy_impl()
                }
            } else {
                self.evaluate_legacy_target_roots(&roots, delta)
            }
        }
    }

    fn legacy_coordinate_targets(
        &mut self,
        targets: &[(&str, u32, u32)],
    ) -> Vec<crate::engine::EvaluationTarget> {
        targets
            .iter()
            .map(|(sheet, row, col)| {
                // Compatibility APIs historically interned an unknown target sheet
                // and returned an empty value rather than rejecting the target.
                self.graph.sheet_id_mut(sheet);
                crate::engine::EvaluationTarget::Cell {
                    sheet: (*sheet).to_string(),
                    row: *row,
                    col: *col,
                }
            })
            .collect()
    }

    /// Evaluate the necessary mixed producer closure for typed cell, range, name, and table targets.
    pub fn evaluate_targets(
        &mut self,
        targets: &[crate::engine::EvaluationTarget],
    ) -> Result<EvalResult, ExcelError> {
        self.observe_evaluation_resource_request(EvaluationRequestKind::Targeted, |engine| {
            engine.observe_function_semantic_epoch()?;
            engine.validate_deterministic_mode()?;
            engine.evaluate_mixed_targets(targets, None)
        })
    }

    /// Evaluate typed targets with explicit preparation policy and request controls.
    pub fn evaluate_targets_with_options(
        &mut self,
        targets: &[crate::engine::EvaluationTarget],
        options: crate::engine::TargetEvalOptions<'_>,
    ) -> Result<EvalResult, ExcelError> {
        self.observe_evaluation_resource_request(EvaluationRequestKind::Targeted, |engine| {
            engine.active_cancel_flag = options.cancel.clone();
            engine.active_evaluation_deadline = options.deadline;
            let result = (|| {
                engine.cancellation_checkpoint("Evaluation cancelled before target preparation")?;
                engine.observe_function_semantic_epoch()?;
                engine.validate_deterministic_mode()?;
                let _source_cache = engine.source_cache_session();
                engine.prepare_and_execute_target_recipe(targets, &options, None)
            })();
            engine.active_cancel_flag = None;
            engine.active_evaluation_deadline = None;
            result
        })
    }

    /// Evaluate typed targets and return the versioned run/region delta for the request.
    pub fn evaluate_targets_with_delta(
        &mut self,
        targets: &[crate::engine::EvaluationTarget],
    ) -> Result<(EvalResult, crate::engine::TargetEvalDelta), ExcelError> {
        self.observe_evaluation_resource_request(EvaluationRequestKind::CellsWithDelta, |engine| {
            engine.observe_function_semantic_epoch()?;
            engine.validate_deterministic_mode()?;
            let mut collector = DeltaCollector::new(DeltaMode::Cells);
            let result = engine.evaluate_mixed_targets(targets, Some(&mut collector))?;
            Ok((result, collector.finish_target()))
        })
    }

    /// Evaluate only the necessary precedents for specific target cells (demand-driven)
    pub fn evaluate_until(
        &mut self,
        targets: &[(&str, u32, u32)],
    ) -> Result<EvalResult, ExcelError> {
        self.observe_evaluation_resource_request(EvaluationRequestKind::Targeted, |engine| {
            engine.evaluate_until_unobserved(targets)
        })
    }

    fn evaluate_until_unobserved(
        &mut self,
        targets: &[(&str, u32, u32)],
    ) -> Result<EvalResult, ExcelError> {
        self.observe_function_semantic_epoch()?;
        let targets = self.legacy_coordinate_targets(targets);
        self.evaluate_mixed_targets(&targets, None)
    }

    fn evaluate_until_with_delta_collector(
        &mut self,
        targets: &[(&str, u32, u32)],
        delta: &mut DeltaCollector,
    ) -> Result<EvalResult, ExcelError> {
        let targets = self.legacy_coordinate_targets(targets);
        self.evaluate_mixed_targets(&targets, Some(delta))
    }

    fn evaluate_legacy_target_roots(
        &mut self,
        roots: &[crate::engine::target_preparation::TargetProducer],
        mut delta: Option<&mut DeltaCollector>,
    ) -> Result<EvalResult, ExcelError> {
        use crate::engine::target_preparation::TargetProducer;
        let start = crate::instant::FzInstant::now();
        let root_vertices = roots
            .iter()
            .filter_map(|root| match root {
                TargetProducer::Legacy(vertex) | TargetProducer::Symbol(vertex) => Some(*vertex),
                TargetProducer::Span { .. } | TargetProducer::ValueOnly(_) => None,
            })
            .collect::<Vec<_>>();
        let mut computed_vertices = 0usize;
        let mut cycle_errors = 0usize;
        let mut replans = 0usize;
        const MAX_REPLAN: usize = 5;
        loop {
            let (precedents_to_eval, old_vdeps) = self.build_demand_subgraph(&root_vertices);
            if precedents_to_eval.is_empty() {
                break;
            }
            let scheduler = Scheduler::new(&self.graph);
            let schedule =
                scheduler.create_schedule_with_virtual(&precedents_to_eval, &old_vdeps)?;
            for &unit in &schedule.units {
                self.cancellation_checkpoint("Evaluation cancelled before target schedule unit")?;
                match unit {
                    ScheduleUnit::Cycle(index) => {
                        if self.handle_cycle_unit(
                            schedule.unit_cycle(index),
                            delta.as_deref_mut(),
                            None,
                            None,
                        )? > 0
                        {
                            cycle_errors = cycle_errors.saturating_add(1);
                        }
                    }
                    ScheduleUnit::Layer(index) => {
                        let layer = schedule.unit_layer(index);
                        let evaluated = if let Some(delta) = delta.as_deref_mut() {
                            if self.thread_pool.is_some() && layer.vertices.len() > 1 {
                                self.evaluate_layer_parallel_with_delta(layer, delta)?
                            } else {
                                self.evaluate_layer_sequential_with_delta(layer, delta)?
                            }
                        } else if self.thread_pool.is_some() && layer.vertices.len() > 1 {
                            self.evaluate_layer_parallel(layer)?
                        } else {
                            self.evaluate_layer_sequential(layer)?
                        };
                        computed_vertices = computed_vertices.saturating_add(evaluated);
                    }
                }
            }
            let changed = self.changed_virtual_dep_vertices(&precedents_to_eval, &old_vdeps);
            self.resource_checkpoint(0)?;
            self.graph.clear_dirty_flags(&precedents_to_eval);
            for vertex in &changed {
                self.graph.set_dirty(*vertex, true);
            }
            if changed.is_empty() {
                break;
            }
            if replans >= MAX_REPLAN {
                return Err(self.replan_exhausted_error(
                    MAX_REPLAN,
                    "targeted legacy dynamic dependency evaluation",
                ));
            }
            replans = replans.saturating_add(1);
        }
        self.redirty_for_next_recalc();
        Ok(EvalResult {
            computed_vertices,
            cycle_errors,
            elapsed: start.elapsed(),
        })
    }

    /// Build a revision-bound compatibility plan covering every prepared formula vertex.
    pub fn build_recalc_plan(&self) -> Result<RecalcPlan, ExcelError> {
        if self.has_staged_formulas() || self.staged_formula_index.has_packages() {
            return Err(
                Self::plan_stale(formualizer_common::PlanStaleReason::Staged).with_message(
                    "compatibility recalculation plans require all staged formulas to be prepared",
                ),
            );
        }
        let key = self.recalc_plan_key();
        let mut vertices: Vec<VertexId> = self.graph.vertices_with_formulas().collect();
        vertices.sort_unstable();
        let has_dynamic_refs = vertices.iter().copied().any(|v| self.graph.is_dynamic(v));
        let schedule = if vertices.is_empty() {
            crate::engine::Schedule {
                units: Vec::new(),
                layers: Vec::new(),
                cycles: Vec::new(),
            }
        } else {
            self.create_evaluation_schedule_uncached(&vertices)?.0
        };
        self.validate_recalc_plan_key(&key)?;
        Ok(RecalcPlan {
            key,
            kind: RecalcPlanKind::CompatibilityFull {
                schedule,
                has_dynamic_refs,
            },
        })
    }

    /// Prepare stable typed targets and retain a revision-bound run-local recipe.
    pub fn build_recalc_plan_for_targets(
        &mut self,
        targets: &[crate::engine::EvaluationTarget],
    ) -> Result<RecalcPlan, ExcelError> {
        self.build_recalc_plan_for_targets_with_options(
            targets,
            crate::engine::TargetEvalOptions::default(),
        )
    }

    pub fn build_recalc_plan_for_targets_with_options(
        &mut self,
        targets: &[crate::engine::EvaluationTarget],
        options: crate::engine::TargetEvalOptions<'_>,
    ) -> Result<RecalcPlan, ExcelError> {
        self.observe_evaluation_resource_request(EvaluationRequestKind::RecalcPlan, |engine| {
            engine.observe_function_semantic_epoch()?;
            engine.validate_deterministic_mode()?;
            let _source_cache = engine.source_cache_session();
            let preparation = engine.prepare_graph_for_routed_evaluation(targets, &options)?;
            engine.graph.flush_pending_edge_deltas();
            let topology = if matches!(
                preparation.widened_scope,
                crate::engine::PrepareScope::Workbook
            ) {
                RecalcTopology::Workbook
            } else {
                RecalcTopology::RunLocalRecipe
            };
            Ok(RecalcPlan {
                key: engine.recalc_plan_key(),
                kind: RecalcPlanKind::Target {
                    targets: targets.to_vec(),
                    scope: preparation.widened_scope,
                    topology,
                    dynamic_policy: DynamicPlanPolicy::BoundedTargetReplan,
                },
            })
        })
    }

    /// Evaluate using a previously constructed compatibility or target plan.
    pub fn evaluate_recalc_plan(&mut self, plan: &RecalcPlan) -> Result<EvalResult, ExcelError> {
        self.observe_evaluation_resource_request(EvaluationRequestKind::RecalcPlan, |engine| {
            engine.evaluate_recalc_plan_unobserved(plan)
        })
    }

    pub fn evaluate_recalc_plan_with_controls(
        &mut self,
        plan: &RecalcPlan,
        cancel: Option<crate::engine::CancelToken>,
        deadline: Option<Instant>,
    ) -> Result<EvalResult, ExcelError> {
        self.observe_evaluation_resource_request(EvaluationRequestKind::RecalcPlan, |engine| {
            engine.active_cancel_flag = cancel.clone();
            engine.active_evaluation_deadline = deadline;
            let result = engine.evaluate_recalc_plan_unobserved(plan);
            engine.active_cancel_flag = None;
            engine.active_evaluation_deadline = None;
            result
        })
    }

    fn evaluate_recalc_plan_unobserved(
        &mut self,
        plan: &RecalcPlan,
    ) -> Result<EvalResult, ExcelError> {
        self.graph.flush_pending_edge_deltas();
        self.validate_recalc_plan_key(&plan.key)?;
        self.cancellation_checkpoint("Evaluation cancelled before recalculation plan execution")?;
        self.validate_deterministic_mode()?;

        match &plan.kind {
            RecalcPlanKind::Target {
                targets,
                scope,
                topology,
                dynamic_policy,
            } => {
                debug_assert_eq!(*dynamic_policy, DynamicPlanPolicy::BoundedTargetReplan);
                debug_assert_eq!(
                    matches!(topology, RecalcTopology::Workbook),
                    matches!(scope, crate::engine::PrepareScope::Workbook)
                );
                let _source_cache = self.source_cache_session();
                self.execute_prepared_target_recipe(targets, scope, None)
            }
            RecalcPlanKind::CompatibilityFull {
                schedule,
                has_dynamic_refs,
            } => {
                let _source_cache = self.source_cache_session();
                self.begin_evaluation_request();
                if self.graph.formula_authority().active_span_count() > 0 {
                    return self.evaluate_authoritative_formula_plane_all();
                }
                if *has_dynamic_refs {
                    self.virtual_dep_fallback_activations =
                        self.virtual_dep_fallback_activations.saturating_add(1);
                    return self.evaluate_all_coordinator();
                }

                let start = crate::instant::FzInstant::now();
                let dirty_vertices = self.graph.get_evaluation_vertices();
                if dirty_vertices.is_empty() {
                    return Ok(EvalResult {
                        computed_vertices: 0,
                        cycle_errors: 0,
                        elapsed: start.elapsed(),
                    });
                }

                let dirty_set: FxHashSet<VertexId> = dirty_vertices.iter().copied().collect();
                let mut computed_vertices = 0;
                let mut cycle_errors = 0;
                for &unit in &schedule.units {
                    self.cancellation_checkpoint(
                        "Evaluation cancelled before recalculation plan schedule unit",
                    )?;
                    match unit {
                        ScheduleUnit::Cycle(i) => {
                            let stamped = self.handle_cycle_unit(
                                schedule.unit_cycle(i),
                                None,
                                Some(&dirty_set),
                                None,
                            )?;
                            if stamped > 0 {
                                cycle_errors += 1;
                            }
                        }
                        ScheduleUnit::Layer(i) => {
                            let work: Vec<VertexId> = schedule
                                .unit_layer(i)
                                .vertices
                                .iter()
                                .copied()
                                .filter(|v| dirty_set.contains(v))
                                .collect();
                            if work.is_empty() {
                                continue;
                            }
                            let temp_layer = crate::engine::scheduler::Layer { vertices: work };
                            if self.thread_pool.is_some() && temp_layer.vertices.len() > 1 {
                                computed_vertices += self.evaluate_layer_parallel(&temp_layer)?;
                            } else {
                                computed_vertices += self.evaluate_layer_sequential(&temp_layer)?;
                            }
                        }
                    }
                }

                self.resource_checkpoint(0)?;
                self.graph.clear_dirty_flags(&dirty_vertices);
                self.redirty_for_next_recalc();
                Ok(EvalResult {
                    computed_vertices,
                    cycle_errors,
                    elapsed: start.elapsed(),
                })
            }
        }
    }
    fn evaluate_all_legacy_and_ack_dirty(
        &mut self,
        formula_dirty: FormulaDirtyLease,
    ) -> Result<EvalResult, ExcelError> {
        let result = self.evaluate_all_legacy_impl()?;
        self.checked_ack_formula_dirty_observed(formula_dirty)?;
        Ok(result)
    }

    fn evaluate_formula_plane_capacity_fallback(
        &mut self,
        mut formula_dirty: FormulaDirtyLease,
        owned_dirty_events: &[usize],
        selected_span_refs: &[FormulaSpanRef],
        target_roots: Option<&[crate::engine::target_preparation::TargetProducer]>,
        delta: Option<&mut DeltaCollector>,
    ) -> Result<EvalResult, ExcelError> {
        let leased_len = formula_dirty.len();
        if !selected_span_refs.is_empty() {
            let materialization_started = crate::instant::FzInstant::now();
            let prepared = self
                .prepare_formula_span_demotion(selected_span_refs)
                .map_err(|error| {
                    if let FormulaSpanDemotionError::Resource(error) = error {
                        error
                    } else {
                        ExcelError::new(ExcelErrorKind::NImpl).with_message(format!(
                            "FormulaPlane capacity fallback demotion preparation failed: {error}"
                        ))
                    }
                })?;
            let report = self
                .commit_prepared_formula_span_demotion(prepared)
                .map_err(|error| {
                    ExcelError::new(ExcelErrorKind::NImpl).with_message(format!(
                        "FormulaPlane capacity fallback demotion commit failed: {error}"
                    ))
                })?;
            self.observe_materialization(
                report.placements_materialized,
                false,
                materialization_started.elapsed(),
            );
        }
        #[cfg(test)]
        {
            self.last_formula_plane_span_eval_report = None;
        }
        if let Some(extended) = self.graph.extend_formula_dirty_lease(formula_dirty.clone()) {
            formula_dirty = extended;
        }
        let mut acknowledged = owned_dirty_events.to_vec();
        acknowledged.extend(leased_len..formula_dirty.len());
        let result = if let Some(target_roots) = target_roots {
            let refreshed = self.resolve_target_producers_from_existing_roots(target_roots)?;
            self.evaluate_legacy_target_roots(&refreshed, delta)?
        } else if let Some(delta) = delta {
            self.evaluate_all_with_delta_collector(delta)?
        } else {
            self.evaluate_all_legacy_impl()?
        };
        self.formula_plane_capacity_bailouts =
            self.formula_plane_capacity_bailouts.saturating_add(1);
        if target_roots.is_some() {
            self.checked_ack_formula_dirty_sublease_observed(formula_dirty, &acknowledged)?;
        } else {
            self.checked_ack_formula_dirty_observed(formula_dirty)?;
        }
        Ok(result)
    }

    fn evaluate_authoritative_formula_plane_all(&mut self) -> Result<EvalResult, ExcelError> {
        self.evaluate_authoritative_formula_plane(None, None)
    }

    fn evaluate_authoritative_formula_plane_targets(
        &mut self,
        roots: &[crate::engine::target_preparation::TargetProducer],
        delta: Option<&mut DeltaCollector>,
    ) -> Result<EvalResult, ExcelError> {
        self.evaluate_authoritative_formula_plane(Some(roots), delta)
    }

    fn evaluate_authoritative_formula_plane(
        &mut self,
        target_roots: Option<&[crate::engine::target_preparation::TargetProducer]>,
        mut delta: Option<&mut DeltaCollector>,
    ) -> Result<EvalResult, ExcelError> {
        // The public/request coordinators begin exactly once. Every primitive
        // below is deliberately non-beginning and non-finalising so the dirty
        // lease, iterative accumulator and §7.11 clock sample have one owner.
        let mut formula_dirty = self.graph.lease_formula_dirty();
        self.observe_dirty_lease_acquired(formula_dirty.is_empty());

        // SingletonUnique formulas intentionally remain legacy graph vertices;
        // when no spans are active, execute through the private legacy primitive.
        if self.graph.formula_authority().active_span_count() == 0 {
            self.observe_topology_strategy(FormulaPlaneTopologyStrategy::SkippedNoActiveSpans);
            #[cfg(test)]
            {
                self.last_formula_plane_span_eval_report = None;
            }
            if let Some(target_roots) = target_roots {
                let result =
                    self.evaluate_legacy_target_roots(target_roots, delta.as_deref_mut())?;
                self.checked_ack_formula_dirty_sublease_observed(formula_dirty, &[])?;
                return Ok(result);
            }
            return self.evaluate_all_legacy_and_ack_dirty(formula_dirty);
        }

        // With no graph-owned span/region dirtiness, only sparse legacy work
        // (including volatiles) can remain. Preserve the warm no-op fast path.
        if formula_dirty.is_empty() {
            self.observe_topology_strategy(FormulaPlaneTopologyStrategy::SkippedNoDirtyWork);
            #[cfg(test)]
            {
                self.last_formula_plane_span_eval_report = None;
            }
            if let Some(target_roots) = target_roots {
                let result =
                    self.evaluate_legacy_target_roots(target_roots, delta.as_deref_mut())?;
                self.checked_ack_formula_dirty_sublease_observed(formula_dirty, &[])?;
                return Ok(result);
            }
            return self.evaluate_all_legacy_and_ack_dirty(formula_dirty);
        }

        let start = crate::instant::FzInstant::now();
        let mut runtime_target_roots = target_roots.map(<[_]>::to_vec);
        let mut workbook_exact_attempted = target_roots.is_none();
        // #CIRC stamps produced by demoting cyclic spans and resolving the
        // residual legacy-only cycle ahead of the mixed schedule (gotcha G8).
        let mut prepass_cycle_errors = 0usize;
        const MAX_CYCLE_DEMOTE_ITERS: usize = 64;
        let mut cycle_demote_iters = 0usize;
        let mut include_dirty_regions = true;
        let mut retry_whole_spans = Vec::new();
        let mut computed_vertices = 0usize;
        let mut runtime_replan_iterations = 0usize;
        const MAX_RUNTIME_REPLAN: usize = 5;
        let mut virtual_telemetry = self
            .config
            .enable_virtual_dep_telemetry
            .then(|| self.start_virtual_dep_telemetry());
        'virtual_replan: loop {
            self.cancellation_checkpoint("Evaluation cancelled before mixed topology")?;
            let (
                schedule,
                span_refs_by_id,
                plane_epoch,
                legacy_vertices,
                owned_dirty_events,
                island_plan,
            ) = loop {
                let (
                    schedule,
                    span_refs_by_id,
                    plane_epoch,
                    legacy_vertices,
                    owned_dirty_events,
                    island_plan,
                ) = if let Some(target_roots) = runtime_target_roots.as_deref() {
                    self.build_formula_plane_target_schedule(
                        &formula_dirty,
                        &retry_whole_spans,
                        include_dirty_regions,
                        target_roots,
                    )?
                } else {
                    self.build_formula_plane_mixed_schedule(
                        &formula_dirty,
                        &retry_whole_spans,
                        include_dirty_regions,
                    )?
                };
                #[cfg(test)]
                let mut schedule = schedule;
                #[cfg(test)]
                if std::mem::take(&mut self.force_non_cycle_schedule_fallback_for_test) {
                    let producer = schedule
                        .layers
                        .iter()
                        .flat_map(|layer| layer.work.iter())
                        .map(|work| work.producer)
                        .next()
                        .unwrap_or(FormulaProducerId::Legacy(VertexId(0)));
                    schedule.fallbacks.push(
                        crate::formula_plane::scheduler::MixedScheduleFallback {
                            producer,
                            reason: MixedScheduleFallbackReason::MissingProducerResultRegion,
                        },
                    );
                }

                if schedule.is_authoritative_safe() {
                    break (
                        schedule,
                        span_refs_by_id,
                        plane_epoch,
                        legacy_vertices,
                        owned_dirty_events,
                        island_plan,
                    );
                }

                // Non-cycle unsafe schedules cannot safely run legacy-only while a
                // scheduled span remains virtual. Refine exactly every span in this
                // request's scheduled work, then complete the request in one legacy
                // pass. Clean, unscheduled spans keep their authority and overlays.
                let has_cycle_fallback = schedule.stats.cycle_count > 0
                    || schedule
                        .fallbacks
                        .iter()
                        .any(|fb| fb.reason == MixedScheduleFallbackReason::CycleDetected);
                if !has_cycle_fallback {
                    let selected_span_refs = schedule
                        .layers
                        .iter()
                        .flat_map(|layer| layer.work.iter())
                        .filter_map(|work| match work.producer {
                            FormulaProducerId::Span(span_id) => {
                                span_refs_by_id.get(&span_id).copied()
                            }
                            FormulaProducerId::Legacy(_) => None,
                        })
                        .collect::<Vec<_>>();

                    return self.evaluate_formula_plane_capacity_fallback(
                        formula_dirty,
                        &owned_dirty_events,
                        &selected_span_refs,
                        runtime_target_roots.as_deref(),
                        delta.as_deref_mut(),
                    );
                }

                // Gotcha G8 (refs #112): a span whose member cell participates in a
                // statically-cyclic SCC must never be span-evaluated. Cross-cell
                // cycles that route through a span producer are invisible to the
                // legacy Tarjan pass (the span member has no graph vertex) and only
                // surface here, as `CycleDetected` fallbacks in the producer-bounded
                // mixed schedule. Demote the cyclic spans to legacy graph vertices
                // so the cycle members move onto the legacy SCC path, then resolve
                // the now legacy-only cycle ahead of the schedule and rebuild.
                // Spans that do not touch the cycle are left untouched.
                let cyclic_spans = self.collect_cyclic_span_refs(&schedule, &span_refs_by_id);
                if !cyclic_spans.is_empty() {
                    self.demote_cyclic_spans(&cyclic_spans)?;
                }

                if self.graph.formula_authority().active_span_count() == 0 {
                    // All spans demoted; nothing left for the FP coordinator. The
                    // legacy evaluator resolves the (now fully legacy) cycle.
                    if let Some(target_roots) = runtime_target_roots.as_deref() {
                        let refreshed =
                            self.resolve_target_producers_from_existing_roots(target_roots)?;
                        let result =
                            self.evaluate_legacy_target_roots(&refreshed, delta.as_deref_mut())?;
                        self.checked_ack_formula_dirty_sublease_observed(formula_dirty, &[])?;
                        return Ok(result);
                    }
                    return self.evaluate_all_legacy_and_ack_dirty(formula_dirty);
                }

                // Resolve the residual legacy-only cycle (`handle_cycle_unit`
                // honors Static vs Runtime) before rebuilding so the mixed schedule
                // is cycle-free and the surviving spans still get evaluated.
                prepass_cycle_errors =
                    prepass_cycle_errors.saturating_add(self.evaluate_legacy_cycle_prepass()?);

                // Re-seed every surviving span explicitly through the graph-owned
                // dirty authority, then renew the lease so successful completion
                // acknowledges both the original prefix and retry seeds.
                retry_whole_spans = if runtime_target_roots.is_some() {
                    let active = self
                        .graph
                        .formula_authority()
                        .active_span_refs()
                        .into_iter()
                        .map(|span_ref| (span_ref.id, span_ref))
                        .collect::<BTreeMap<_, _>>();
                    let mut refs = schedule
                        .layers
                        .iter()
                        .flat_map(|layer| layer.work.iter())
                        .filter_map(|work| match work.producer {
                            FormulaProducerId::Span(id) => active.get(&id).copied(),
                            FormulaProducerId::Legacy(_) => None,
                        })
                        .collect::<Vec<_>>();
                    refs.extend(schedule.fallbacks.iter().filter_map(|fallback| {
                        match fallback.producer {
                            FormulaProducerId::Span(id) => active.get(&id).copied(),
                            FormulaProducerId::Legacy(_) => None,
                        }
                    }));
                    refs.sort_by_key(|span_ref| span_ref.id);
                    refs.dedup();
                    refs
                } else {
                    self.graph.formula_authority().active_span_refs()
                };
                self.graph.mark_formula_spans_dirty(
                    retry_whole_spans.iter().copied(),
                    WholeSpanDirtyReason::CycleRetry,
                );
                // Only the first renewal can enlarge this generation's owned
                // prefix. If another cycle iteration is required, its redundant
                // retry seeds stay pending rather than risking acknowledgement of
                // work recorded after the first renewal.
                if let Some(extended) = self.graph.extend_formula_dirty_lease(formula_dirty.clone())
                {
                    formula_dirty = extended;
                    #[cfg(test)]
                    if std::mem::take(
                        &mut self.rerecord_cycle_retry_span_after_lease_extension_for_test,
                    ) {
                        self.graph.mark_formula_spans_dirty(
                            retry_whole_spans.iter().copied().take(1),
                            WholeSpanDirtyReason::GlobalInvalidation,
                        );
                    }
                }
                include_dirty_regions = false;

                cycle_demote_iters += 1;
                if cycle_demote_iters >= MAX_CYCLE_DEMOTE_ITERS {
                    return Err(ExcelError::new(ExcelErrorKind::NImpl).with_message(
                        "FormulaPlane cyclic demotion did not converge".to_string(),
                    ));
                }
            };
            self.observe_formula_plane_route(
                &island_plan,
                FormulaPlaneRoutePhase::Planned,
                FormulaPlaneRouteTransitionReason::ProvenIsolated,
                cycle_demote_iters,
                runtime_replan_iterations,
            );
            if !island_plan.dirty_vertices.is_empty() {
                self.cancellation_checkpoint("Evaluation cancelled before legacy island")?;
                let (island_computed, island_cycles) = self.evaluate_legacy_island_non_finalizing(
                    &island_plan.dirty_vertices,
                    delta.as_deref_mut(),
                )?;
                computed_vertices = computed_vertices.saturating_add(island_computed);
                prepass_cycle_errors = prepass_cycle_errors.saturating_add(island_cycles);
                self.observe_formula_plane_route(
                    &island_plan,
                    FormulaPlaneRoutePhase::Executed,
                    FormulaPlaneRouteTransitionReason::ProvenIsolated,
                    cycle_demote_iters,
                    runtime_replan_iterations,
                );
                self.cancellation_checkpoint("Evaluation cancelled after legacy island")?;
            }
            let old_virtual_dependencies = VirtualDepBuilder::new(self).build(&legacy_vertices).0;
            let old_dynamic_regions = self.dynamic_virtual_regions(&legacy_vertices);

            #[cfg(test)]
            {
                self.last_formula_plane_span_eval_report = None;
            }
            for layer in schedule.layers {
                self.cancellation_checkpoint("Evaluation cancelled before mixed layer")?;
                let mut buffer = ComputedWriteBuffer::default();
                let mut sink = SpanComputedWriteSink::new(&mut buffer);
                let work_items = layer.work;
                let mut work_index = 0usize;
                while work_index < work_items.len() {
                    match work_items[work_index].producer {
                        FormulaProducerId::Span(span_id) => {
                            let span_ref = *span_refs_by_id.get(&span_id).ok_or_else(|| {
                                ExcelError::new(ExcelErrorKind::NImpl)
                                    .with_message("FormulaPlane schedule referenced a stale span")
                            })?;
                            let sheet_id = {
                                let authority = self.graph.formula_authority();
                                let span =
                                    authority.plane.spans.get(span_ref).ok_or_else(|| {
                                        ExcelError::new(ExcelErrorKind::NImpl).with_message(
                                            "FormulaPlane schedule referenced a stale span",
                                        )
                                    })?;
                                span.sheet_id
                            };
                            let current_sheet = self.graph.sheet_name(sheet_id);
                            let authority = self.graph.formula_authority();
                            let evaluator = SpanEvaluator::new_with_cancel(
                                &authority.plane,
                                self,
                                current_sheet,
                                self.graph.data_store(),
                                self.graph.sheet_reg(),
                                self.active_cancel_flag.as_ref(),
                            );
                            #[cfg(test)]
                            let mut last_group_report = None;
                            let mut selected_group_work = 0_u64;
                            while work_index < work_items.len() {
                                let FormulaProducerId::Span(group_span_id) =
                                    work_items[work_index].producer
                                else {
                                    break;
                                };
                                let group_span_ref =
                                    *span_refs_by_id.get(&group_span_id).ok_or_else(|| {
                                        ExcelError::new(ExcelErrorKind::NImpl).with_message(
                                            "FormulaPlane schedule referenced a stale span",
                                        )
                                    })?;
                                let group_sheet_id = {
                                    let authority = self.graph.formula_authority();
                                    let span =
                                        authority.plane.spans.get(group_span_ref).ok_or_else(
                                            || {
                                                ExcelError::new(ExcelErrorKind::NImpl).with_message(
                                                    "FormulaPlane schedule referenced a stale span",
                                                )
                                            },
                                        )?;
                                    span.sheet_id
                                };
                                if group_sheet_id != sheet_id {
                                    break;
                                }

                                let dirty = producer_dirty_to_span_dirty(
                                    work_items[work_index].dirty.clone(),
                                    group_span_ref,
                                );
                                let task = SpanEvalTask {
                                    span: group_span_ref,
                                    dirty,
                                    plane_epoch,
                                };
                                self.cancellation_checkpoint(
                                    "Evaluation cancelled during FormulaPlane span",
                                )?;
                                let report = evaluator.evaluate_task(&task, &mut sink).map_err(
                                    |err| {
                                        if err
                                            == crate::formula_plane::span_eval::SpanEvalError::Cancelled
                                        {
                                            ExcelError::new(ExcelErrorKind::Cancelled).with_message(
                                                "Evaluation cancelled during FormulaPlane span",
                                            )
                                        } else {
                                            ExcelError::new(ExcelErrorKind::NImpl).with_message(
                                                format!(
                                                    "FormulaPlane span evaluation failed: {err:?}"
                                                ),
                                            )
                                        }
                                    },
                                )?;
                                #[cfg(test)]
                                {
                                    last_group_report = Some(report.clone());
                                }
                                selected_group_work = selected_group_work
                                    .saturating_add(report.span_eval_placement_count);
                                computed_vertices = computed_vertices
                                    .saturating_add(report.span_eval_placement_count as usize);
                                work_index = work_index.saturating_add(1);
                            }
                            // Charge the exact selected placement regions before
                            // their transaction-local value buffer is published.
                            self.charge_bounded_work(selected_group_work)?;
                            #[cfg(test)]
                            {
                                if let Some(report) = last_group_report {
                                    self.last_formula_plane_span_eval_report = Some(report);
                                }
                            }
                        }
                        FormulaProducerId::Legacy(_) => {
                            // Batch the contiguous run of legacy work items into a
                            // synthetic layer and evaluate it through the same
                            // coalesced effects pipeline as the legacy scheduler.
                            // Items in one mixed layer have no edges between them
                            // (same invariant the legacy Kahn layers rely on), so
                            // batching preserves ordering semantics while
                            // amortizing per-write overlay mirroring that makes
                            // one-vertex-at-a-time evaluation ~30x slower.
                            let mut vertices = Vec::new();
                            while work_index < work_items.len() {
                                let FormulaProducerId::Legacy(vertex_id) =
                                    work_items[work_index].producer
                                else {
                                    break;
                                };
                                vertices.push(vertex_id);
                                work_index = work_index.saturating_add(1);
                            }
                            let legacy_layer = crate::engine::scheduler::Layer { vertices };
                            let evaluated = if let Some(delta) = delta.as_deref_mut() {
                                if self.thread_pool.is_some() && legacy_layer.vertices.len() > 1 {
                                    self.evaluate_layer_parallel_with_delta(&legacy_layer, delta)?
                                } else {
                                    self.evaluate_layer_sequential_with_delta(&legacy_layer, delta)?
                                }
                            } else if self.thread_pool.is_some() && legacy_layer.vertices.len() > 1
                            {
                                self.evaluate_layer_parallel(&legacy_layer)?
                            } else {
                                self.evaluate_layer_sequential(&legacy_layer)?
                            };
                            computed_vertices = computed_vertices.saturating_add(evaluated);
                        }
                    }
                }
                self.resource_checkpoint(0)?;
                self.cancellation_checkpoint("Evaluation cancelled before mixed layer flush")?;
                if let Some(delta) = delta.as_deref_mut() {
                    self.record_computed_write_buffer_delta(&buffer, delta);
                }
                self.flush_computed_write_buffer(&mut buffer)?;
            }

            let mut changed_virtual =
                self.changed_virtual_dep_vertices(&legacy_vertices, &old_virtual_dependencies);
            let new_dynamic_regions = self.dynamic_virtual_regions(&legacy_vertices);
            let mut dynamic_candidates = old_dynamic_regions
                .keys()
                .chain(new_dynamic_regions.keys())
                .copied()
                .collect::<FxHashSet<_>>();
            for vertex in dynamic_candidates.drain() {
                if old_dynamic_regions.get(&vertex) != new_dynamic_regions.get(&vertex)
                    && !changed_virtual.contains(&vertex)
                {
                    changed_virtual.push(vertex);
                }
            }
            if let Some(telemetry) = virtual_telemetry.as_mut() {
                telemetry.changed_vdeps_total = telemetry
                    .changed_vdeps_total
                    .saturating_add(changed_virtual.len());
            }
            self.resource_checkpoint(0)?;
            self.graph.clear_dirty_flags(&legacy_vertices);
            if !changed_virtual.is_empty() {
                for vertex in &changed_virtual {
                    self.graph.set_dirty(*vertex, true);
                }
                let can_replan = runtime_replan_iterations < MAX_RUNTIME_REPLAN;
                let can_attempt_workbook =
                    !can_replan && runtime_target_roots.is_some() && !workbook_exact_attempted;
                if can_replan || can_attempt_workbook {
                    if can_replan {
                        if let Some(roots) = runtime_target_roots.as_mut() {
                            self.extend_target_roots_with_dynamic_regions(
                                roots,
                                old_dynamic_regions
                                    .values()
                                    .flatten()
                                    .chain(new_dynamic_regions.values().flatten()),
                            )?;
                        }
                        runtime_replan_iterations = runtime_replan_iterations.saturating_add(1);
                    } else {
                        runtime_target_roots = None;
                        workbook_exact_attempted = true;
                    }
                    if let Some(stats) = self.active_evaluation_resource_request.as_mut() {
                        if can_replan {
                            stats.runtime_replan_rounds =
                                stats.runtime_replan_rounds.saturating_add(1);
                        }
                        stats.runtime_widening_rounds =
                            stats.runtime_widening_rounds.saturating_add(1);
                        if can_attempt_workbook {
                            stats.workbook_exact_attempts = 1;
                        }
                    }
                    self.cached_mixed_topology = None;
                    if let Some(ledger) = self.active_resource_ledger.as_mut() {
                        ledger
                            .account_mixed_cache(0)
                            .map_err(crate::engine::ResourceLedgerError::into_excel_error)?;
                    }
                    include_dirty_regions = true;
                    continue 'virtual_replan;
                }
                if let Some(telemetry) = virtual_telemetry.as_mut() {
                    telemetry.replan_iterations = runtime_replan_iterations;
                    telemetry.bailout_reason = Some("max_replan");
                    self.last_virtual_dep_telemetry = telemetry.clone();
                }
                return Err(self.replan_exhausted_error(
                    MAX_RUNTIME_REPLAN,
                    "mixed dynamic dependency evaluation",
                ));
            }
            if let Some(mut telemetry) = virtual_telemetry {
                telemetry.replan_iterations = runtime_replan_iterations;
                telemetry.bailout_reason = Some(if changed_virtual.is_empty() {
                    "converged"
                } else {
                    "max_replan"
                });
                self.last_virtual_dep_telemetry = telemetry;
            }
            // Drop dirty flags on any newly-scheduled FP runtime cells whose graph
            // vertices weren't in the dirty subset (e.g. recently-introduced span
            // result cells); legacy clear_dirty_flags is safe over the full set.
            self.redirty_for_next_recalc();
            self.checked_ack_formula_dirty_sublease_observed(formula_dirty, &owned_dirty_events)?;
            self.recalc_epoch = self.recalc_epoch.wrapping_add(1);
            return Ok(EvalResult {
                computed_vertices,
                cycle_errors: prepass_cycle_errors,
                elapsed: start.elapsed(),
            });
        }
    }

    fn effective_mixed_cache_limits(&self) -> (usize, usize, usize) {
        let budgets = &self.evaluation_resource_budgets;
        let candidate_limit = budgets
            .optimization
            .mixed_cache_candidates
            .map_or(self.config.max_formula_plane_cache_candidates, |limit| {
                limit.min(self.config.max_formula_plane_cache_candidates)
            });
        let edge_limit = budgets
            .optimization
            .mixed_cache_edges
            .map_or(self.config.max_formula_plane_cache_edges, |limit| {
                limit.min(self.config.max_formula_plane_cache_edges)
            });
        let mut byte_limit =
            u64::try_from(self.config.max_formula_plane_cache_bytes).unwrap_or(u64::MAX);
        if let Some(limit) = budgets.retained.total_bytes {
            byte_limit = byte_limit.min(limit);
        }
        if let Some(limit) = budgets.retained.mixed_cache_bytes {
            byte_limit = byte_limit.min(limit);
        }
        (
            candidate_limit,
            edge_limit,
            usize::try_from(byte_limit).unwrap_or(usize::MAX),
        )
    }

    fn mixed_topology_cache_key(&self) -> MixedTopologyCacheKey {
        let (max_candidates, max_edges, max_memory_bytes) = self.effective_mixed_cache_limits();
        MixedTopologyCacheKey {
            engine_topology_epoch: self.topology_epoch,
            graph_topology_revision: self.graph.topology_revision(),
            authority_indexes_epoch: self.graph.formula_authority().indexes_epoch(),
            legacy_island_revision: self.graph.topology_revision(),
            boundary_index_revision: self.graph.formula_authority().indexes_epoch(),
            function_semantic_epoch: self.function_semantic_epoch_seen,
            function_provider_revision: self.function_provider_revision_seen,
            max_candidates,
            max_edges,
            max_memory_bytes,
        }
    }

    fn mixed_topology_index_preflight_bytes(&self) -> u64 {
        use crate::formula_plane::region_index::AxisRange;

        const FIXED_BYTES: u64 = 8 * 1024;
        const ENTRY_BYTES: u64 = 512;
        const INDEX_UNIT_BYTES: u64 = 1024;
        const BINDING_BYTES: u64 = 128;
        let index_units = |region: Region| -> u64 {
            match region.normalized().axis_ranges() {
                (AxisRange::Point(_), AxisRange::Point(_)) => 2,
                (AxisRange::Span(row_start, row_end), AxisRange::Span(col_start, col_end)) => {
                    let row_buckets = u64::from(row_end / 64 - row_start / 64).saturating_add(1);
                    let col_buckets = u64::from(col_end / 16 - col_start / 16).saturating_add(1);
                    row_buckets.saturating_mul(col_buckets).saturating_mul(2)
                }
                _ => 1,
            }
        };

        let authority = self.graph.formula_authority();
        let span_refs = authority.active_span_refs();
        let legacy_vertices = self.graph.formula_vertices();
        let mut entry_count = 0_u64;
        let mut units = 0_u64;
        for span_ref in &span_refs {
            if let Some(span) = authority.plane.spans.get(*span_ref) {
                let result_region = Region::from_domain(span.result_region.domain());
                entry_count = entry_count.saturating_add(1);
                units = units.saturating_add(index_units(result_region));
                if let Some(summary_id) = span.read_summary_id
                    && let Some(summary) = authority.plane.span_read_summaries.get(summary_id)
                {
                    for dependency in &summary.dependencies {
                        entry_count = entry_count.saturating_add(1);
                        units = units.saturating_add(index_units(dependency.read_region));
                    }
                }
            }
        }
        for &vertex in &legacy_vertices {
            if let Some(cell) = self.graph.get_cell_ref_for_vertex(vertex) {
                let point = Region::point(cell.sheet_id, cell.coord.row(), cell.coord.col());
                entry_count = entry_count.saturating_add(1);
                units = units.saturating_add(index_units(point));
            }
            for dependency in self.graph.get_dependencies(vertex) {
                if let Some(cell) = self.graph.get_cell_ref_for_vertex(dependency) {
                    let point = Region::point(cell.sheet_id, cell.coord.row(), cell.coord.col());
                    entry_count = entry_count.saturating_add(1);
                    units = units.saturating_add(index_units(point));
                }
            }
            if let Some(ranges) = self.graph.get_range_dependencies(vertex) {
                for range in ranges {
                    if let Ok(Some(region)) = self.shared_range_to_region_pattern(range) {
                        entry_count = entry_count.saturating_add(1);
                        units = units.saturating_add(index_units(region));
                    }
                }
            }
        }
        FIXED_BYTES
            .saturating_add(entry_count.saturating_mul(ENTRY_BYTES))
            .saturating_add(units.saturating_mul(INDEX_UNIT_BYTES))
            .saturating_add((span_refs.len() as u64).saturating_mul(BINDING_BYTES))
    }

    fn prove_sheet_disjoint_legacy_island(
        &self,
        span_results: &FormulaProducerResultIndex,
        span_reads: &FormulaConsumerReadIndex,
        legacy_vertices: &[VertexId],
    ) -> Option<LegacyIslandPlan> {
        if !self.legacy_island_structural_summaries_trusted
            || self.graph.named_ranges_iter().next().is_some()
            || self.graph.sheet_named_ranges_iter().next().is_some()
            || self.graph.spill_registry_counts() != (0, 0)
            || legacy_vertices.iter().copied().any(|vertex| {
                self.graph.is_dynamic(vertex)
                    || self.graph.get_vertex_kind(vertex) == VertexKind::FormulaArray
            })
        {
            return None;
        }
        let span_result_sheets = span_results
            .entries()
            .filter(|entry| matches!(entry.producer, FormulaProducerId::Span(_)))
            .map(|entry| entry.result_region.sheet_id())
            .collect::<FxHashSet<_>>();
        let span_read_sheets = span_reads
            .entries()
            .filter(|entry| matches!(entry.consumer, FormulaProducerId::Span(_)))
            .map(|entry| entry.read_region.sheet_id())
            .collect::<FxHashSet<_>>();

        let span_boundary_sheets = span_result_sheets
            .union(&span_read_sheets)
            .copied()
            .collect::<FxHashSet<_>>();
        for vertex in legacy_vertices {
            let cell = self.graph.get_cell_ref_for_vertex(*vertex)?;
            if span_boundary_sheets.contains(&cell.sheet_id) {
                return None;
            }
            for dependency in self.graph.get_dependencies(*vertex) {
                let dependency_cell = self.graph.get_cell_ref_for_vertex(dependency)?;
                if span_boundary_sheets.contains(&dependency_cell.sheet_id) {
                    return None;
                }
            }
            if let Some(ranges) = self.graph.get_range_dependencies(*vertex) {
                for range in ranges {
                    let region = self.shared_range_to_region_pattern(range).ok()??;
                    if span_boundary_sheets.contains(&region.sheet_id()) {
                        return None;
                    }
                }
            }
        }

        let mut membership = legacy_vertices.to_vec();
        membership.sort_unstable();
        if membership.is_empty() {
            return None;
        }
        let mut sheet_ids = membership
            .iter()
            .filter_map(|vertex| self.graph.get_cell_ref_for_vertex(*vertex))
            .map(|cell| cell.sheet_id)
            .collect::<Vec<_>>();
        sheet_ids.sort_unstable();
        sheet_ids.dedup();
        let island_id = membership
            .iter()
            .fold(0xcbf29ce484222325_u64, |hash, vertex| {
                (hash ^ u64::from(vertex.0)).wrapping_mul(0x100000001b3)
            });
        let retained_bytes = membership
            .capacity()
            .saturating_mul(std::mem::size_of::<VertexId>())
            .saturating_add(
                sheet_ids
                    .capacity()
                    .saturating_mul(std::mem::size_of::<SheetId>()),
            );
        Some(LegacyIslandPlan {
            membership,
            dirty_vertices: Vec::new(),
            sheet_ids,
            island_id,
            retained_bytes,
            boundary_relationships: 0,
            omitted_relationships: legacy_vertices.len(),
            omitted_direct_relationships: 0,
        })
    }

    fn contract_legacy_islands(
        &self,
        full_results: &FormulaProducerResultIndex,
        full_reads: &FormulaConsumerReadIndex,
        legacy_reads_complete: bool,
        candidate_cap: usize,
    ) -> Option<(
        FormulaProducerResultIndex,
        FormulaConsumerReadIndex,
        LegacyIslandPlan,
    )> {
        use crate::formula_plane::producer::ProjectionResult;
        use crate::formula_plane::region_index::BoundedRegionQueryResult;

        if !self.legacy_island_structural_summaries_trusted
            || !legacy_reads_complete
            || self.graph.named_ranges_iter().next().is_some()
            || self.graph.sheet_named_ranges_iter().next().is_some()
            || self.graph.spill_registry_counts() != (0, 0)
        {
            return None;
        }
        let legacy_vertices = self.graph.formula_vertices();
        if legacy_vertices.iter().copied().any(|vertex| {
            self.graph.is_dynamic(vertex)
                || self.graph.get_vertex_kind(vertex) == VertexKind::FormulaArray
        }) {
            return None;
        }

        let mut reads_by_consumer: FxHashMap<VertexId, Vec<Region>> = FxHashMap::default();
        for entry in full_reads.entries() {
            if let FormulaProducerId::Legacy(vertex) = entry.consumer {
                reads_by_consumer
                    .entry(vertex)
                    .or_default()
                    .push(entry.read_region);
            }
        }

        let mut connected = FxHashSet::default();
        let mut queue = VecDeque::new();
        let mut observed_candidates = 0usize;
        let mut boundary_relationships = 0usize;
        let add_connected = |vertex: VertexId,
                             connected: &mut FxHashSet<VertexId>,
                             queue: &mut VecDeque<VertexId>| {
            if connected.insert(vertex) {
                queue.push_back(vertex);
            }
        };

        // Span results -> legacy consumers.
        for result in full_results.entries() {
            if !matches!(result.producer, FormulaProducerId::Span(_)) {
                continue;
            }
            let remaining = candidate_cap.saturating_sub(observed_candidates);
            let query = full_reads.query_changed_region_bounded(result.result_region, remaining);
            let BoundedRegionQueryResult::Complete(query) = query else {
                return None;
            };
            observed_candidates = observed_candidates.saturating_add(query.stats.candidate_count);
            for matched in query.matches {
                if let FormulaProducerId::Legacy(vertex) = matched.value.consumer {
                    match matched.value.dirty {
                        ProjectionResult::NoIntersection => {}
                        ProjectionResult::Unsupported(_) => return None,
                        ProjectionResult::Exact(_) | ProjectionResult::Conservative { .. } => {
                            boundary_relationships = boundary_relationships.saturating_add(1);
                            add_connected(vertex, &mut connected, &mut queue);
                        }
                    }
                }
            }
        }

        // Span reads -> legacy producers.
        for read in full_reads.entries() {
            if !matches!(read.consumer, FormulaProducerId::Span(_)) {
                continue;
            }
            let remaining = candidate_cap.saturating_sub(observed_candidates);
            let query = full_results.query_bounded(read.read_region, remaining);
            let BoundedRegionQueryResult::Complete(query) = query else {
                return None;
            };
            observed_candidates = observed_candidates.saturating_add(query.stats.candidate_count);
            for matched in query.matches {
                if let FormulaProducerId::Legacy(vertex) = matched.value.producer {
                    boundary_relationships = boundary_relationships.saturating_add(1);
                    add_connected(vertex, &mut connected, &mut queue);
                }
            }
        }

        // Undirected closure through legacy relationships. Every vertex in this
        // closure remains in the mixed scheduler, preserving the only detector
        // for cycles whose path crosses a virtual span member.
        while let Some(vertex) = queue.pop_front() {
            let producer = FormulaProducerId::Legacy(vertex);
            if let Some(result_region) = full_results.producer_result_region(producer) {
                let remaining = candidate_cap.saturating_sub(observed_candidates);
                let query = full_reads.query_changed_region_bounded(result_region, remaining);
                let BoundedRegionQueryResult::Complete(query) = query else {
                    return None;
                };
                observed_candidates =
                    observed_candidates.saturating_add(query.stats.candidate_count);
                for matched in query.matches {
                    if let FormulaProducerId::Legacy(consumer) = matched.value.consumer {
                        match matched.value.dirty {
                            ProjectionResult::NoIntersection => {}
                            ProjectionResult::Unsupported(_) => return None,
                            ProjectionResult::Exact(_) | ProjectionResult::Conservative { .. } => {
                                add_connected(consumer, &mut connected, &mut queue);
                            }
                        }
                    }
                }
            }
            for read_region in reads_by_consumer.get(&vertex).into_iter().flatten() {
                let remaining = candidate_cap.saturating_sub(observed_candidates);
                let query = full_results.query_bounded(*read_region, remaining);
                let BoundedRegionQueryResult::Complete(query) = query else {
                    return None;
                };
                observed_candidates =
                    observed_candidates.saturating_add(query.stats.candidate_count);
                for matched in query.matches {
                    if let FormulaProducerId::Legacy(precedent) = matched.value.producer {
                        add_connected(precedent, &mut connected, &mut queue);
                    }
                }
            }
        }

        let mut membership = legacy_vertices
            .iter()
            .copied()
            .filter(|vertex| !connected.contains(vertex))
            .collect::<Vec<_>>();
        membership.sort_unstable();
        if membership.is_empty() {
            return None;
        }

        let mut producer_results = FormulaProducerResultIndex::default();
        let mut consumer_reads = FormulaConsumerReadIndex::default();
        let retained_span_results = full_results
            .entries()
            .filter(|entry| matches!(entry.producer, FormulaProducerId::Span(_)))
            .count();
        producer_results
            .try_reserve(retained_span_results.saturating_add(connected.len()))
            .ok()?;
        for entry in full_results.entries() {
            let retain = match entry.producer {
                FormulaProducerId::Span(_) => true,
                FormulaProducerId::Legacy(vertex) => connected.contains(&vertex),
            };
            if retain {
                producer_results.insert_producer(entry.producer, entry.result_region);
            }
        }
        for entry in full_reads.entries() {
            let retain = match entry.consumer {
                FormulaProducerId::Span(_) => true,
                FormulaProducerId::Legacy(vertex) => connected.contains(&vertex),
            };
            if retain {
                consumer_reads.try_reserve(1).ok()?;
                consumer_reads.insert_read(
                    entry.consumer,
                    entry.read_region,
                    entry.consumer_result_region,
                    entry.projection,
                );
            }
        }

        let mut sheet_ids = membership
            .iter()
            .filter_map(|vertex| self.graph.get_cell_ref_for_vertex(*vertex))
            .map(|cell| cell.sheet_id)
            .collect::<Vec<_>>();
        sheet_ids.sort_unstable();
        sheet_ids.dedup();
        let island_id = membership
            .iter()
            .fold(0xcbf29ce484222325_u64, |hash, vertex| {
                (hash ^ u64::from(vertex.0)).wrapping_mul(0x100000001b3)
            });
        let retained_bytes = membership
            .capacity()
            .saturating_mul(std::mem::size_of::<VertexId>())
            .saturating_add(
                sheet_ids
                    .capacity()
                    .saturating_mul(std::mem::size_of::<SheetId>()),
            );
        let omitted_relationships = full_reads
            .entries()
            .filter(|entry| matches!(entry.consumer, FormulaProducerId::Legacy(vertex) if !connected.contains(&vertex)))
            .count();
        let membership_set = membership.iter().copied().collect::<FxHashSet<_>>();
        let omitted_direct_relationships = membership
            .iter()
            .map(|vertex| {
                self.graph
                    .get_dependencies(*vertex)
                    .into_iter()
                    .filter(|dependency| membership_set.contains(dependency))
                    .count()
            })
            .sum();
        Some((
            producer_results,
            consumer_reads,
            LegacyIslandPlan {
                membership,
                dirty_vertices: Vec::new(),
                sheet_ids,
                island_id,
                retained_bytes,
                boundary_relationships,
                omitted_relationships,
                omitted_direct_relationships,
            },
        ))
    }

    fn compile_formula_plane_mixed_topology(
        &mut self,
        key: MixedTopologyCacheKey,
    ) -> Result<FormulaPlaneTopologyCompileResult, ExcelError> {
        #[cfg(test)]
        {
            self.mixed_topology_index_builds_for_test =
                self.mixed_topology_index_builds_for_test.saturating_add(1);
        }
        let authority = self.graph.formula_authority();
        let mut producer_results = FormulaProducerResultIndex::default();
        let mut consumer_reads = FormulaConsumerReadIndex::default();
        let mut legacy_reads_complete = true;
        let span_refs = authority.active_span_refs();
        let legacy_vertices = self.graph.formula_vertices();
        let _producer_count = span_refs
            .len()
            .checked_add(legacy_vertices.len())
            .ok_or_else(|| {
                ExcelError::new(ExcelErrorKind::NImpl)
                    .with_message("FormulaPlane cache producer count overflow")
            })?;
        producer_results.try_reserve(_producer_count).map_err(|_| {
            ExcelError::new(ExcelErrorKind::NImpl)
                .with_message("FormulaPlane cache producer index reservation failed")
        })?;
        let span_refs_by_id = span_refs
            .iter()
            .copied()
            .map(|span_ref| (span_ref.id, span_ref))
            .collect::<BTreeMap<_, _>>();
        for span_ref in &span_refs {
            let span = authority.plane.spans.get(*span_ref).ok_or_else(|| {
                ExcelError::new(ExcelErrorKind::NImpl)
                    .with_message("FormulaPlane active span ref is stale")
            })?;
            let result_region = Region::from_domain(span.result_region.domain());
            producer_results.insert_producer(FormulaProducerId::Span(span.id), result_region);
            let Some(read_summary_id) = span.read_summary_id else {
                return Err(ExcelError::new(ExcelErrorKind::NImpl)
                    .with_message("FormulaPlane active span is missing read summary"));
            };
            let Some(read_summary) = authority.plane.span_read_summaries.get(read_summary_id)
            else {
                return Err(ExcelError::new(ExcelErrorKind::NImpl)
                    .with_message("FormulaPlane active span has stale read summary"));
            };
            if read_summary.result_region != result_region {
                return Err(ExcelError::new(ExcelErrorKind::NImpl)
                    .with_message("FormulaPlane active span read summary is stale"));
            }
            for dependency in &read_summary.dependencies {
                consumer_reads.try_reserve(1).map_err(|_| {
                    ExcelError::new(ExcelErrorKind::NImpl)
                        .with_message("FormulaPlane cache read-index reservation failed")
                })?;
                consumer_reads.insert_read(
                    FormulaProducerId::Span(span.id),
                    dependency.read_region,
                    read_summary.result_region,
                    dependency.projection,
                );
            }
        }

        let sheet_disjoint_island = self.prove_sheet_disjoint_legacy_island(
            &producer_results,
            &consumer_reads,
            &legacy_vertices,
        );
        if sheet_disjoint_island.is_none() {
            for vertex in &legacy_vertices {
                let Some(cell) = self.graph.get_cell_ref_for_vertex(*vertex) else {
                    continue;
                };
                producer_results.insert_producer(
                    FormulaProducerId::Legacy(*vertex),
                    Region::point(cell.sheet_id, cell.coord.row(), cell.coord.col()),
                );
            }
            for vertex in &legacy_vertices {
                let Some(cell) = self.graph.get_cell_ref_for_vertex(*vertex) else {
                    continue;
                };
                let result_region =
                    Region::point(cell.sheet_id, cell.coord.row(), cell.coord.col());
                let mut seen = rustc_hash::FxHashSet::default();
                for dep in self.graph.get_dependencies(*vertex) {
                    let Some(dep_cell) = self.graph.get_cell_ref_for_vertex(dep) else {
                        // Named/table/source vertices do not have a trustworthy
                        // regional boundary summary. Preserve the global planner.
                        legacy_reads_complete = false;
                        continue;
                    };
                    let read_region = Region::point(
                        dep_cell.sheet_id,
                        dep_cell.coord.row(),
                        dep_cell.coord.col(),
                    );
                    if seen.insert(read_region) {
                        consumer_reads.try_reserve(1).map_err(|_| {
                            ExcelError::new(ExcelErrorKind::NImpl)
                                .with_message("FormulaPlane cache read-index reservation failed")
                        })?;
                        consumer_reads.insert_read(
                            FormulaProducerId::Legacy(*vertex),
                            read_region,
                            result_region,
                            DirtyProjectionRule::WholeResult,
                        );
                    }
                }
                if let Some(ranges) = self.graph.get_range_dependencies(*vertex) {
                    for range in ranges {
                        let Some(read_region) = self.shared_range_to_region_pattern(range)? else {
                            legacy_reads_complete = false;
                            continue;
                        };
                        if seen.insert(read_region) {
                            consumer_reads.try_reserve(1).map_err(|_| {
                                ExcelError::new(ExcelErrorKind::NImpl).with_message(
                                    "FormulaPlane cache read-index reservation failed",
                                )
                            })?;
                            consumer_reads.insert_read(
                                FormulaProducerId::Legacy(*vertex),
                                read_region,
                                result_region,
                                DirtyProjectionRule::WholeResult,
                            );
                        }
                    }
                }
                let (virtual_dependencies, _) = VirtualDepBuilder::new(self).build(&[*vertex]);
                for dependency in virtual_dependencies
                    .get(vertex)
                    .into_iter()
                    .flatten()
                    .copied()
                {
                    let Some(cell) = self.graph.get_cell_ref_for_vertex(dependency) else {
                        continue;
                    };
                    let read_region =
                        Region::point(cell.sheet_id, cell.coord.row(), cell.coord.col());
                    if seen.insert(read_region) {
                        consumer_reads.try_reserve(1).map_err(|_| {
                            ExcelError::new(ExcelErrorKind::NImpl)
                                .with_message("FormulaPlane cache virtual read reservation failed")
                        })?;
                        consumer_reads.insert_read(
                            FormulaProducerId::Legacy(*vertex),
                            read_region,
                            result_region,
                            DirtyProjectionRule::WholeResult,
                        );
                    }
                }
                for read_region in DynamicRefVirtualDepProvider::get_virtual_regions(self, *vertex)
                {
                    if seen.insert(read_region) {
                        consumer_reads.try_reserve(1).map_err(|_| {
                            ExcelError::new(ExcelErrorKind::NImpl)
                                .with_message("FormulaPlane dynamic-region reservation failed")
                        })?;
                        consumer_reads.insert_read(
                            FormulaProducerId::Legacy(*vertex),
                            read_region,
                            result_region,
                            DirtyProjectionRule::WholeResult,
                        );
                    }
                }
            }
        }

        // Boundary discovery uses complete, request-local indexes. Only the
        // span-connected closure is retained and compiled; disconnected legacy
        // membership is contracted into the legacy scheduler primitive.
        let (producer_results, consumer_reads, island) = if let Some(island) = sheet_disjoint_island
        {
            (producer_results, consumer_reads, island)
        } else {
            self.contract_legacy_islands(
                &producer_results,
                &consumer_reads,
                legacy_reads_complete,
                key.max_candidates,
            )
            .unwrap_or((
                producer_results,
                consumer_reads,
                LegacyIslandPlan::default(),
            ))
        };

        let retained_memory_bytes = std::mem::size_of::<CachedMixedTopology>()
            .checked_add(
                producer_results
                    .estimated_memory_bytes()
                    .unwrap_or(usize::MAX),
            )
            .and_then(|bytes| {
                bytes.checked_add(
                    consumer_reads
                        .estimated_memory_bytes()
                        .unwrap_or(usize::MAX),
                )
            })
            .and_then(|bytes| bytes.checked_add(estimated_span_bindings_bytes(&span_refs_by_id)?))
            .and_then(|bytes| bytes.checked_add(island.retained_bytes))
            .unwrap_or(usize::MAX);
        let config = MixedTopologyConfig {
            max_candidates: key.max_candidates,
            max_edges: key.max_edges,
            max_memory_bytes: key.max_memory_bytes,
            retained_memory_bytes,
        };
        let mut compiled = compile_mixed_topology(&producer_results, &consumer_reads, &config);
        // `producers_observed` remains a discovery counter, not merely the
        // post-contraction mixed-node count. Preserve that established meaning
        // while exposing omissions separately in route telemetry.
        match &mut compiled {
            MixedTopologyCompileResult::Cached(topology) => {
                topology.stats.producers = topology
                    .stats
                    .producers
                    .saturating_add(island.membership.len());
                topology.stats.candidates = topology
                    .stats
                    .candidates
                    .saturating_add(island.omitted_direct_relationships);
                topology.stats.relationships = topology
                    .stats
                    .relationships
                    .saturating_add(island.omitted_direct_relationships);
            }
            MixedTopologyCompileResult::CacheSkipped { observed, .. } => {
                observed.producers = observed.producers.saturating_add(island.membership.len());
                observed.candidates = observed
                    .candidates
                    .saturating_add(island.omitted_direct_relationships);
                observed.relationships = observed
                    .relationships
                    .saturating_add(island.omitted_direct_relationships);
            }
        }
        let plane_epoch = authority.plane.epoch().0;
        Ok(match compiled {
            MixedTopologyCompileResult::Cached(topology) => {
                FormulaPlaneTopologyCompileResult::Cached(CachedMixedTopology {
                    key,
                    topology,
                    producer_results,
                    consumer_reads,
                    span_refs_by_id,
                    plane_epoch,
                    island,
                })
            }
            MixedTopologyCompileResult::CacheSkipped { reason, observed } => {
                FormulaPlaneTopologyCompileResult::CacheSkipped(SkippedMixedTopology {
                    reason,
                    observed,
                    producer_results,
                    consumer_reads,
                    span_refs_by_id,
                    plane_epoch,
                    island,
                })
            }
        })
    }

    fn build_formula_plane_mixed_schedule(
        &mut self,
        formula_dirty: &FormulaDirtyLease,
        retry_whole_spans: &[FormulaSpanRef],
        include_dirty_regions: bool,
    ) -> Result<FormulaPlaneMixedScheduleBuild, ExcelError> {
        self.build_formula_plane_mixed_schedule_inner(
            formula_dirty,
            retry_whole_spans,
            include_dirty_regions,
            None,
        )
    }

    fn build_formula_plane_target_schedule(
        &mut self,
        formula_dirty: &FormulaDirtyLease,
        retry_whole_spans: &[FormulaSpanRef],
        include_dirty_regions: bool,
        target_roots: &[crate::engine::target_preparation::TargetProducer],
    ) -> Result<FormulaPlaneMixedScheduleBuild, ExcelError> {
        self.build_formula_plane_mixed_schedule_inner(
            formula_dirty,
            retry_whole_spans,
            include_dirty_regions,
            Some(target_roots),
        )
    }

    fn build_formula_plane_mixed_schedule_inner(
        &mut self,
        formula_dirty: &FormulaDirtyLease,
        retry_whole_spans: &[FormulaSpanRef],
        include_dirty_regions: bool,
        target_roots: Option<&[crate::engine::target_preparation::TargetProducer]>,
    ) -> Result<FormulaPlaneMixedScheduleBuild, ExcelError> {
        let baseline = self.graph.baseline_stats();
        self.charge_bounded_work(
            baseline
                .graph_vertex_count
                .saturating_add(baseline.graph_edge_count) as u64,
        )?;
        let key = self.mixed_topology_cache_key();
        let active_refs = self
            .graph
            .formula_authority()
            .active_span_refs()
            .into_iter()
            .map(|span_ref| (span_ref.id, span_ref))
            .collect::<BTreeMap<_, _>>();
        let has_dynamic_legacy = self
            .graph
            .formula_vertices()
            .into_iter()
            .any(|vertex| self.graph.is_dynamic(vertex));
        let cache_hit = !has_dynamic_legacy
            && self
                .cached_mixed_topology
                .as_ref()
                .is_some_and(|cached| cached.key == key && cached.span_refs_by_id == active_refs);
        let mut skipped_topology = None;
        let mut index_scratch_reserved = 0_u64;
        let mut demand_scratch_reserved = 0_u64;
        let topology_started = crate::instant::FzInstant::now();
        let (cache_outcome, strategy, compile_stats) = if cache_hit {
            self.mixed_topology_cache_hits = self.mixed_topology_cache_hits.saturating_add(1);
            self.mixed_topology_cache_skip_streak = 0;
            let cached = self
                .cached_mixed_topology
                .as_ref()
                .expect("cache hit has topology");
            let stats = cached.topology.stats.clone();
            let strategy = if cached.topology.is_complete() {
                FormulaPlaneTopologyStrategy::Cached
            } else {
                FormulaPlaneTopologyStrategy::ExactPagedIndexed
            };
            if let Some(ledger) = self.active_resource_ledger.as_mut() {
                ledger
                    .account_mixed_cache(stats.estimated_memory_bytes as u64)
                    .map_err(crate::engine::ResourceLedgerError::into_excel_error)?;
            }
            (FormulaPlaneTopologyCacheOutcome::Hit, strategy, stats)
        } else {
            // A key/cap miss makes the old retained topology stale. Drop it before building its
            // replacement so the request never accounts or owns both generations concurrently.
            self.cached_mixed_topology = None;
            if let Some(ledger) = self.active_resource_ledger.as_mut() {
                ledger
                    .account_mixed_cache(0)
                    .map_err(crate::engine::ResourceLedgerError::into_excel_error)?;
            }

            let preflight = self.mixed_topology_index_preflight_bytes();
            if let Some(ledger) = self.active_resource_ledger.as_mut() {
                ledger
                    .reserve_schedule_discovery(preflight)
                    .map_err(crate::engine::ResourceLedgerError::into_excel_error)?;
            }
            index_scratch_reserved = preflight;
            let compiled = match self.compile_formula_plane_mixed_topology(key.clone()) {
                Ok(compiled) => compiled,
                Err(error) => {
                    if let Some(ledger) = self.active_resource_ledger.as_mut() {
                        let _ = ledger.release_scratch(index_scratch_reserved);
                    }
                    return Err(error);
                }
            };
            let actual_index_bytes = match &compiled {
                FormulaPlaneTopologyCompileResult::Cached(compiled) => compiled
                    .producer_results
                    .estimated_memory_bytes()
                    .and_then(|bytes| {
                        bytes.checked_add(compiled.consumer_reads.estimated_memory_bytes()?)
                    })
                    .and_then(|bytes| {
                        bytes.checked_add(estimated_span_bindings_bytes(&compiled.span_refs_by_id)?)
                    })
                    .and_then(|bytes| bytes.checked_add(compiled.island.retained_bytes)),
                FormulaPlaneTopologyCompileResult::CacheSkipped(skipped) => skipped
                    .producer_results
                    .estimated_memory_bytes()
                    .and_then(|bytes| {
                        bytes.checked_add(skipped.consumer_reads.estimated_memory_bytes()?)
                    })
                    .and_then(|bytes| {
                        bytes.checked_add(estimated_span_bindings_bytes(&skipped.span_refs_by_id)?)
                    })
                    .and_then(|bytes| bytes.checked_add(skipped.island.retained_bytes)),
            }
            .unwrap_or(usize::MAX) as u64;
            debug_assert!(
                actual_index_bytes <= index_scratch_reserved,
                "mixed topology index preflight underestimated actual allocation"
            );
            if actual_index_bytes > index_scratch_reserved {
                let additional = actual_index_bytes - index_scratch_reserved;
                let reserve_result = self
                    .active_resource_ledger
                    .as_mut()
                    .map_or(Ok(()), |ledger| {
                        ledger.reserve_schedule_discovery(additional)
                    });
                if let Err(error) = reserve_result {
                    drop(compiled);
                    if let Some(ledger) = self.active_resource_ledger.as_mut() {
                        let _ = ledger.release_scratch(index_scratch_reserved);
                    }
                    return Err(error.into_excel_error());
                }
            } else if actual_index_bytes < index_scratch_reserved
                && let Some(ledger) = self.active_resource_ledger.as_mut()
            {
                ledger
                    .release_scratch(index_scratch_reserved - actual_index_bytes)
                    .map_err(crate::engine::ResourceLedgerError::into_excel_error)?;
            }
            index_scratch_reserved = actual_index_bytes;

            self.mixed_topology_cache_builds = self.mixed_topology_cache_builds.saturating_add(1);
            match compiled {
                FormulaPlaneTopologyCompileResult::Cached(compiled) if has_dynamic_legacy => {
                    let stats = compiled.topology.stats.clone();
                    self.mixed_topology_cache_skip_streak =
                        self.mixed_topology_cache_skip_streak.saturating_add(1);
                    skipped_topology = Some(SkippedMixedTopology {
                        reason: MixedScheduleFallbackReason::CacheMemoryExceeded,
                        observed: stats.clone(),
                        producer_results: compiled.producer_results,
                        consumer_reads: compiled.consumer_reads,
                        span_refs_by_id: compiled.span_refs_by_id,
                        plane_epoch: compiled.plane_epoch,
                        island: compiled.island,
                    });
                    (
                        FormulaPlaneTopologyCacheOutcome::SkippedDynamicLegacy,
                        FormulaPlaneTopologyStrategy::ExactPagedIndexed,
                        stats,
                    )
                }
                FormulaPlaneTopologyCompileResult::Cached(compiled) => {
                    let stats = compiled.topology.stats.clone();
                    let strategy = if compiled.topology.is_complete() {
                        FormulaPlaneTopologyStrategy::CompiledAndCached
                    } else {
                        FormulaPlaneTopologyStrategy::ExactPagedIndexed
                    };
                    let retained_result = self
                        .active_resource_ledger
                        .as_mut()
                        .map_or(Ok(()), |ledger| {
                            ledger.account_mixed_cache(stats.estimated_memory_bytes as u64)
                        });
                    if let Err(error) = retained_result {
                        if let Some(ledger) = self.active_resource_ledger.as_mut() {
                            let _ = ledger.release_scratch(index_scratch_reserved);
                        }
                        return Err(error.into_excel_error());
                    }
                    self.mixed_topology_cache_skip_streak = 0;
                    self.cached_mixed_topology = Some(compiled);
                    if let Some(ledger) = self.active_resource_ledger.as_mut() {
                        ledger
                            .release_scratch(index_scratch_reserved)
                            .map_err(crate::engine::ResourceLedgerError::into_excel_error)?;
                    }
                    index_scratch_reserved = 0;
                    (FormulaPlaneTopologyCacheOutcome::Built, strategy, stats)
                }
                FormulaPlaneTopologyCompileResult::CacheSkipped(skipped) => {
                    debug_assert!(self.cached_mixed_topology.is_none());
                    self.mixed_topology_cache_overflows =
                        self.mixed_topology_cache_overflows.saturating_add(1);
                    self.mixed_topology_cache_skip_streak =
                        self.mixed_topology_cache_skip_streak.saturating_add(1);
                    let stats = skipped.observed.clone();
                    skipped_topology = Some(skipped);
                    (
                        FormulaPlaneTopologyCacheOutcome::SkippedOverflow,
                        FormulaPlaneTopologyStrategy::ExactPagedIndexed,
                        stats,
                    )
                }
            }
        };
        self.observe_topology(
            cache_outcome,
            strategy,
            &compile_stats,
            topology_started.elapsed(),
        );
        if let Some(stats) = self.active_evaluation_resource_request.as_mut() {
            stats.topology.cache_skip_streak = self.mixed_topology_cache_skip_streak;
            stats.topology.candidate_cap = Some(key.max_candidates as u64);
            stats.topology.edge_cap = Some(key.max_edges as u64);
            stats.topology.retained_byte_cap = Some(key.max_memory_bytes as u64);
            if cache_outcome == FormulaPlaneTopologyCacheOutcome::SkippedDynamicLegacy {
                stats.topology.operator_guidance =
                    Some("dynamic legacy dependencies require an exact request topology rebuild");
            } else if cache_outcome == FormulaPlaneTopologyCacheOutcome::SkippedOverflow {
                stats.topology.operator_guidance =
                    Some(if compile_stats.candidate_overflow_count > 0 {
                        "raise the mixed-cache candidate limit to avoid exact request rebuilds"
                    } else if compile_stats.edge_overflow_count > 0 {
                        "raise the mixed-cache edge limit to avoid exact request rebuilds"
                    } else {
                        "raise the retained mixed-cache byte limit to avoid exact request rebuilds"
                    });
            }
        }

        let reuse_partial_topology = cache_outcome == FormulaPlaneTopologyCacheOutcome::Hit;
        let schedule_result = (|| -> Result<FormulaPlaneMixedScheduleBuild, ExcelError> {
            let (
                producer_results,
                consumer_reads,
                span_refs_by_id,
                plane_epoch,
                cached_topology,
                partial_topology,
                island,
            ) = if let Some(skipped) = skipped_topology.as_ref() {
                (
                    &skipped.producer_results,
                    &skipped.consumer_reads,
                    &skipped.span_refs_by_id,
                    skipped.plane_epoch,
                    None,
                    None,
                    &skipped.island,
                )
            } else {
                let cached = self
                    .cached_mixed_topology
                    .as_ref()
                    .expect("mixed topology available for request");
                let (complete, partial) = if cached.topology.is_complete() {
                    (Some(&cached.topology), None)
                } else {
                    (None, Some(&cached.topology))
                };
                (
                    &cached.producer_results,
                    &cached.consumer_reads,
                    &cached.span_refs_by_id,
                    cached.plane_epoch,
                    complete,
                    partial,
                    &cached.island,
                )
            };
            let demand = if let Some(target_roots) = target_roots {
                use crate::engine::target_preparation::TargetProducer;
                let mut roots = Vec::new();
                let mut graph_roots = Vec::new();
                for root in target_roots {
                    match *root {
                        TargetProducer::Span { span_ref, demanded } => {
                            roots.push((FormulaProducerId::Span(span_ref.id), demanded))
                        }
                        TargetProducer::Legacy(vertex) => {
                            graph_roots.push(vertex);
                            if let Some(region) = producer_results
                                .producer_result_region(FormulaProducerId::Legacy(vertex))
                            {
                                roots.push((FormulaProducerId::Legacy(vertex), region));
                            }
                        }
                        TargetProducer::Symbol(vertex) => graph_roots.push(vertex),
                        TargetProducer::ValueOnly(_) => {}
                    }
                }
                if !graph_roots.is_empty() {
                    let (legacy_demand, _) = self.build_demand_subgraph(&graph_roots);
                    for vertex in legacy_demand {
                        if let Some(region) = producer_results
                            .producer_result_region(FormulaProducerId::Legacy(vertex))
                        {
                            roots.push((FormulaProducerId::Legacy(vertex), region));
                        }
                    }
                }
                let roots = roots;
                let closure_base = (producer_results.len() as u64)
                    .saturating_mul(128)
                    .saturating_add(4096);
                let scratch_estimates =
                    exact_demand_scratch_estimates(consumer_reads.len(), closure_base);
                let native_allowed = native_exact_demand_allowed(
                    self.active_resource_ledger
                        .as_ref()
                        .and_then(ResourceLedger::disk_scratch_policy),
                    !cfg!(target_arch = "wasm32"),
                );
                let (selected_strategy, reservation) = if cached_topology.is_some() {
                    (None, closure_base)
                } else {
                    let (strategy, reservation) =
                        select_exact_demand_strategy(scratch_estimates, native_allowed, |bytes| {
                            self.can_reserve_topology_scratch(bytes)
                        });
                    (Some(strategy), reservation)
                };
                if let Some(ledger) = self.active_resource_ledger.as_mut() {
                    ledger
                        .reserve_schedule_discovery(reservation)
                        .map_err(crate::engine::ResourceLedgerError::into_excel_error)?;
                }
                demand_scratch_reserved = reservation;
                #[allow(unused_mut)]
                let mut native_disk_bytes = 0_u64;
                let (demand, actual_strategy, passes) = match selected_strategy {
                    None => (
                        build_demand_closure_cached(
                            roots,
                            producer_results,
                            cached_topology.expect("cached demand strategy has topology"),
                        ),
                        None,
                        0,
                    ),
                    Some(FormulaPlaneTopologyStrategy::ExactPagedIndexed) => {
                        let (demand, passes) = build_demand_closure_paged(
                            roots,
                            producer_results,
                            consumer_reads,
                            |units| {
                                Self::resource_loop_checkpoint(
                                    &mut self.active_resource_ledger,
                                    units,
                                )
                            },
                        )?;
                        (demand, selected_strategy, passes)
                    }
                    Some(FormulaPlaneTopologyStrategy::ExactInMemoryRuns) => {
                        let (demand, passes) = build_demand_closure_in_memory_runs(
                            roots,
                            producer_results,
                            consumer_reads,
                            |units| {
                                Self::resource_loop_checkpoint(
                                    &mut self.active_resource_ledger,
                                    units,
                                )
                            },
                        )?;
                        (demand, selected_strategy, passes)
                    }
                    #[cfg(not(target_arch = "wasm32"))]
                    Some(FormulaPlaneTopologyStrategy::ExactNativeScratch) => {
                        let request_id = self
                            .active_evaluation_resource_request
                            .as_ref()
                            .map_or(0, |stats| stats.request_id);
                        match NativeTopologyScratch::create(request_id) {
                            Ok(mut native) => match build_demand_closure_native(
                                roots.clone(),
                                producer_results,
                                consumer_reads,
                                native.file.as_mut().expect("native scratch file"),
                                native
                                    .auxiliary_file
                                    .as_mut()
                                    .expect("native auxiliary scratch file"),
                                |units| {
                                    Self::resource_loop_checkpoint(
                                        &mut self.active_resource_ledger,
                                        units,
                                    )
                                },
                            ) {
                                Ok((demand, passes, bytes)) => {
                                    native_disk_bytes = bytes;
                                    (demand, selected_strategy, passes)
                                }
                                Err(NativeExactDemandError::Work(error)) => return Err(error),
                                Err(NativeExactDemandError::Io(_)) => {
                                    let (demand, passes) = build_demand_closure_repeated_passes(
                                        roots,
                                        producer_results,
                                        consumer_reads,
                                        |units| {
                                            Self::resource_loop_checkpoint(
                                                &mut self.active_resource_ledger,
                                                units,
                                            )
                                        },
                                    )?;
                                    (
                                        demand,
                                        Some(FormulaPlaneTopologyStrategy::ExactRepeatedPasses),
                                        passes,
                                    )
                                }
                            },
                            Err(_) => {
                                let (demand, passes) = build_demand_closure_repeated_passes(
                                    roots,
                                    producer_results,
                                    consumer_reads,
                                    |units| {
                                        Self::resource_loop_checkpoint(
                                            &mut self.active_resource_ledger,
                                            units,
                                        )
                                    },
                                )?;
                                (
                                    demand,
                                    Some(FormulaPlaneTopologyStrategy::ExactRepeatedPasses),
                                    passes,
                                )
                            }
                        }
                    }
                    Some(FormulaPlaneTopologyStrategy::ExactRepeatedPasses) => {
                        let (demand, passes) = build_demand_closure_repeated_passes(
                            roots,
                            producer_results,
                            consumer_reads,
                            |units| {
                                Self::resource_loop_checkpoint(
                                    &mut self.active_resource_ledger,
                                    units,
                                )
                            },
                        )?;
                        (demand, selected_strategy, passes)
                    }
                    _ => unreachable!("exact demand strategy selection is exhaustive"),
                };
                let strategy_memory = match actual_strategy {
                    Some(FormulaPlaneTopologyStrategy::ExactPagedIndexed) => {
                        scratch_estimates.paged.saturating_sub(closure_base)
                    }
                    Some(FormulaPlaneTopologyStrategy::ExactInMemoryRuns) => {
                        scratch_estimates.runs.saturating_sub(closure_base)
                    }
                    Some(FormulaPlaneTopologyStrategy::ExactNativeScratch) => {
                        scratch_estimates.native.saturating_sub(closure_base)
                    }
                    Some(FormulaPlaneTopologyStrategy::ExactRepeatedPasses) => {
                        scratch_estimates.repeated.saturating_sub(closure_base)
                    }
                    None => 0,
                    _ => 0,
                };
                let actual_scratch = demand
                    .estimated_memory_bytes()
                    .saturating_add(strategy_memory);
                if actual_scratch > demand_scratch_reserved {
                    if let Some(ledger) = self.active_resource_ledger.as_mut() {
                        ledger
                            .reserve_schedule_discovery(
                                actual_scratch.saturating_sub(demand_scratch_reserved),
                            )
                            .map_err(crate::engine::ResourceLedgerError::into_excel_error)?;
                    }
                } else if actual_scratch < demand_scratch_reserved
                    && let Some(ledger) = self.active_resource_ledger.as_mut()
                {
                    ledger
                        .release_scratch(demand_scratch_reserved - actual_scratch)
                        .map_err(crate::engine::ResourceLedgerError::into_excel_error)?;
                }
                demand_scratch_reserved = actual_scratch;
                if let Some(strategy) = actual_strategy
                    && let Some(stats) = self.active_evaluation_resource_request.as_mut()
                {
                    if strategy.severity() > stats.topology.strategy.severity() {
                        stats.topology.strategy = strategy;
                    }
                    stats.topology.exact_pass_count = stats
                        .topology
                        .exact_pass_count
                        .saturating_add(passes.max(1));
                    stats.topology.native_topology_disk_bytes = stats
                        .topology
                        .native_topology_disk_bytes
                        .saturating_add(native_disk_bytes);
                }
                Some(demand)
            } else {
                None
            };

            let dirty_legacy = self.graph.get_evaluation_vertices();
            let dirty_legacy_set = dirty_legacy.iter().copied().collect::<FxHashSet<_>>();
            let island_target_demand = target_roots.map(|roots| {
                use crate::engine::target_preparation::TargetProducer;
                let graph_roots = roots
                    .iter()
                    .filter_map(|root| match *root {
                        TargetProducer::Legacy(vertex) | TargetProducer::Symbol(vertex) => {
                            Some(vertex)
                        }
                        TargetProducer::Span { .. } | TargetProducer::ValueOnly(_) => None,
                    })
                    .collect::<Vec<_>>();
                self.build_demand_subgraph(&graph_roots)
                    .0
                    .into_iter()
                    .collect::<FxHashSet<_>>()
            });
            let mut island_plan = island.clone();
            island_plan.dirty_vertices = island_plan
                .membership
                .iter()
                .copied()
                .filter(|vertex| dirty_legacy_set.contains(vertex))
                .filter(|vertex| {
                    island_target_demand
                        .as_ref()
                        .is_none_or(|demand| demand.contains(vertex))
                })
                .collect();
            let mut work = Vec::new();
            let mut scheduled_legacy_vertices = Vec::new();
            let demanded_dirty = |producer: FormulaProducerId,
                                  dirty: ProducerDirtyDomain|
             -> Option<ProducerDirtyDomain> {
                let Some(demand) = demand.as_ref() else {
                    return Some(dirty);
                };
                let result = producer_results.producer_result_region(producer)?;
                dirty.intersect_demanded(result, demand.regions(producer))
            };
            for (span_ref, region) in formula_dirty.span_regions() {
                let producer = FormulaProducerId::Span(span_ref.id);
                if span_refs_by_id.get(&span_ref.id) == Some(&span_ref)
                    && let Some(dirty) =
                        demanded_dirty(producer, ProducerDirtyDomain::Regions(vec![region]))
                {
                    work.push(FormulaProducerWork { producer, dirty });
                }
            }
            for span_ref in formula_dirty
                .whole_spans()
                .chain(retry_whole_spans.iter().copied())
            {
                let producer = FormulaProducerId::Span(span_ref.id);
                if span_refs_by_id.get(&span_ref.id) == Some(&span_ref)
                    && let Some(dirty) = demanded_dirty(producer, ProducerDirtyDomain::Whole)
                {
                    work.push(FormulaProducerWork { producer, dirty });
                }
            }
            for vertex in dirty_legacy {
                let producer = FormulaProducerId::Legacy(vertex);
                if producer_results.producer_result_region(producer).is_some()
                    && let Some(dirty) = demanded_dirty(producer, ProducerDirtyDomain::Whole)
                {
                    scheduled_legacy_vertices.push(vertex);
                    work.push(FormulaProducerWork { producer, dirty });
                }
            }

            let pending_changed_regions = formula_dirty
                .regions()
                .chain(formula_dirty.span_regions().map(|(_, region)| region))
                .collect::<Vec<_>>();
            if include_dirty_regions && !pending_changed_regions.is_empty() {
                use crate::formula_plane::producer::compute_dirty_closure_checked;
                let closure = compute_dirty_closure_checked(
                    consumer_reads,
                    pending_changed_regions.iter().copied(),
                    |producer| producer_results.producer_result_region(producer),
                    |units| Self::resource_loop_checkpoint(&mut self.active_resource_ledger, units),
                )?;
                if closure.incomplete {
                    // The fixed-point guard discards partial closure output. Complete conservatively
                    // in the same topology/schedule path; it must not become a new demotion route.
                    work.clear();
                    scheduled_legacy_vertices.clear();
                    if let Some(demand) = demand.as_ref() {
                        for producer in demand.producers() {
                            if let Some(dirty) =
                                demanded_dirty(producer, ProducerDirtyDomain::Whole)
                            {
                                if let FormulaProducerId::Legacy(vertex) = producer {
                                    scheduled_legacy_vertices.push(vertex);
                                }
                                work.push(FormulaProducerWork { producer, dirty });
                            }
                        }
                    } else {
                        work.extend(span_refs_by_id.keys().copied().map(|id| {
                            FormulaProducerWork {
                                producer: FormulaProducerId::Span(id),
                                dirty: ProducerDirtyDomain::Whole,
                            }
                        }));
                        for vertex in self.graph.formula_vertices() {
                            let producer = FormulaProducerId::Legacy(vertex);
                            if producer_results.producer_result_region(producer).is_some() {
                                scheduled_legacy_vertices.push(vertex);
                                work.push(FormulaProducerWork {
                                    producer,
                                    dirty: ProducerDirtyDomain::Whole,
                                });
                            }
                        }
                    }
                    if let Some(stats) = self.active_evaluation_resource_request.as_mut() {
                        stats.topology.incomplete_reason =
                            Some(crate::engine::EvaluationIncompleteReason::DirtyClosureWork);
                    }
                } else if let Some(demand) = demand.as_ref() {
                    for item in closure.work {
                        if let Some(dirty) = demanded_dirty(item.producer, item.dirty) {
                            work.push(FormulaProducerWork {
                                producer: item.producer,
                                dirty,
                            });
                        }
                    }
                } else {
                    work.extend(closure.work);
                }
                if !closure.incomplete && !closure.fallbacks.is_empty() {
                    let mut already_whole = work
                        .iter()
                        .filter_map(|item| match (item.producer, &item.dirty) {
                            (FormulaProducerId::Span(id), ProducerDirtyDomain::Whole) => Some(id),
                            _ => None,
                        })
                        .collect::<rustc_hash::FxHashSet<_>>();
                    for fallback in closure.fallbacks {
                        if let FormulaProducerId::Span(id) = fallback.consumer
                            && already_whole.insert(id)
                        {
                            work.push(FormulaProducerWork {
                                producer: FormulaProducerId::Span(id),
                                dirty: ProducerDirtyDomain::Whole,
                            });
                        }
                    }
                }
            }

            let owned_dirty_events = if let Some(demand) = demand.as_ref() {
                use crate::formula_plane::producer::compute_dirty_closure_checked;
                let mut owned = Vec::new();
                for (index, event) in formula_dirty.events() {
                    let (seed_regions, initial) = match event {
                        FormulaDirtyEventSnapshot::Region(region) => (vec![region], None),
                        FormulaDirtyEventSnapshot::SpanRegion { span_ref, region } => (
                            vec![region],
                            Some(FormulaProducerWork {
                                producer: FormulaProducerId::Span(span_ref.id),
                                dirty: ProducerDirtyDomain::Regions(vec![region]),
                            }),
                        ),
                        FormulaDirtyEventSnapshot::WholeSpan(span_ref) => {
                            let producer = FormulaProducerId::Span(span_ref.id);
                            let Some(result) = producer_results.producer_result_region(producer)
                            else {
                                continue;
                            };
                            (
                                vec![result],
                                Some(FormulaProducerWork {
                                    producer,
                                    dirty: ProducerDirtyDomain::Whole,
                                }),
                            )
                        }
                    };
                    let closure = compute_dirty_closure_checked(
                        consumer_reads,
                        seed_regions,
                        |producer| producer_results.producer_result_region(producer),
                        |units| {
                            Self::resource_loop_checkpoint(&mut self.active_resource_ledger, units)
                        },
                    )?;
                    if closure.incomplete || !closure.fallbacks.is_empty() {
                        continue;
                    }
                    let fully_demanded =
                        initial
                            .into_iter()
                            .chain(closure.work.into_iter())
                            .all(|item| {
                                let Some(result) =
                                    producer_results.producer_result_region(item.producer)
                                else {
                                    return false;
                                };
                                item.dirty
                                    .result_regions(result)
                                    .into_iter()
                                    .all(|dirty_region| {
                                        demand
                                            .regions(item.producer)
                                            .iter()
                                            .any(|demanded| demanded.contains_region(dirty_region))
                                    })
                            });
                    if fully_demanded {
                        owned.push(index);
                    }
                }
                owned
            } else {
                (0..formula_dirty.len()).collect()
            };

            Self::resource_loop_checkpoint(&mut self.active_resource_ledger, work.len() as u64)?;
            let producer_count = producer_results.len();
            let dirty_units = work.iter().fold(0usize, |total, item| {
                total.saturating_add(match &item.dirty {
                    ProducerDirtyDomain::Whole => 0,
                    ProducerDirtyDomain::Cells(cells) => cells.len(),
                    ProducerDirtyDomain::Regions(regions) => regions.len(),
                })
            });
            let work_bytes = work
                .len()
                .saturating_mul(std::mem::size_of::<FormulaProducerWork>() + 64)
                .saturating_add(
                    dirty_units.saturating_mul(std::mem::size_of::<Region>().max(
                        std::mem::size_of::<crate::formula_plane::region_index::RegionKey>(),
                    )),
                ) as u64;
            let binding_bytes =
                estimated_span_bindings_bytes(span_refs_by_id).unwrap_or(usize::MAX) as u64;
            let schedule_bytes = work_bytes
                .saturating_mul(4)
                .saturating_add((producer_count as u64).saturating_mul(192))
                .saturating_add(binding_bytes)
                .saturating_add(1024);
            let maximum_edges =
                producer_count.saturating_mul(producer_count.saturating_sub(1)) as u64;
            // Producer/read indexes are either retained by the cache or covered by the live index
            // preflight reservation. Strategy reservations therefore cover only additional scheduling
            // structures and must not charge those indexes a second time.
            let paged_bytes = schedule_bytes
                .saturating_add(maximum_edges.saturating_mul(160))
                .saturating_add(16 * 1024);
            let runs_bytes = schedule_bytes
                .saturating_add(maximum_edges.saturating_mul(48))
                .saturating_add(8192);
            let native_bytes = schedule_bytes
                .saturating_add((producer_count as u64).saturating_mul(128))
                .saturating_add(2048);
            let repeated_bytes = schedule_bytes
                .saturating_add((producer_count as u64).saturating_mul(96))
                .saturating_add(1024);
            let native_allowed = self
                .active_resource_ledger
                .as_ref()
                .and_then(ResourceLedger::disk_scratch_policy)
                == Some(crate::engine::DiskScratchPolicy::NativeTemporary)
                && !cfg!(target_arch = "wasm32");

            let cached_schedule_bytes = schedule_bytes
                .saturating_add(
                    cached_topology
                        .map_or(0, |topology| topology.stats.relationships as u64)
                        .saturating_mul(160),
                )
                .saturating_add(1024);
            let use_cached_schedule = cached_topology.is_some()
                && self.can_reserve_topology_scratch(cached_schedule_bytes);
            let (selected_strategy, scratch) = if use_cached_schedule {
                (None, cached_schedule_bytes)
            } else if self.can_reserve_topology_scratch(paged_bytes) {
                (
                    Some(FormulaPlaneTopologyStrategy::ExactPagedIndexed),
                    paged_bytes,
                )
            } else if self.can_reserve_topology_scratch(runs_bytes) {
                (
                    Some(FormulaPlaneTopologyStrategy::ExactInMemoryRuns),
                    runs_bytes,
                )
            } else if native_allowed && self.can_reserve_topology_scratch(native_bytes) {
                (
                    Some(FormulaPlaneTopologyStrategy::ExactNativeScratch),
                    native_bytes,
                )
            } else if self.can_reserve_topology_scratch(repeated_bytes) {
                (
                    Some(FormulaPlaneTopologyStrategy::ExactRepeatedPasses),
                    repeated_bytes,
                )
            } else {
                if let Some(ledger) = self.active_resource_ledger.as_mut() {
                    ledger
                        .reserve_schedule_discovery(repeated_bytes)
                        .map_err(crate::engine::ResourceLedgerError::into_excel_error)?;
                }
                unreachable!("failed scratch reservation must return a typed error")
            };
            if let Some(ledger) = self.active_resource_ledger.as_mut() {
                ledger
                    .reserve_schedule_discovery(scratch)
                    .map_err(crate::engine::ResourceLedgerError::into_excel_error)?;
            }
            let request_id = self
                .active_evaluation_resource_request
                .as_ref()
                .map_or(0, |stats| stats.request_id);
            let build_result = (|| -> Result<_, ExcelError> {
                let (schedule, actual_strategy, passes, native_disk_bytes) =
                    match (cached_topology, selected_strategy) {
                        (Some(topology), None) => (
                            schedule_dirty_work(work, producer_results, topology, 256),
                            None,
                            0,
                            0,
                        ),
                        (_, Some(FormulaPlaneTopologyStrategy::ExactPagedIndexed)) => {
                            let (schedule, passes) = schedule_dirty_work_paged_hybrid(
                                work,
                                producer_results,
                                consumer_reads,
                                partial_topology.filter(|_| reuse_partial_topology),
                                256,
                                |units| {
                                    Self::resource_loop_checkpoint(
                                        &mut self.active_resource_ledger,
                                        units,
                                    )
                                },
                            )?;
                            (schedule, selected_strategy, passes.max(1), 0)
                        }
                        (_, Some(FormulaPlaneTopologyStrategy::ExactInMemoryRuns)) => {
                            let (schedule, passes) = schedule_dirty_work_in_memory_runs(
                                work,
                                producer_results,
                                consumer_reads,
                                256,
                                |units| {
                                    Self::resource_loop_checkpoint(
                                        &mut self.active_resource_ledger,
                                        units,
                                    )
                                },
                            )?;
                            (schedule, selected_strategy, passes.max(1), 0)
                        }
                        #[cfg(not(target_arch = "wasm32"))]
                        (_, Some(FormulaPlaneTopologyStrategy::ExactNativeScratch)) => {
                            let native = NativeTopologyScratch::create(request_id);
                            if let Ok(mut native) = native {
                                match schedule_dirty_work_native(
                                    work.clone(),
                                    producer_results,
                                    consumer_reads,
                                    256,
                                    native.file.as_mut().expect("native scratch file"),
                                    |units| {
                                        Self::resource_loop_checkpoint(
                                            &mut self.active_resource_ledger,
                                            units,
                                        )
                                    },
                                ) {
                                    Ok((schedule, passes, topology_bytes)) => (
                                        schedule,
                                        Some(FormulaPlaneTopologyStrategy::ExactNativeScratch),
                                        passes.max(1),
                                        topology_bytes,
                                    ),
                                    Err(NativeExactScheduleError::Work(error)) => {
                                        return Err(error);
                                    }
                                    Err(NativeExactScheduleError::Io(_)) => {
                                        let (schedule, passes) =
                                            schedule_dirty_work_repeated_passes(
                                                work,
                                                producer_results,
                                                consumer_reads,
                                                256,
                                                |units| {
                                                    Self::resource_loop_checkpoint(
                                                        &mut self.active_resource_ledger,
                                                        units,
                                                    )
                                                },
                                            )?;
                                        (
                                            schedule,
                                            Some(FormulaPlaneTopologyStrategy::ExactRepeatedPasses),
                                            passes.max(1),
                                            0,
                                        )
                                    }
                                }
                            } else {
                                let (schedule, passes) = schedule_dirty_work_repeated_passes(
                                    work,
                                    producer_results,
                                    consumer_reads,
                                    256,
                                    |units| {
                                        Self::resource_loop_checkpoint(
                                            &mut self.active_resource_ledger,
                                            units,
                                        )
                                    },
                                )?;
                                (
                                    schedule,
                                    Some(FormulaPlaneTopologyStrategy::ExactRepeatedPasses),
                                    passes.max(1),
                                    0,
                                )
                            }
                        }
                        (_, Some(FormulaPlaneTopologyStrategy::ExactRepeatedPasses)) => {
                            let (schedule, passes) = schedule_dirty_work_repeated_passes(
                                work,
                                producer_results,
                                consumer_reads,
                                256,
                                |units| {
                                    Self::resource_loop_checkpoint(
                                        &mut self.active_resource_ledger,
                                        units,
                                    )
                                },
                            )?;
                            (schedule, selected_strategy, passes.max(1), 0)
                        }
                        _ => unreachable!(
                            "topology cache and exact strategy selection are exhaustive"
                        ),
                    };
                Ok((
                    schedule,
                    actual_strategy,
                    passes,
                    native_disk_bytes,
                    span_refs_by_id.clone(),
                ))
            })();
            let release_result = self
                .active_resource_ledger
                .as_mut()
                .map_or(Ok(()), |ledger| ledger.release_scratch(scratch))
                .map_err(crate::engine::ResourceLedgerError::into_excel_error);
            let (schedule, exact_strategy, pass_count, native_disk_bytes, result_span_refs) =
                match build_result {
                    Ok(output) => {
                        release_result?;
                        output
                    }
                    Err(error) => {
                        let _ = release_result;
                        return Err(error);
                    }
                };
            if let Some(strategy) = exact_strategy
                && let Some(stats) = self.active_evaluation_resource_request.as_mut()
            {
                if strategy.severity() > stats.topology.strategy.severity() {
                    stats.topology.strategy = strategy;
                }
                stats.topology.exact_pass_count = pass_count;
                stats.topology.native_topology_disk_bytes = stats
                    .topology
                    .native_topology_disk_bytes
                    .saturating_add(native_disk_bytes);
            }
            Ok((
                schedule,
                result_span_refs,
                plane_epoch,
                scheduled_legacy_vertices,
                owned_dirty_events,
                island_plan,
            ))
        })();
        let scratch_release_result = self
            .active_resource_ledger
            .as_mut()
            .map_or(Ok(()), |ledger| {
                ledger
                    .release_scratch(index_scratch_reserved.saturating_add(demand_scratch_reserved))
            })
            .map_err(crate::engine::ResourceLedgerError::into_excel_error);
        match schedule_result {
            Ok(output) => {
                scratch_release_result?;
                Ok(output)
            }
            Err(error) => {
                let _ = scratch_release_result;
                Err(error)
            }
        }
    }
}

impl<R> Engine<R>
where
    R: EvaluationContext,
{
    fn shared_range_to_region_pattern(
        &self,
        range: &crate::reference::SharedRangeRef<'static>,
    ) -> Result<Option<Region>, ExcelError> {
        use crate::reference::SharedSheetLocator;
        let sheet_id = match range.sheet {
            SharedSheetLocator::Id(id) => id,
            SharedSheetLocator::Current => self.graph.default_sheet_id(),
            SharedSheetLocator::Name(_) => return Ok(None),
        };
        match (
            range.start_row,
            range.end_row,
            range.start_col,
            range.end_col,
        ) {
            (Some(sr), Some(er), Some(sc), Some(ec)) => Ok(Some(Region::rect(
                sheet_id, sr.index, er.index, sc.index, ec.index,
            ))),
            (None, None, Some(sc), Some(ec)) if sc.index == ec.index => {
                Ok(Some(Region::whole_col(sheet_id, sc.index)))
            }
            (Some(sr), Some(er), None, None) if sr.index == er.index => {
                Ok(Some(Region::whole_row(sheet_id, sr.index)))
            }
            _ => Ok(None),
        }
    }

    /// Evaluate all dirty/volatile vertices
    pub fn evaluate_all(&mut self) -> Result<EvalResult, ExcelError> {
        self.observe_evaluation_resource_request(EvaluationRequestKind::Full, |engine| {
            engine.evaluate_all_unobserved()
        })
    }

    fn evaluate_all_unobserved(&mut self) -> Result<EvalResult, ExcelError> {
        debug_assert!(
            !self.graph.deferred_dirty_active(),
            "deferred-dirty scope leaked into evaluate_all: a begin_deferred_dirty \
             was not balanced by end_deferred_dirty"
        );
        self.observe_function_semantic_epoch()?;
        self.lookup_index_cache.reset_counters();
        let _source_cache = self.source_cache_session();
        self.validate_deterministic_mode()?;
        if self.config.defer_graph_building {
            // Build graph for all staged formulas before evaluating
            self.build_graph_all()?;
        }
        self.evaluate_all_coordinator()
    }

    /// Central FormulaPlane-aware coordinator for `evaluate_all`. In
    /// `AuthoritativeExperimental` mode every call enters the FormulaPlane
    /// coordinator; the coordinator itself composes with private legacy
    /// primitives for legacy-only work.
    fn evaluate_all_coordinator(&mut self) -> Result<EvalResult, ExcelError> {
        self.begin_evaluation_request();
        if self.config.formula_plane_mode == FormulaPlaneMode::AuthoritativeExperimental {
            return self.evaluate_authoritative_formula_plane_all();
        }
        self.evaluate_all_legacy_impl()
    }

    /// Walk a schedule's units in condensation order: stamp each cyclic SCC
    /// at its position and evaluate each layer (parallel when enabled).
    ///
    /// Returns `(computed_vertices, cycle_count)` where `cycle_count` is the
    /// number of Cycle units walked (the former `schedule.cycles.len()`).
    fn legacy_pass_run_units(
        &mut self,
        schedule: &crate::engine::scheduler::Schedule,
    ) -> Result<(usize, usize), ExcelError> {
        let mut computed_vertices = 0;
        let mut cycle_count = 0;
        for &unit in &schedule.units {
            match unit {
                ScheduleUnit::Cycle(i) => {
                    if self.handle_cycle_unit(schedule.unit_cycle(i), None, None, None)? > 0 {
                        cycle_count += 1;
                    }
                }
                ScheduleUnit::Layer(i) => {
                    let layer = schedule.unit_layer(i);
                    if self.thread_pool.is_some() && layer.vertices.len() > 1 {
                        computed_vertices += self.evaluate_layer_parallel(layer)?;
                    } else {
                        computed_vertices += self.evaluate_layer_sequential(layer)?;
                    }
                }
            }
        }
        Ok((computed_vertices, cycle_count))
    }

    /// Execute a proven span-disconnected legacy island without beginning or
    /// finalising an evaluation request. The FormulaPlane coordinator retains
    /// sole ownership of the dirty lease, volatile redirty, acknowledgement,
    /// clock sample, and recalc-epoch advance.
    fn evaluate_legacy_island_non_finalizing(
        &mut self,
        vertices: &[VertexId],
        mut delta: Option<&mut DeltaCollector>,
    ) -> Result<(usize, usize), ExcelError> {
        if vertices.is_empty() {
            return Ok((0, 0));
        }
        let (schedule, _, _) = self.create_evaluation_schedule(vertices)?;
        let mut computed = 0usize;
        let mut cycles = 0usize;
        for &unit in &schedule.units {
            self.cancellation_checkpoint("Evaluation cancelled during legacy island")?;
            match unit {
                ScheduleUnit::Cycle(index) => {
                    if self.handle_cycle_unit(
                        schedule.unit_cycle(index),
                        delta.as_deref_mut(),
                        None,
                        None,
                    )? > 0
                    {
                        cycles = cycles.saturating_add(1);
                    }
                }
                ScheduleUnit::Layer(index) => {
                    let layer = schedule.unit_layer(index);
                    let evaluated = if let Some(delta) = delta.as_deref_mut() {
                        if self.thread_pool.is_some() && layer.vertices.len() > 1 {
                            self.evaluate_layer_parallel_with_delta(layer, delta)?
                        } else {
                            self.evaluate_layer_sequential_with_delta(layer, delta)?
                        }
                    } else if self.thread_pool.is_some() && layer.vertices.len() > 1 {
                        self.evaluate_layer_parallel(layer)?
                    } else {
                        self.evaluate_layer_sequential(layer)?
                    };
                    computed = computed.saturating_add(evaluated);
                }
            }
        }
        self.graph.clear_dirty_flags(vertices);
        Ok((computed, cycles))
    }

    /// Legacy `evaluate_all` body, reachable from the FormulaPlane coordinator
    /// when no active spans exist or FormulaPlane authority is not in
    /// `AuthoritativeExperimental` mode. This is now an internal primitive; it
    /// must not be invoked directly from public APIs.
    ///
    /// Does NOT call `begin_evaluation_request` (cycle-telemetry reset +
    /// per-recalc clock sample): the FormulaPlane coordinator composes this
    /// primitive *after* `evaluate_legacy_cycle_prepass` may have accumulated
    /// counts (G8 demotion path), and both sub-passes belong to ONE request /
    /// one clock sample; request begin happens at the public entry points /
    /// coordinators instead.
    fn evaluate_all_legacy_impl(&mut self) -> Result<EvalResult, ExcelError> {
        self.reset_virtual_dep_telemetry_if_disabled();
        #[cfg(feature = "tracing")]
        let _span_eval = tracing::info_span!("evaluate_all").entered();
        let start = crate::instant::FzInstant::now();
        let mut computed_vertices = 0;
        let mut cycle_errors = 0;
        let mut replan_iterations = 0;
        const MAX_REPLAN: usize = 5;
        let mut telemetry = self
            .config
            .enable_virtual_dep_telemetry
            .then(|| self.start_virtual_dep_telemetry());

        loop {
            let to_evaluate = self.graph.get_evaluation_vertices();
            if to_evaluate.is_empty() {
                if let Some(t) = telemetry.as_mut()
                    && t.bailout_reason.is_none()
                {
                    t.bailout_reason = Some("no_work");
                }
                break;
            }

            let (schedule, old_vdeps, meta) = self.create_evaluation_schedule(&to_evaluate)?;
            if let Some(t) = telemetry.as_mut() {
                Self::accumulate_schedule_meta(t, &meta);
            }

            let (pass_computed, pass_cycles) = self.legacy_pass_run_units(&schedule)?;
            computed_vertices += pass_computed;
            cycle_errors += pass_cycles;

            // Check if dynamic dependencies changed
            let changed_vertices = self.changed_virtual_dep_vertices(&to_evaluate, &old_vdeps);
            if let Some(t) = telemetry.as_mut() {
                t.changed_vdeps_total += changed_vertices.len();
            }

            self.resource_checkpoint(0)?;
            self.graph.clear_dirty_flags(&to_evaluate);
            for v in &changed_vertices {
                self.graph.set_dirty(*v, true);
            }

            if changed_vertices.is_empty() {
                if let Some(t) = telemetry.as_mut() {
                    t.bailout_reason = Some("converged");
                }
                break;
            }
            if replan_iterations >= MAX_REPLAN {
                if let Some(mut t) = telemetry.take() {
                    t.bailout_reason = Some("max_replan");
                    t.replan_iterations = replan_iterations;
                    self.last_virtual_dep_telemetry = t;
                }
                return Err(
                    self.replan_exhausted_error(MAX_REPLAN, "dynamic dependency evaluation")
                );
            }

            replan_iterations += 1;
        }

        if let Some(mut t) = telemetry {
            t.replan_iterations = replan_iterations;
            self.last_virtual_dep_telemetry = t;
        }

        // Re-dirty volatile vertices for the next evaluation cycle
        self.redirty_for_next_recalc();

        // Advance recalc epoch after a full evaluation pass finishes
        self.recalc_epoch = self.recalc_epoch.wrapping_add(1);

        Ok(EvalResult {
            computed_vertices,
            cycle_errors,
            elapsed: start.elapsed(),
        })
    }

    pub fn evaluate_all_with_target_delta(
        &mut self,
    ) -> Result<(EvalResult, crate::engine::TargetEvalDelta), ExcelError> {
        self.observe_evaluation_resource_request(EvaluationRequestKind::FullWithDelta, |engine| {
            engine.observe_function_semantic_epoch()?;
            let mut collector = DeltaCollector::new(DeltaMode::Cells);
            let result = engine.evaluate_all_with_delta_collector(&mut collector)?;
            Ok((result, collector.finish_target()))
        })
    }

    pub fn evaluate_all_with_delta(&mut self) -> Result<(EvalResult, EvalDelta), ExcelError> {
        self.evaluate_all_with_delta_policy(EvalDeltaCompatibilityPolicy::Unlimited)
    }

    pub fn evaluate_all_with_delta_policy(
        &mut self,
        policy: EvalDeltaCompatibilityPolicy,
    ) -> Result<(EvalResult, EvalDelta), ExcelError> {
        self.observe_evaluation_resource_request(EvaluationRequestKind::FullWithDelta, |engine| {
            engine.observe_function_semantic_epoch()?;
            let mut collector = DeltaCollector::new(DeltaMode::Cells);
            let result = engine.evaluate_all_with_delta_collector(&mut collector)?;
            Ok((result, collector.finish_with_policy(policy)?))
        })
    }

    fn evaluate_all_with_delta_collector(
        &mut self,
        delta: &mut DeltaCollector,
    ) -> Result<EvalResult, ExcelError> {
        self.begin_evaluation_request();
        let _source_cache = self.source_cache_session();
        if self.config.defer_graph_building {
            self.build_graph_all()?;
        }
        if self.graph.formula_authority().active_span_count() > 0 {
            return self.evaluate_authoritative_formula_plane(None, Some(delta));
        }
        self.reset_virtual_dep_telemetry_if_disabled();
        #[cfg(feature = "tracing")]
        let _span_eval = tracing::info_span!("evaluate_all_with_delta").entered();
        let start = crate::instant::FzInstant::now();
        let mut computed_vertices = 0;
        let mut cycle_errors = 0;

        let mut replan_iterations = 0;
        const MAX_REPLAN: usize = 5;
        let mut telemetry = self
            .config
            .enable_virtual_dep_telemetry
            .then(|| self.start_virtual_dep_telemetry());

        loop {
            let to_evaluate = self.graph.get_evaluation_vertices();
            if to_evaluate.is_empty() {
                if let Some(t) = telemetry.as_mut()
                    && t.bailout_reason.is_none()
                {
                    t.bailout_reason = Some("no_work");
                }
                break;
            }

            let (schedule, old_vdeps, meta) = self.create_evaluation_schedule(&to_evaluate)?;
            if let Some(t) = telemetry.as_mut() {
                Self::accumulate_schedule_meta(t, &meta);
            }

            for &unit in &schedule.units {
                match unit {
                    ScheduleUnit::Cycle(i) => {
                        if self.handle_cycle_unit(
                            schedule.unit_cycle(i),
                            Some(delta),
                            None,
                            None,
                        )? > 0
                        {
                            cycle_errors += 1;
                        }
                    }
                    ScheduleUnit::Layer(i) => {
                        let layer = schedule.unit_layer(i);
                        if self.thread_pool.is_some() && layer.vertices.len() > 1 {
                            computed_vertices +=
                                self.evaluate_layer_parallel_with_delta(layer, delta)?;
                        } else {
                            computed_vertices +=
                                self.evaluate_layer_sequential_with_delta(layer, delta)?;
                        }
                    }
                }
            }

            let changed_vertices = self.changed_virtual_dep_vertices(&to_evaluate, &old_vdeps);
            if let Some(t) = telemetry.as_mut() {
                t.changed_vdeps_total += changed_vertices.len();
            }
            self.resource_checkpoint(0)?;
            self.graph.clear_dirty_flags(&to_evaluate);
            for v in &changed_vertices {
                self.graph.set_dirty(*v, true);
            }

            if changed_vertices.is_empty() {
                if let Some(t) = telemetry.as_mut() {
                    t.bailout_reason = Some("converged");
                }
                break;
            }
            if replan_iterations >= MAX_REPLAN {
                if let Some(mut t) = telemetry.take() {
                    t.bailout_reason = Some("max_replan");
                    t.replan_iterations = replan_iterations;
                    self.last_virtual_dep_telemetry = t;
                }
                return Err(
                    self.replan_exhausted_error(MAX_REPLAN, "dynamic dependency evaluation")
                );
            }
            replan_iterations += 1;
        }

        if let Some(mut t) = telemetry {
            t.replan_iterations = replan_iterations;
            self.last_virtual_dep_telemetry = t;
        }

        self.redirty_for_next_recalc();
        self.recalc_epoch = self.recalc_epoch.wrapping_add(1);

        Ok(EvalResult {
            computed_vertices,
            cycle_errors,
            elapsed: start.elapsed(),
        })
    }

    /// Convenience: demand-driven evaluation of a single cell by sheet name and row/col.
    ///
    /// This will evaluate only the minimal set of dirty / volatile precedents required
    /// to bring the target cell up-to-date (as if a user asked for that single value),
    /// rather than scheduling a full workbook recalc. If the cell is already clean and
    /// non-volatile, no vertices will be recomputed.
    ///
    /// Returns the (possibly newly computed) value stored for the cell afterwards.
    /// Empty cells return None. Errors are surfaced via the Result type.
    pub fn evaluate_cell(
        &mut self,
        sheet: &str,
        row: u32,
        col: u32,
    ) -> Result<Option<LiteralValue>, ExcelError> {
        self.observe_evaluation_resource_request(EvaluationRequestKind::Cell, |engine| {
            engine.evaluate_cell_unobserved(sheet, row, col)
        })
    }

    fn evaluate_cell_unobserved(
        &mut self,
        sheet: &str,
        row: u32,
        col: u32,
    ) -> Result<Option<LiteralValue>, ExcelError> {
        if row == 0 || col == 0 {
            return Err(ExcelError::new(ExcelErrorKind::Ref)
                .with_message("Row and column must be >= 1".to_string()));
        }

        let result = self.evaluate_cells(&[(sheet, row, col)])?;

        match result.len() {
            0 => Ok(None),
            1 => {
                let v = result.into_iter().next().unwrap();
                Ok(v)
            }
            _ => unreachable!("evaluate_cells returned unexpected length"),
        }
    }

    /// Convenience: demand-driven evaluation of multiple cells; accepts a slice of
    /// (sheet, row, col) triples. The union of required dirty / volatile precedents
    /// is computed once and evaluated, which is typically faster than calling
    /// `evaluate_cell` repeatedly for a related set of targets.
    ///
    /// Returns the resulting values for each requested target in the same order.
    pub fn evaluate_cells(
        &mut self,
        targets: &[(&str, u32, u32)],
    ) -> Result<Vec<Option<LiteralValue>>, ExcelError> {
        self.observe_evaluation_resource_request(EvaluationRequestKind::Cells, |engine| {
            engine.evaluate_cells_unobserved(targets)
        })
    }

    fn evaluate_cells_unobserved(
        &mut self,
        targets: &[(&str, u32, u32)],
    ) -> Result<Vec<Option<LiteralValue>>, ExcelError> {
        self.observe_function_semantic_epoch()?;
        debug_assert!(
            !self.graph.deferred_dirty_active(),
            "deferred-dirty scope leaked into evaluate_cells: a begin_deferred_dirty \
             was not balanced by end_deferred_dirty"
        );
        self.validate_deterministic_mode()?;
        if targets.is_empty() {
            return Ok(Vec::new());
        }
        let typed_targets = self.legacy_coordinate_targets(targets);
        self.evaluate_mixed_targets(&typed_targets, None)?;
        Ok(targets
            .iter()
            .map(|(s, r, c)| self.get_cell_value(s, *r, *c))
            .collect())
    }

    pub fn evaluate_cells_cancellable(
        &mut self,
        targets: &[(&str, u32, u32)],
        cancel: crate::engine::CancelToken,
    ) -> Result<Vec<Option<LiteralValue>>, ExcelError> {
        self.observe_evaluation_resource_request(
            EvaluationRequestKind::CellsCancellable,
            |engine| {
                engine.observe_function_semantic_epoch()?;
                engine.active_cancel_flag = Some(cancel.clone());
                let res = engine.evaluate_cells_cancellable_impl(targets, cancel.as_flag());
                engine.active_cancel_flag = None;
                res
            },
        )
    }

    fn evaluate_cells_cancellable_impl(
        &mut self,
        targets: &[(&str, u32, u32)],
        cancel_flag: &AtomicBool,
    ) -> Result<Vec<Option<LiteralValue>>, ExcelError> {
        self.validate_deterministic_mode()?;
        if targets.is_empty() {
            return Ok(Vec::new());
        }
        if cancel_flag.load(Ordering::Relaxed) {
            return Err(ExcelError::new(ExcelErrorKind::Cancelled)
                .with_message("Evaluation cancelled before target preparation"));
        }
        let typed_targets = self.legacy_coordinate_targets(targets);
        self.evaluate_mixed_targets(&typed_targets, None)?;
        Ok(targets
            .iter()
            .map(|(sheet, row, col)| self.get_cell_value(sheet, *row, *col))
            .collect())
    }

    pub fn evaluate_cells_with_target_delta(
        &mut self,
        targets: &[(&str, u32, u32)],
    ) -> Result<(Vec<Option<LiteralValue>>, crate::engine::TargetEvalDelta), ExcelError> {
        self.observe_evaluation_resource_request(EvaluationRequestKind::CellsWithDelta, |engine| {
            engine.observe_function_semantic_epoch()?;
            engine.validate_deterministic_mode()?;
            if targets.is_empty() {
                return Ok((Vec::new(), crate::engine::TargetEvalDelta::default()));
            }
            let mut collector = DeltaCollector::new(DeltaMode::Cells);
            engine.evaluate_until_with_delta_collector(targets, &mut collector)?;
            let values = targets
                .iter()
                .map(|(sheet, row, col)| engine.get_cell_value(sheet, *row, *col))
                .collect();
            Ok((values, collector.finish_target()))
        })
    }

    pub fn evaluate_cells_with_delta(
        &mut self,
        targets: &[(&str, u32, u32)],
    ) -> Result<(Vec<Option<LiteralValue>>, EvalDelta), ExcelError> {
        self.evaluate_cells_with_delta_policy(targets, EvalDeltaCompatibilityPolicy::Unlimited)
    }

    pub fn evaluate_cells_with_delta_policy(
        &mut self,
        targets: &[(&str, u32, u32)],
        policy: EvalDeltaCompatibilityPolicy,
    ) -> Result<(Vec<Option<LiteralValue>>, EvalDelta), ExcelError> {
        self.observe_evaluation_resource_request(EvaluationRequestKind::CellsWithDelta, |engine| {
            engine.evaluate_cells_with_delta_unobserved(targets, policy)
        })
    }

    fn evaluate_cells_with_delta_unobserved(
        &mut self,
        targets: &[(&str, u32, u32)],
        policy: EvalDeltaCompatibilityPolicy,
    ) -> Result<(Vec<Option<LiteralValue>>, EvalDelta), ExcelError> {
        self.observe_function_semantic_epoch()?;
        self.validate_deterministic_mode()?;
        if targets.is_empty() {
            return Ok((Vec::new(), EvalDelta::default()));
        }
        let mut collector = DeltaCollector::new(DeltaMode::Cells);
        self.evaluate_until_with_delta_collector(targets, &mut collector)?;
        let values = targets
            .iter()
            .map(|(s, r, c)| self.get_cell_value(s, *r, *c))
            .collect();
        Ok((values, collector.finish_with_policy(policy)?))
    }

    /// Get the evaluation plan for target cells without actually evaluating them
    pub fn get_eval_plan(&self, targets: &[(&str, u32, u32)]) -> Result<EvalPlan, ExcelError> {
        if targets.is_empty() {
            return Ok(EvalPlan {
                total_vertices_to_evaluate: 0,
                layers: Vec::new(),
                cycles_detected: 0,
                dirty_count: 0,
                volatile_count: 0,
                parallel_enabled: self.config.enable_parallel && self.thread_pool.is_some(),
                estimated_parallel_layers: 0,
                target_cells: Vec::new(),
            });
        }
        if self.config.defer_graph_building && self.has_staged_formulas() {
            return Err(ExcelError::new(ExcelErrorKind::Value).with_message(
                "Evaluation plan requested with deferred graph; build first or call evaluate_*",
            ));
        }

        // Convert targets to A1 notation for consistency
        let addresses: Vec<String> = targets
            .iter()
            .map(|(s, r, c)| format!("{}!{}{}", s, Self::col_to_letters(*c), r))
            .collect();

        // Parse target cell addresses
        let mut target_addrs = Vec::new();
        for (sheet, row, col) in targets {
            if let Some(sheet_id) = self.graph.sheet_id(sheet) {
                let coord = Coord::from_excel(*row, *col, true, true);
                target_addrs.push(CellRef::new(sheet_id, coord));
            }
        }

        // Find vertex IDs for targets
        let mut target_vertex_ids = Vec::new();
        for addr in &target_addrs {
            if let Some(vertex_id) = self.graph.get_vertex_id_for_address(addr) {
                target_vertex_ids.push(*vertex_id);
            }
        }

        if target_vertex_ids.is_empty() {
            return Ok(EvalPlan {
                total_vertices_to_evaluate: 0,
                layers: Vec::new(),
                cycles_detected: 0,
                dirty_count: 0,
                volatile_count: 0,
                parallel_enabled: self.config.enable_parallel && self.thread_pool.is_some(),
                estimated_parallel_layers: 0,
                target_cells: addresses,
            });
        }

        // Build demand subgraph with virtual edges (same as evaluate_until)
        let (precedents_to_eval, vdeps) = self.build_demand_subgraph(&target_vertex_ids);

        if precedents_to_eval.is_empty() {
            return Ok(EvalPlan {
                total_vertices_to_evaluate: 0,
                layers: Vec::new(),
                cycles_detected: 0,
                dirty_count: 0,
                volatile_count: 0,
                parallel_enabled: self.config.enable_parallel && self.thread_pool.is_some(),
                estimated_parallel_layers: 0,
                target_cells: addresses,
            });
        }

        // Count dirty and volatile vertices
        let mut dirty_count = 0;
        let mut volatile_count = 0;
        for &vertex_id in &precedents_to_eval {
            if self.graph.is_dirty(vertex_id) {
                dirty_count += 1;
            }
            if self.graph.is_volatile(vertex_id) {
                volatile_count += 1;
            }
        }

        // Create schedule for the minimal subgraph honoring virtual edges
        let scheduler = Scheduler::new(&self.graph);
        let schedule = scheduler.create_schedule_with_virtual(&precedents_to_eval, &vdeps)?;

        // Build layer information
        let mut layers = Vec::new();
        let mut estimated_parallel_layers = 0;
        let parallel_enabled = self.config.enable_parallel && self.thread_pool.is_some();

        for layer in &schedule.layers {
            let parallel_eligible = parallel_enabled && layer.vertices.len() > 1;
            if parallel_eligible {
                estimated_parallel_layers += 1;
            }

            // Get sample cell addresses (up to 5)
            let sample_cells: Vec<String> = layer
                .vertices
                .iter()
                .take(5)
                .filter_map(|&vertex_id| {
                    self.graph
                        .get_cell_ref_for_vertex(vertex_id)
                        .map(|cell_ref| {
                            let sheet_name = self.graph.sheet_name(cell_ref.sheet_id);
                            format!(
                                "{}!{}{}",
                                sheet_name,
                                Self::col_to_letters(cell_ref.coord.col()),
                                cell_ref.coord.row() + 1
                            )
                        })
                })
                .collect();

            layers.push(LayerInfo {
                vertex_count: layer.vertices.len(),
                parallel_eligible,
                sample_cells,
            });
        }

        Ok(EvalPlan {
            total_vertices_to_evaluate: precedents_to_eval.len(),
            layers,
            cycles_detected: schedule.cycles.len(),
            dirty_count,
            volatile_count,
            parallel_enabled,
            estimated_parallel_layers,
            target_cells: addresses,
        })
    }
    /// Helper to create a schedule, integrating virtual dependencies automatically.
    fn create_evaluation_schedule(
        &mut self,
        to_evaluate: &[VertexId],
    ) -> Result<ScheduleBuildOutput, ExcelError> {
        // Fold pending edge deltas once per schedule build so traversal uses
        // the zero-allocation CSR slices (#125).
        self.graph.flush_pending_edge_deltas();
        if self.can_use_static_schedule_cache(to_evaluate) {
            if let Some(cached) = self.cached_static_schedule.as_ref()
                && cached.topology_epoch == self.topology_epoch
                && cached.candidate_vertices.as_slice() == to_evaluate
            {
                let meta = ScheduleBuildMeta {
                    candidate_vertices: to_evaluate.len(),
                    vdeps_vertices: 0,
                    vdeps_edges: 0,
                    builder_elapsed_ms: 0,
                    used_virtual_schedule: false,
                    schedule_cache_hit: true,
                    schedule_cache_eligible: true,
                };
                return Ok((cached.schedule.clone(), FxHashMap::default(), meta));
            }

            let (schedule, vdeps, mut meta) =
                self.create_evaluation_schedule_uncached(to_evaluate)?;
            meta.schedule_cache_hit = false;
            meta.schedule_cache_eligible = true;
            if vdeps.is_empty() {
                self.cached_static_schedule = Some(CachedScheduleEntry {
                    topology_epoch: self.topology_epoch,
                    candidate_vertices: to_evaluate.to_vec(),
                    schedule: schedule.clone(),
                });
            }
            return Ok((schedule, vdeps, meta));
        }

        let (schedule, vdeps, mut meta) = self.create_evaluation_schedule_uncached(to_evaluate)?;
        meta.schedule_cache_hit = false;
        meta.schedule_cache_eligible = false;
        Ok((schedule, vdeps, meta))
    }

    fn create_evaluation_schedule_uncached(
        &self,
        to_evaluate: &[VertexId],
    ) -> Result<ScheduleBuildOutput, ExcelError> {
        let builder = VirtualDepBuilder::new(self);
        let (vdeps, augmented, builder_elapsed_ms, vdeps_edges) =
            if self.config.enable_virtual_dep_telemetry {
                let build_started = crate::instant::FzInstant::now();
                let (vdeps, augmented) = builder.build(to_evaluate);
                let builder_elapsed_ms = build_started.elapsed().as_millis();
                let vdeps_edges = vdeps.values().map(|deps| deps.len()).sum::<usize>();
                (vdeps, augmented, builder_elapsed_ms, vdeps_edges)
            } else {
                let (vdeps, augmented) = builder.build(to_evaluate);
                (vdeps, augmented, 0, 0)
            };

        let mut final_evaluate = to_evaluate.to_vec();
        if !augmented.is_empty() {
            final_evaluate.extend(augmented);
            final_evaluate.sort_unstable();
            final_evaluate.dedup();
        }

        let use_virtual = !vdeps.is_empty();

        let scheduler = Scheduler::new(&self.graph);
        let schedule = if use_virtual {
            scheduler.create_schedule_with_virtual(&final_evaluate, &vdeps)?
        } else {
            scheduler.create_schedule(&final_evaluate)?
        };

        let meta = ScheduleBuildMeta {
            candidate_vertices: to_evaluate.len(),
            vdeps_vertices: vdeps.len(),
            vdeps_edges,
            builder_elapsed_ms,
            used_virtual_schedule: use_virtual,
            schedule_cache_hit: false,
            schedule_cache_eligible: false,
        };

        Ok((schedule, vdeps, meta))
    }

    fn can_use_static_schedule_cache(&self, to_evaluate: &[VertexId]) -> bool {
        !to_evaluate.is_empty()
            && to_evaluate.iter().copied().all(|v| {
                !self.graph.is_dynamic(v) && self.graph.get_range_dependencies(v).is_none()
            })
    }

    fn start_virtual_dep_telemetry(&self) -> VirtualDepTelemetry {
        VirtualDepTelemetry {
            fallback_mode_activations: self.virtual_dep_fallback_activations,
            ..VirtualDepTelemetry::default()
        }
    }

    fn accumulate_schedule_meta(telemetry: &mut VirtualDepTelemetry, meta: &ScheduleBuildMeta) {
        telemetry.candidate_vertices_total += meta.candidate_vertices;
        telemetry.vdeps_vertices_total += meta.vdeps_vertices;
        telemetry.vdeps_edges_total += meta.vdeps_edges;
        telemetry.builder_elapsed_ms_total += meta.builder_elapsed_ms;
        if meta.schedule_cache_eligible {
            if meta.schedule_cache_hit {
                telemetry.schedule_cache_hits += 1;
                telemetry.reused_schedule_vertices_total += meta.candidate_vertices;
            } else {
                telemetry.schedule_cache_misses += 1;
            }
        }
        if meta.used_virtual_schedule {
            telemetry.schedule_virtual_passes += 1;
        } else {
            telemetry.schedule_static_passes += 1;
        }
    }

    fn dynamic_virtual_regions(&self, vertices: &[VertexId]) -> FxHashMap<VertexId, Vec<Region>> {
        vertices
            .iter()
            .copied()
            .filter(|vertex| self.graph.is_dynamic(*vertex))
            .filter_map(|vertex| {
                let regions = DynamicRefVirtualDepProvider::get_virtual_regions(self, vertex);
                (!regions.is_empty()).then_some((vertex, regions))
            })
            .collect()
    }

    fn extend_target_roots_with_dynamic_regions<'a>(
        &self,
        roots: &mut Vec<crate::engine::target_preparation::TargetProducer>,
        regions: impl Iterator<Item = &'a Region>,
    ) -> Result<(), ExcelError> {
        use crate::engine::target_preparation::TargetProducer;
        let request_id = self
            .active_evaluation_resource_request
            .as_ref()
            .map(|request| request.request_id);
        let root_count = roots.len();
        let mut extended = OrderedTargetProducers::from_ordered(std::mem::take(roots))
            .map_err(|_| target_root_allocation_error(root_count, request_id))?;
        for region in regions {
            for vertex in self.graph.formula_vertices() {
                let key = crate::formula_plane::region_index::RegionKey {
                    sheet_id: self.graph.get_vertex_sheet_id(vertex),
                    row: self.graph.vertex_coord(vertex).row(),
                    col: self.graph.vertex_coord(vertex).col(),
                };
                if region.contains_key(key) {
                    extended.push(TargetProducer::Legacy(vertex)).map_err(|_| {
                        target_root_allocation_error(extended.len() + 1, request_id)
                    })?;
                }
            }
            let authority = self.graph.formula_authority();
            for span_ref in authority.active_span_refs() {
                let Some(span) = authority.plane.spans.get(span_ref) else {
                    continue;
                };
                let Some(demanded) =
                    Region::from_domain(span.result_region.domain()).intersection(*region)
                else {
                    continue;
                };
                extended
                    .push(TargetProducer::Span { span_ref, demanded })
                    .map_err(|_| target_root_allocation_error(extended.len() + 1, request_id))?;
            }
        }
        *roots = extended.into_vec();
        Ok(())
    }

    fn changed_virtual_dep_vertices(
        &mut self,
        to_evaluate: &[VertexId],
        old_vdeps: &FxHashMap<VertexId, Vec<VertexId>>,
    ) -> Vec<VertexId> {
        #[cfg(test)]
        if self.force_virtual_dep_changes_remaining_for_test > 0
            && let Some(vertex) = to_evaluate.first().copied()
        {
            self.force_virtual_dep_changes_remaining_for_test -= 1;
            return vec![vertex];
        }
        if !to_evaluate
            .iter()
            .copied()
            .any(|v| self.graph.is_dynamic(v))
        {
            return Vec::new();
        }

        let builder = VirtualDepBuilder::new(self);
        let (new_vdeps, _) = builder.build(to_evaluate);

        let mut candidates = FxHashSet::default();
        candidates.extend(old_vdeps.keys().copied());
        candidates.extend(new_vdeps.keys().copied());

        let mut changed = Vec::new();
        for v in candidates {
            if old_vdeps.get(&v) != new_vdeps.get(&v) {
                changed.push(v);
            }
        }
        changed
    }

    /// Build a demand-driven subgraph for the given targets, including ephemeral edges for
    /// compressed ranges, and returning the set of dirty/volatile precedents and virtual deps.
    fn build_demand_subgraph(
        &self,
        target_vertices: &[VertexId],
    ) -> (
        Vec<VertexId>,
        rustc_hash::FxHashMap<VertexId, Vec<VertexId>>,
    ) {
        #[cfg(feature = "tracing")]
        let _span =
            tracing::info_span!("demand_subgraph", targets = target_vertices.len()).entered();
        use rustc_hash::{FxHashMap, FxHashSet};

        let mut to_evaluate: FxHashSet<VertexId> = FxHashSet::default();
        let mut visited: FxHashSet<VertexId> = FxHashSet::default();
        let mut stack: Vec<VertexId> = Vec::new();
        let mut vdeps: FxHashMap<VertexId, Vec<VertexId>> = FxHashMap::default(); // incoming deps per vertex

        for &t in target_vertices {
            stack.push(t);
        }

        while let Some(v) = stack.pop() {
            if !visited.insert(v) {
                continue;
            }
            if !self.graph.vertex_exists(v) {
                continue;
            }
            // Schedule dirty/volatile formulas. Also schedule pass-through
            // Named*/Range vertices so the scheduler honours the
            // topological position of any formula cells that sit underneath
            // them — without these in `vertex_set` the scheduler skips the
            // edges that route a target through a named-range vertex into
            // its underlying cells, and the underlying cells then end up
            // in the same (or an earlier) layer as the target.
            match self.graph.get_vertex_kind(v) {
                VertexKind::FormulaScalar | VertexKind::FormulaArray => {
                    if self.graph.is_dirty(v) || self.graph.is_volatile(v) {
                        to_evaluate.insert(v);
                    }
                }
                VertexKind::NamedScalar
                | VertexKind::NamedArray
                | VertexKind::Range
                | VertexKind::InfiniteRange => {
                    to_evaluate.insert(v);
                }
                _ => {}
            }

            // Explicit dependencies (graph edges). We push *every* dep onto
            // the stack — not just formulas — because intermediate vertices
            // (NamedScalar, NamedArray, Range) are pass-through nodes whose
            // own dependencies point at the actual formula cells. Filtering
            // by kind here previously caused DN-range refs to be dropped
            // from the demand subgraph, so a target like
            // ``=SUM(named_range_pointing_at_dirty_cells)`` would evaluate
            // using stale values for those cells. The kind check at the top
            // of the loop still gates which vertices end up in
            // ``to_evaluate``; only Formula vertices are scheduled.
            if let Some(dependencies) = self.graph.dependencies_slice(v) {
                for &dep in dependencies {
                    if self.graph.vertex_exists(dep) && !visited.contains(&dep) {
                        stack.push(dep);
                    }
                }
            } else {
                for dep in self.graph.get_dependencies(v) {
                    if self.graph.vertex_exists(dep) && !visited.contains(&dep) {
                        stack.push(dep);
                    }
                }
            } // Virtual dependencies (compressed ranges + dynamic like INDIRECT)
            let builder = VirtualDepBuilder::new(self);
            let (vdeps_map, _) = builder.build(&[v]);
            if let Some(deps) = vdeps_map.get(&v) {
                for &u in deps {
                    vdeps.entry(v).or_default().push(u);
                    if !visited.contains(&u) {
                        stack.push(u);
                    }
                }
            }
        }

        let mut result: Vec<VertexId> = to_evaluate.into_iter().collect();
        result.sort_unstable();
        // Dedup virtual deps
        for deps in vdeps.values_mut() {
            deps.sort_unstable();
            deps.dedup();
        }
        (result, vdeps)
    }

    /// Helper: convert 1-based column index to Excel-style letters (1 -> A, 27 -> AA)
    fn col_to_letters(col: u32) -> String {
        col_letters_from_1based(col).expect("column index must be >= 1")
    }

    /// Evaluate all dirty/volatile vertices with cancellation support
    pub fn evaluate_all_cancellable(
        &mut self,
        cancel: crate::engine::CancelToken,
    ) -> Result<EvalResult, ExcelError> {
        self.observe_evaluation_resource_request(EvaluationRequestKind::FullCancellable, |engine| {
            engine.observe_function_semantic_epoch()?;
            engine.active_cancel_flag = Some(cancel.clone());
            let res = engine.evaluate_all_cancellable_impl(cancel.as_flag());
            engine.active_cancel_flag = None;
            res
        })
    }

    fn evaluate_all_cancellable_impl(
        &mut self,
        cancel_flag: &AtomicBool,
    ) -> Result<EvalResult, ExcelError> {
        self.begin_evaluation_request();
        let _source_cache = self.source_cache_session();
        self.validate_deterministic_mode()?;
        if self.config.defer_graph_building {
            self.build_graph_all()?;
        }
        if self.graph.formula_authority().active_span_count() > 0 {
            if cancel_flag.load(Ordering::Relaxed) {
                return Err(ExcelError::new(ExcelErrorKind::Cancelled).with_message(
                    "Evaluation cancelled before FormulaPlane scheduling".to_string(),
                ));
            }
            return self.evaluate_authoritative_formula_plane_all();
        }
        self.reset_virtual_dep_telemetry_if_disabled();
        let start = crate::instant::FzInstant::now();
        let mut computed_vertices = 0;
        let mut cycle_errors = 0;

        let mut replan_iterations = 0;
        const MAX_REPLAN: usize = 5;
        let mut telemetry = self
            .config
            .enable_virtual_dep_telemetry
            .then(|| self.start_virtual_dep_telemetry());

        loop {
            if cancel_flag.load(Ordering::Relaxed) {
                if let Some(mut t) = telemetry {
                    t.bailout_reason = Some("cancelled");
                    t.replan_iterations = replan_iterations;
                    self.last_virtual_dep_telemetry = t;
                }
                return Err(ExcelError::new(ExcelErrorKind::Cancelled)
                    .with_message("Evaluation cancelled before scheduling".to_string()));
            }

            let to_evaluate = self.graph.get_evaluation_vertices();
            if to_evaluate.is_empty() {
                if let Some(t) = telemetry.as_mut()
                    && t.bailout_reason.is_none()
                {
                    t.bailout_reason = Some("no_work");
                }
                break;
            }

            let (schedule, old_vdeps, meta) = self.create_evaluation_schedule(&to_evaluate)?;
            if let Some(t) = telemetry.as_mut() {
                Self::accumulate_schedule_meta(t, &meta);
            }

            // Walk units in condensation order, checking cancellation between
            // units (formerly between cycles and between layers).
            for &unit in &schedule.units {
                match unit {
                    ScheduleUnit::Cycle(i) => {
                        // Check cancellation between cycles
                        if cancel_flag.load(Ordering::Relaxed) {
                            if let Some(mut t) = telemetry {
                                t.bailout_reason = Some("cancelled");
                                t.replan_iterations = replan_iterations;
                                self.last_virtual_dep_telemetry = t;
                            }
                            return Err(ExcelError::new(ExcelErrorKind::Cancelled).with_message(
                                "Evaluation cancelled during cycle handling".to_string(),
                            ));
                        }

                        if self.handle_cycle_unit(
                            schedule.unit_cycle(i),
                            None,
                            None,
                            Some(cancel_flag),
                        )? > 0
                        {
                            cycle_errors += 1;
                        }
                    }
                    ScheduleUnit::Layer(i) => {
                        let layer = schedule.unit_layer(i);
                        // Check cancellation between layers
                        if cancel_flag.load(Ordering::Relaxed) {
                            if let Some(mut t) = telemetry {
                                t.bailout_reason = Some("cancelled");
                                t.replan_iterations = replan_iterations;
                                self.last_virtual_dep_telemetry = t;
                            }
                            return Err(ExcelError::new(ExcelErrorKind::Cancelled)
                                .with_message("Evaluation cancelled between layers".to_string()));
                        }

                        // Evaluate vertices in this layer (parallel or sequential)
                        if self.thread_pool.is_some() && layer.vertices.len() > 1 {
                            computed_vertices +=
                                self.evaluate_layer_parallel_cancellable(layer, cancel_flag)?;
                        } else {
                            computed_vertices +=
                                self.evaluate_layer_sequential_cancellable(layer, cancel_flag)?;
                        }
                    }
                }
            }

            let changed_vertices = self.changed_virtual_dep_vertices(&to_evaluate, &old_vdeps);
            if let Some(t) = telemetry.as_mut() {
                t.changed_vdeps_total += changed_vertices.len();
            }
            self.resource_checkpoint(0)?;
            self.graph.clear_dirty_flags(&to_evaluate);
            for v in &changed_vertices {
                self.graph.set_dirty(*v, true);
            }

            if changed_vertices.is_empty() {
                if let Some(t) = telemetry.as_mut() {
                    t.bailout_reason = Some("converged");
                }
                break;
            }
            if replan_iterations >= MAX_REPLAN {
                if let Some(mut t) = telemetry.take() {
                    t.bailout_reason = Some("max_replan");
                    t.replan_iterations = replan_iterations;
                    self.last_virtual_dep_telemetry = t;
                }
                return Err(
                    self.replan_exhausted_error(MAX_REPLAN, "dynamic dependency evaluation")
                );
            }
            replan_iterations += 1;
        }

        if let Some(mut t) = telemetry {
            t.replan_iterations = replan_iterations;
            self.last_virtual_dep_telemetry = t;
        }

        // Re-dirty volatile vertices for the next evaluation cycle
        self.redirty_for_next_recalc();
        self.recalc_epoch = self.recalc_epoch.wrapping_add(1);

        Ok(EvalResult {
            computed_vertices,
            cycle_errors,
            elapsed: start.elapsed(),
        })
    }

    /// Evaluate only the necessary precedents for specific target cells with cancellation support
    pub fn evaluate_until_cancellable(
        &mut self,
        targets: &[&str],
        cancel: crate::engine::CancelToken,
    ) -> Result<EvalResult, ExcelError> {
        self.observe_evaluation_resource_request(
            EvaluationRequestKind::TargetedCancellable,
            |engine| {
                engine.observe_function_semantic_epoch()?;
                engine.active_cancel_flag = Some(cancel.clone());
                let res = engine.evaluate_until_cancellable_impl(targets, cancel.as_flag());
                engine.active_cancel_flag = None;
                res
            },
        )
    }

    fn evaluate_until_cancellable_impl(
        &mut self,
        targets: &[&str],
        cancel_flag: &AtomicBool,
    ) -> Result<EvalResult, ExcelError> {
        if cancel_flag.load(Ordering::Relaxed) {
            return Err(ExcelError::new(ExcelErrorKind::Cancelled)
                .with_message("Evaluation cancelled before target preparation"));
        }
        let mut typed_targets = Vec::with_capacity(targets.len());
        for target in targets {
            let (sheet, row, col) = self.parse_a1_notation(target)?;
            self.graph.sheet_id_mut(&sheet);
            typed_targets.push(crate::engine::EvaluationTarget::Cell { sheet, row, col });
        }
        self.evaluate_mixed_targets(&typed_targets, None)
    }

    fn parse_a1_notation(&self, address: &str) -> Result<(String, u32, u32), ExcelError> {
        let mut quoted = false;
        let mut separator = None;
        let bytes = address.as_bytes();
        let mut index = 0usize;
        while index < bytes.len() {
            match bytes[index] {
                b'\'' => {
                    if quoted && bytes.get(index + 1) == Some(&b'\'') {
                        index = index.saturating_add(1);
                    } else {
                        quoted = !quoted;
                    }
                }
                b'!' if !quoted => separator = Some(index),
                _ => {}
            }
            index = index.saturating_add(1);
        }
        if quoted {
            return Err(ExcelError::new(ExcelErrorKind::Ref)
                .with_message(format!("Invalid quoted sheet reference `{address}`")));
        }
        let (sheet, cell_part) = match separator {
            Some(separator) => {
                let raw_sheet = &address[..separator];
                let sheet = if raw_sheet.starts_with('\'') && raw_sheet.ends_with('\'') {
                    raw_sheet[1..raw_sheet.len().saturating_sub(1)].replace("''", "'")
                } else {
                    raw_sheet.to_string()
                };
                (sheet, &address[separator + 1..])
            }
            None => (self.default_sheet_name().to_string(), address),
        };

        let (row, col, _, _) = parse_a1_1based(cell_part).map_err(|err| {
            ExcelError::new(ExcelErrorKind::Ref)
                .with_message(format!("Invalid cell reference `{cell_part}`: {err}"))
        })?;

        Ok((sheet, row, col))
    }

    /// Determine volatility using this engine's FunctionProvider, falling back to global registry.
    fn is_ast_volatile_with_provider(&self, ast: &ASTNode) -> bool {
        use formualizer_parse::parser::ASTNodeType;
        match &ast.node_type {
            ASTNodeType::Function { name, args, .. } => {
                if let Some(func) = self
                    .get_function("", name)
                    .or_else(|| crate::function_registry::get("", name))
                    && func.caps().contains(crate::function::FnCaps::VOLATILE)
                {
                    return true;
                }
                args.iter()
                    .any(|arg| self.is_ast_volatile_with_provider(arg))
            }
            ASTNodeType::BinaryOp { left, right, .. } => {
                self.is_ast_volatile_with_provider(left)
                    || self.is_ast_volatile_with_provider(right)
            }
            ASTNodeType::UnaryOp { expr, .. } => self.is_ast_volatile_with_provider(expr),
            ASTNodeType::Array(rows) => rows.iter().any(|row| {
                row.iter()
                    .any(|cell| self.is_ast_volatile_with_provider(cell))
            }),
            _ => false,
        }
    }

    /// Find dirty precedents that need evaluation for the given target vertices
    fn find_dirty_precedents(&self, target_vertices: &[VertexId]) -> Vec<VertexId> {
        let mut to_evaluate = FxHashSet::default();
        let mut visited = FxHashSet::default();
        let mut stack = Vec::new();

        // Start reverse traversal from target vertices
        for &target in target_vertices {
            stack.push(target);
        }

        while let Some(vertex_id) = stack.pop() {
            if !visited.insert(vertex_id) {
                continue; // Already processed
            }

            if self.graph.vertex_exists(vertex_id) {
                // Check if this vertex needs evaluation
                let kind = self.graph.get_vertex_kind(vertex_id);
                let needs_eval = match kind {
                    super::vertex::VertexKind::FormulaScalar
                    | super::vertex::VertexKind::FormulaArray => {
                        self.graph.is_dirty(vertex_id) || self.graph.is_volatile(vertex_id)
                    }
                    _ => false, // Values and empty cells don't need evaluation
                };

                if needs_eval {
                    to_evaluate.insert(vertex_id);
                }

                // Continue traversal to dependencies (precedents)
                if let Some(dependencies) = self.graph.dependencies_slice(vertex_id) {
                    for &dep_id in dependencies {
                        if !visited.contains(&dep_id) {
                            stack.push(dep_id);
                        }
                    }
                } else {
                    let dependencies = self.graph.get_dependencies(vertex_id);
                    for dep_id in dependencies {
                        if !visited.contains(&dep_id) {
                            stack.push(dep_id);
                        }
                    }
                }
            }
        }

        let mut result: Vec<VertexId> = to_evaluate.into_iter().collect();
        result.sort_unstable();
        result
    }

    /// Evaluate a layer sequentially
    fn evaluate_layer_sequential(
        &mut self,
        layer: &super::scheduler::Layer,
    ) -> Result<usize, ExcelError> {
        self.resource_checkpoint(layer.vertices.len() as u64)?;
        self.evaluate_layer_sequential_effects(layer)
    }

    fn update_vertex_value_with_delta(
        &mut self,
        vertex_id: VertexId,
        new_value: LiteralValue,
        delta: &mut DeltaCollector,
    ) {
        if delta.mode != DeltaMode::Off
            && let Some(cell) = self.graph.get_cell_ref_for_vertex(vertex_id)
        {
            let sheet_name = self.graph.sheet_name(cell.sheet_id);
            let old = self
                .read_cell_value(sheet_name, cell.coord.row() + 1, cell.coord.col() + 1)
                .unwrap_or(LiteralValue::Empty);
            if old != new_value {
                delta.record_cell(cell.sheet_id, cell.coord.row(), cell.coord.col());
            }
        }
        self.graph.update_vertex_value(vertex_id, new_value.clone());
        self.mirror_vertex_value_to_overlay(vertex_id, &new_value);
    }

    fn evaluate_layer_sequential_with_delta(
        &mut self,
        layer: &super::scheduler::Layer,
        delta: &mut DeltaCollector,
    ) -> Result<usize, ExcelError> {
        self.resource_checkpoint(layer.vertices.len() as u64)?;
        self.evaluate_layer_sequential_with_delta_effects(layer, delta)
    }

    /// Evaluate a layer sequentially with cancellation support
    fn evaluate_layer_sequential_cancellable(
        &mut self,
        layer: &super::scheduler::Layer,
        cancel_flag: &AtomicBool,
    ) -> Result<usize, ExcelError> {
        self.resource_checkpoint(layer.vertices.len() as u64)?;
        self.evaluate_layer_sequential_cancellable_effects(layer, cancel_flag)
    }

    /// Evaluate a layer sequentially with more frequent cancellation checks for demand-driven evaluation
    fn evaluate_layer_sequential_cancellable_demand_driven(
        &mut self,
        layer: &super::scheduler::Layer,
        cancel_flag: &AtomicBool,
    ) -> Result<usize, ExcelError> {
        self.resource_checkpoint(layer.vertices.len() as u64)?;
        self.evaluate_layer_sequential_cancellable_demand_driven_effects(layer, cancel_flag)
    }

    /// Evaluate a layer in parallel using the thread pool
    fn evaluate_layer_parallel(
        &mut self,
        layer: &super::scheduler::Layer,
    ) -> Result<usize, ExcelError> {
        self.resource_checkpoint(layer.vertices.len() as u64)?;
        self.evaluate_layer_parallel_effects(layer)
    }

    fn evaluate_layer_parallel_with_delta(
        &mut self,
        layer: &super::scheduler::Layer,
        delta: &mut DeltaCollector,
    ) -> Result<usize, ExcelError> {
        self.resource_checkpoint(layer.vertices.len() as u64)?;
        self.evaluate_layer_parallel_with_delta_effects(layer, delta)
    }

    /// Evaluate a layer in parallel with cancellation support
    fn evaluate_layer_parallel_cancellable(
        &mut self,
        layer: &super::scheduler::Layer,
        cancel_flag: &AtomicBool,
    ) -> Result<usize, ExcelError> {
        self.resource_checkpoint(layer.vertices.len() as u64)?;
        self.evaluate_layer_parallel_cancellable_effects(layer, cancel_flag)
    }

    /// Apply a computed result produced by `evaluate_vertex_immutable()`.
    ///
    /// This is the parallel equivalent of the "apply" portion of `evaluate_vertex_impl`.
    /// We keep apply sequential for correctness (spill commit is inherently stateful).
    fn apply_parallel_vertex_result(
        &mut self,
        vertex_id: VertexId,
        result: LiteralValue,
        mut delta: Option<&mut DeltaCollector>,
        overwritable_formulas: Option<&rustc_hash::FxHashSet<VertexId>>,
    ) -> Result<(), ExcelError> {
        // If this vertex's cell is currently covered by a spill from a different anchor,
        // ignore the computed result. The spill's committed values own the grid.
        if let Some(cell) = self.graph.get_cell_ref(vertex_id)
            && let Some(owner) = self.graph.spill_registry_anchor_for_cell(cell)
            && owner != vertex_id
        {
            return Ok(());
        }

        let kind = self.graph.get_vertex_kind(vertex_id);

        // Only formula vertices spill dynamic arrays into the grid.
        let is_formula = matches!(kind, VertexKind::FormulaScalar | VertexKind::FormulaArray);
        if is_formula {
            match result {
                LiteralValue::Array(rows) => {
                    self.apply_array_result_from_parallel(
                        vertex_id,
                        rows,
                        delta.as_deref_mut(),
                        overwritable_formulas,
                    )?;
                }
                other => {
                    self.apply_non_array_result_from_parallel(
                        vertex_id,
                        other,
                        delta.as_deref_mut(),
                    );
                }
            }
            return Ok(());
        }

        // Non-formula vertices: store value as-is (arrays remain arrays; no spill).
        if let Some(d) = delta {
            self.update_vertex_value_with_delta(vertex_id, result, d);
        } else {
            self.graph.update_vertex_value(vertex_id, result.clone());
            self.mirror_vertex_value_to_overlay(vertex_id, &result);
        }
        Ok(())
    }

    fn apply_non_array_result_from_parallel(
        &mut self,
        vertex_id: VertexId,
        value: LiteralValue,
        delta: Option<&mut DeltaCollector>,
    ) {
        // Scalar/error result: store value and ensure any previous spill is cleared.
        // This mirrors the sequential behavior in `evaluate_vertex_impl`.
        let spill_cells = self
            .graph
            .spill_cells_for_anchor(vertex_id)
            .map(|cells| cells.to_vec())
            .unwrap_or_default();

        if let Some(d) = delta
            && d.mode != DeltaMode::Off
            && let Some(anchor) = self.graph.get_cell_ref_for_vertex(vertex_id)
        {
            if spill_cells.is_empty() {
                let old = self
                    .read_cell_value(
                        self.graph.sheet_name(anchor.sheet_id),
                        anchor.coord.row() + 1,
                        anchor.coord.col() + 1,
                    )
                    .unwrap_or(LiteralValue::Empty);
                if old != value {
                    d.record_cell(anchor.sheet_id, anchor.coord.row(), anchor.coord.col());
                }
            } else {
                for cell in spill_cells.iter() {
                    let sheet_name = self.graph.sheet_name(cell.sheet_id);
                    let old = self
                        .get_cell_value(sheet_name, cell.coord.row() + 1, cell.coord.col() + 1)
                        .unwrap_or(LiteralValue::Empty);
                    let new = if cell.sheet_id == anchor.sheet_id
                        && cell.coord.row() == anchor.coord.row()
                        && cell.coord.col() == anchor.coord.col()
                    {
                        value.clone()
                    } else {
                        LiteralValue::Empty
                    };
                    Self::record_cell_if_changed(d, cell, &old, &new);
                }
            }
        }

        self.graph.clear_spill_region(vertex_id);
        if let Some(scope) = Self::formula_plane_region_from_cells(&spill_cells) {
            self.record_formula_plane_structural_change(scope);
        }

        if self.config.arrow_storage_enabled
            && self.config.delta_overlay_enabled
            && self.config.write_formula_overlay_enabled
        {
            let empty = LiteralValue::Empty;
            for cell in spill_cells.iter() {
                let sheet_name = self.graph.sheet_name(cell.sheet_id).to_string();
                self.mirror_value_to_computed_overlay(
                    &sheet_name,
                    cell.coord.row() + 1,
                    cell.coord.col() + 1,
                    &empty,
                );
            }
        }

        self.graph.update_vertex_value(vertex_id, value.clone());
        self.mirror_vertex_value_to_overlay(vertex_id, &value);
    }

    fn apply_array_result_from_parallel(
        &mut self,
        vertex_id: VertexId,
        rows: Vec<Vec<LiteralValue>>,
        mut delta: Option<&mut DeltaCollector>,
        overwritable_formulas: Option<&rustc_hash::FxHashSet<VertexId>>,
    ) -> Result<(), ExcelError> {
        // Keep behavior consistent with the sequential spill path in `evaluate_vertex_impl`.
        self.graph
            .set_kind(vertex_id, crate::engine::vertex::VertexKind::FormulaArray);

        let anchor = self
            .graph
            .get_cell_ref(vertex_id)
            .expect("cell ref for vertex");
        let sheet_id = anchor.sheet_id;
        let h = rows.len() as u32;
        let w = rows.first().map(|r| r.len()).unwrap_or(0) as u32;

        // Hard cap to avoid vertex explosion from huge dynamic arrays.
        let spill_cells = (h as u64).saturating_mul(w as u64);
        if spill_cells > self.config.spill.max_spill_cells as u64 {
            self.clear_spill_projection_and_mirror(vertex_id, delta.as_deref_mut());
            let spill_err = ExcelError::new(ExcelErrorKind::Spill)
                .with_message("SpillTooLarge")
                .with_extra(formualizer_common::ExcelErrorExtra::Spill {
                    expected_rows: h,
                    expected_cols: w,
                });
            let spill_val = LiteralValue::Error(spill_err.clone());
            if let Some(d) = delta.as_deref_mut()
                && d.mode != DeltaMode::Off
            {
                let old = self
                    .read_cell_value(
                        self.graph.sheet_name(anchor.sheet_id),
                        anchor.coord.row() + 1,
                        anchor.coord.col() + 1,
                    )
                    .unwrap_or(LiteralValue::Empty);
                if old != spill_val {
                    d.record_cell(anchor.sheet_id, anchor.coord.row(), anchor.coord.col());
                }
            }
            self.graph.update_vertex_value(vertex_id, spill_val.clone());
            self.mirror_vertex_value_to_overlay(vertex_id, &spill_val);
            return Ok(());
        }

        // Bounds check to avoid out-of-range writes (align to AbsCoord capacity)
        const PACKED_MAX_ROW: u32 = 1_048_575; // 20-bit max
        const PACKED_MAX_COL: u32 = 16_383; // 14-bit max
        let end_row = anchor.coord.row().saturating_add(h).saturating_sub(1);
        let end_col = anchor.coord.col().saturating_add(w).saturating_sub(1);
        if end_row > PACKED_MAX_ROW || end_col > PACKED_MAX_COL {
            self.clear_spill_projection_and_mirror(vertex_id, delta.as_deref_mut());
            let spill_err = ExcelError::new(ExcelErrorKind::Spill)
                .with_message("Spill exceeds sheet bounds")
                .with_extra(formualizer_common::ExcelErrorExtra::Spill {
                    expected_rows: h,
                    expected_cols: w,
                });
            let spill_val = LiteralValue::Error(spill_err.clone());
            if let Some(d) = delta.as_deref_mut()
                && d.mode != DeltaMode::Off
            {
                let old = self
                    .read_cell_value(
                        self.graph.sheet_name(anchor.sheet_id),
                        anchor.coord.row() + 1,
                        anchor.coord.col() + 1,
                    )
                    .unwrap_or(LiteralValue::Empty);
                if old != spill_val {
                    d.record_cell(anchor.sheet_id, anchor.coord.row(), anchor.coord.col());
                }
            }
            self.graph.update_vertex_value(vertex_id, spill_val.clone());
            self.mirror_vertex_value_to_overlay(vertex_id, &spill_val);
            return Ok(());
        }

        let mut targets = Vec::new();
        for r in 0..h {
            for c in 0..w {
                targets.push(self.graph.make_cell_ref_internal(
                    sheet_id,
                    anchor.coord.row() + r,
                    anchor.coord.col() + c,
                ));
            }
        }

        match self.spill_mgr.reserve(
            vertex_id,
            anchor,
            SpillShape { rows: h, cols: w },
            SpillMeta {
                epoch: self.recalc_epoch,
                config: self.config.spill,
            },
        ) {
            Ok(()) => {
                if let Err(e) = self.commit_spill_and_mirror(
                    vertex_id,
                    &targets,
                    rows.clone(),
                    delta.as_deref_mut(),
                    overwritable_formulas,
                ) {
                    self.clear_spill_projection_and_mirror(vertex_id, delta.as_deref_mut());
                    let err_val = LiteralValue::Error(e.clone());
                    if let Some(d) = delta.as_deref_mut()
                        && d.mode != DeltaMode::Off
                    {
                        let old = self
                            .read_cell_value(
                                self.graph.sheet_name(anchor.sheet_id),
                                anchor.coord.row() + 1,
                                anchor.coord.col() + 1,
                            )
                            .unwrap_or(LiteralValue::Empty);
                        if old != err_val {
                            d.record_cell(anchor.sheet_id, anchor.coord.row(), anchor.coord.col());
                        }
                    }
                    self.graph.update_vertex_value(vertex_id, err_val.clone());
                    self.mirror_vertex_value_to_overlay(vertex_id, &err_val);
                    return Ok(());
                }

                // Anchor shows the top-left value, like Excel
                let top_left = rows
                    .first()
                    .and_then(|r| r.first())
                    .cloned()
                    .unwrap_or(LiteralValue::Empty);
                self.graph.update_vertex_value(vertex_id, top_left.clone());
                self.mirror_vertex_value_to_overlay(vertex_id, &top_left);
                Ok(())
            }
            Err(e) => {
                self.clear_spill_projection_and_mirror(vertex_id, delta.as_deref_mut());
                let spill_err = ExcelError::new(ExcelErrorKind::Spill)
                    .with_message(e.message.unwrap_or_else(|| "Spill blocked".to_string()))
                    .with_extra(formualizer_common::ExcelErrorExtra::Spill {
                        expected_rows: h,
                        expected_cols: w,
                    });
                let spill_val = LiteralValue::Error(spill_err.clone());
                if let Some(d) = delta
                    && d.mode != DeltaMode::Off
                {
                    let old = self
                        .read_cell_value(
                            self.graph.sheet_name(anchor.sheet_id),
                            anchor.coord.row() + 1,
                            anchor.coord.col() + 1,
                        )
                        .unwrap_or(LiteralValue::Empty);
                    if old != spill_val {
                        d.record_cell(anchor.sheet_id, anchor.coord.row(), anchor.coord.col());
                    }
                }
                self.graph.update_vertex_value(vertex_id, spill_val.clone());
                self.mirror_vertex_value_to_overlay(vertex_id, &spill_val);
                Ok(())
            }
        }
    }

    /// Evaluate a single vertex without mutating the graph (for parallel evaluation)
    fn evaluate_vertex_immutable(&self, vertex_id: VertexId) -> Result<LiteralValue, ExcelError> {
        // Check if vertex exists
        if !self.graph.vertex_exists(vertex_id) {
            return Err(ExcelError::new(formualizer_common::ExcelErrorKind::Ref)
                .with_message(format!("Vertex not found: {vertex_id:?}")));
        }

        // Get vertex kind and check if it needs evaluation
        let kind = self.graph.get_vertex_kind(vertex_id);
        let sheet_id = self.graph.get_vertex_sheet_id(vertex_id);

        let ast_id = match kind {
            VertexKind::FormulaScalar | VertexKind::FormulaArray => {
                if let Some(ast_id) = self.graph.get_formula_id(vertex_id) {
                    ast_id
                } else {
                    return Ok(LiteralValue::Number(0.0));
                }
            }
            VertexKind::Empty | VertexKind::Cell => {
                if let Some(cell_ref) = self.graph.get_cell_ref(vertex_id) {
                    let sheet_name = self.graph.sheet_name(cell_ref.sheet_id);
                    let row = cell_ref.coord.row() + 1;
                    let col = cell_ref.coord.col() + 1;
                    if let Some(v) = self.read_cell_value(sheet_name, row, col) {
                        return Ok(v);
                    }
                }
                return Ok(LiteralValue::Number(0.0));
            }
            VertexKind::NamedScalar => {
                let named_range = self.graph.named_range_by_vertex(vertex_id).ok_or_else(|| {
                    ExcelError::new(ExcelErrorKind::Name)
                        .with_message("Named range metadata missing".to_string())
                })?;

                return match &named_range.definition {
                    NamedDefinition::Cell(cell_ref) => {
                        let sheet_name = self.graph.sheet_name(cell_ref.sheet_id);
                        Ok(self
                            .get_cell_value(
                                sheet_name,
                                cell_ref.coord.row() + 1,
                                cell_ref.coord.col() + 1,
                            )
                            .unwrap_or(LiteralValue::Empty))
                    }
                    NamedDefinition::Literal(v) => Ok(v.clone()),
                    NamedDefinition::Formula { ast, .. } => {
                        let context_sheet = match named_range.scope {
                            NameScope::Sheet(id) => id,
                            NameScope::Workbook => sheet_id,
                        };
                        let sheet_name = self.graph.sheet_name(context_sheet);
                        let cell_ref = self
                            .graph
                            .get_cell_ref(vertex_id)
                            .unwrap_or_else(|| self.graph.make_cell_ref(sheet_name, 0, 0));
                        let interpreter = Interpreter::new_with_cell(self, sheet_name, cell_ref);
                        interpreter.evaluate_ast(ast).map(|cv| cv.into_literal())
                    }
                    NamedDefinition::Range(_) => Err(ExcelError::new(ExcelErrorKind::Value)
                        .with_message("Range-valued name evaluated as scalar".to_string())),
                };
            }
            VertexKind::NamedArray => {
                let named_range = self.graph.named_range_by_vertex(vertex_id).ok_or_else(|| {
                    ExcelError::new(ExcelErrorKind::Name)
                        .with_message("Named range metadata missing".to_string())
                })?;

                return match &named_range.definition {
                    NamedDefinition::Range(range_ref) => {
                        if range_ref.start.sheet_id != range_ref.end.sheet_id {
                            return Err(ExcelError::new(ExcelErrorKind::Ref)
                                .with_message("Named range cannot span sheets".to_string()));
                        }
                        let sheet_name = self.graph.sheet_name(range_ref.start.sheet_id);
                        let sr0 = range_ref.start.coord.row();
                        let sc0 = range_ref.start.coord.col();
                        let er0 = range_ref.end.coord.row();
                        let ec0 = range_ref.end.coord.col();
                        if sr0 > er0 || sc0 > ec0 {
                            return Err(ExcelError::new(ExcelErrorKind::Ref)
                                .with_message("Invalid named range bounds".to_string()));
                        }

                        let h = (er0 - sr0 + 1) as usize;
                        let w = (ec0 - sc0 + 1) as usize;
                        let cell_count = (h as u64).saturating_mul(w as u64);
                        if cell_count > self.config.spill.max_spill_cells as u64 {
                            return Err(ExcelError::new(ExcelErrorKind::NImpl).with_message(
                                "Named range too large to materialize as an array".to_string(),
                            ));
                        }

                        let mut rows = Vec::with_capacity(h);
                        for r0 in sr0..=er0 {
                            let mut row = Vec::with_capacity(w);
                            for c0 in sc0..=ec0 {
                                let v = self
                                    .get_cell_value(sheet_name, r0 + 1, c0 + 1)
                                    .unwrap_or(LiteralValue::Empty);
                                row.push(v);
                            }
                            rows.push(row);
                        }
                        Ok(LiteralValue::Array(rows))
                    }
                    NamedDefinition::Cell(cell_ref) => {
                        let sheet_name = self.graph.sheet_name(cell_ref.sheet_id);
                        let row = cell_ref.coord.row() + 1;
                        let col = cell_ref.coord.col() + 1;
                        let v = self
                            .get_cell_value(sheet_name, row, col)
                            .unwrap_or(LiteralValue::Empty);
                        Ok(LiteralValue::Array(vec![vec![v]]))
                    }
                    NamedDefinition::Literal(v) => Ok(LiteralValue::Array(vec![vec![v.clone()]])),
                    NamedDefinition::Formula { ast, .. } => {
                        let context_sheet = match named_range.scope {
                            NameScope::Sheet(id) => id,
                            NameScope::Workbook => sheet_id,
                        };
                        let sheet_name = self.graph.sheet_name(context_sheet);
                        let cell_ref = self
                            .graph
                            .get_cell_ref(vertex_id)
                            .unwrap_or_else(|| self.graph.make_cell_ref(sheet_name, 0, 0));
                        let interpreter = Interpreter::new_with_cell(self, sheet_name, cell_ref);
                        match interpreter.evaluate_ast(ast) {
                            Ok(cv) => {
                                let v = cv.into_literal();
                                match v {
                                    LiteralValue::Array(_) => Ok(v),
                                    other => Ok(LiteralValue::Array(vec![vec![other]])),
                                }
                            }
                            Err(err) => Ok(LiteralValue::Error(err)),
                        }
                    }
                };
            }
            VertexKind::InfiniteRange
            | VertexKind::Range
            | VertexKind::External
            | VertexKind::Table => {
                // Not directly evaluatable here.
                return Ok(LiteralValue::Number(0.0));
            }
        };

        // The interpreter uses a reference to the engine as the context
        let sheet_name = self.graph.sheet_name(sheet_id);
        let cell_ref = self
            .graph
            .get_cell_ref(vertex_id)
            .expect("cell ref for vertex");
        let interpreter = Interpreter::new_with_cell(self, sheet_name, cell_ref);

        interpreter
            .evaluate_arena_ast(ast_id, self.graph.data_store(), self.graph.sheet_reg())
            .map(|cv| {
                crate::engine::result_finalization::finalize_formula_result(cv.into_literal())
            })
    }

    /// Get access to the shared thread pool for parallel evaluation
    pub fn thread_pool(&self) -> Option<&Arc<rayon::ThreadPool>> {
        self.thread_pool.as_ref()
    }
}

#[derive(Default)]
struct RowBoundsCache {
    snapshot: u64,
    // key: (sheet_id, col_idx)
    map: rustc_hash::FxHashMap<(u32, usize), (Option<u32>, Option<u32>)>,
}

impl RowBoundsCache {
    fn new(snapshot: u64) -> Self {
        Self {
            snapshot,
            map: Default::default(),
        }
    }
    fn get_row_bounds(
        &self,
        sheet_id: SheetId,
        col_idx: usize,
        snapshot: u64,
    ) -> Option<(Option<u32>, Option<u32>)> {
        if self.snapshot != snapshot {
            return None;
        }
        self.map.get(&(sheet_id as u32, col_idx)).copied()
    }
    fn put_row_bounds(
        &mut self,
        sheet_id: SheetId,
        col_idx: usize,
        snapshot: u64,
        bounds: (Option<u32>, Option<u32>),
    ) {
        if self.snapshot != snapshot {
            self.snapshot = snapshot;
            self.map.clear();
        }
        self.map.insert((sheet_id as u32, col_idx), bounds);
    }
}

struct UsedAxisBoundsCache {
    snapshot: u64,
    row_bounds_by_col_span: rustc_hash::FxHashMap<(SheetId, u32, u32), Option<(u32, u32)>>,
    col_bounds_by_row_span: rustc_hash::FxHashMap<(SheetId, u32, u32), Option<(u32, u32)>>,
    #[cfg(test)]
    row_hits: std::sync::atomic::AtomicUsize,
    #[cfg(test)]
    row_misses: std::sync::atomic::AtomicUsize,
    #[cfg(test)]
    col_hits: std::sync::atomic::AtomicUsize,
    #[cfg(test)]
    col_misses: std::sync::atomic::AtomicUsize,
}

impl UsedAxisBoundsCache {
    fn new(snapshot: u64) -> Self {
        Self {
            snapshot,
            row_bounds_by_col_span: Default::default(),
            col_bounds_by_row_span: Default::default(),
            #[cfg(test)]
            row_hits: std::sync::atomic::AtomicUsize::new(0),
            #[cfg(test)]
            row_misses: std::sync::atomic::AtomicUsize::new(0),
            #[cfg(test)]
            col_hits: std::sync::atomic::AtomicUsize::new(0),
            #[cfg(test)]
            col_misses: std::sync::atomic::AtomicUsize::new(0),
        }
    }

    fn reset_for_snapshot(&mut self, snapshot: u64) {
        if self.snapshot != snapshot {
            self.snapshot = snapshot;
            self.row_bounds_by_col_span.clear();
            self.col_bounds_by_row_span.clear();
        }
    }

    fn get_row_bounds(
        &self,
        sheet_id: SheetId,
        start_col: u32,
        end_col: u32,
        snapshot: u64,
    ) -> Option<Option<(u32, u32)>> {
        if self.snapshot != snapshot {
            return None;
        }
        let cached = self
            .row_bounds_by_col_span
            .get(&(sheet_id, start_col, end_col))
            .copied();
        #[cfg(test)]
        if cached.is_some() {
            self.row_hits.fetch_add(1, Ordering::Relaxed);
        }
        cached
    }

    fn put_row_bounds(
        &mut self,
        sheet_id: SheetId,
        start_col: u32,
        end_col: u32,
        snapshot: u64,
        bounds: Option<(u32, u32)>,
    ) {
        self.reset_for_snapshot(snapshot);
        self.row_bounds_by_col_span
            .insert((sheet_id, start_col, end_col), bounds);
        #[cfg(test)]
        self.row_misses.fetch_add(1, Ordering::Relaxed);
    }

    fn get_col_bounds(
        &self,
        sheet_id: SheetId,
        start_row: u32,
        end_row: u32,
        snapshot: u64,
    ) -> Option<Option<(u32, u32)>> {
        if self.snapshot != snapshot {
            return None;
        }
        let cached = self
            .col_bounds_by_row_span
            .get(&(sheet_id, start_row, end_row))
            .copied();
        #[cfg(test)]
        if cached.is_some() {
            self.col_hits.fetch_add(1, Ordering::Relaxed);
        }
        cached
    }

    fn put_col_bounds(
        &mut self,
        sheet_id: SheetId,
        start_row: u32,
        end_row: u32,
        snapshot: u64,
        bounds: Option<(u32, u32)>,
    ) {
        self.reset_for_snapshot(snapshot);
        self.col_bounds_by_row_span
            .insert((sheet_id, start_row, end_row), bounds);
        #[cfg(test)]
        self.col_misses.fetch_add(1, Ordering::Relaxed);
    }
}

// Phase 2 shim: in-process spill manager delegating to current graph methods.
#[derive(Default)]
pub struct ShimSpillManager {
    region_locks: RegionLockManager,
    pub(crate) active_locks: rustc_hash::FxHashMap<VertexId, u64>,
}

impl ShimSpillManager {
    pub(crate) fn reserve(
        &mut self,
        owner: VertexId,
        anchor_cell: CellRef,
        shape: SpillShape,
        _meta: SpillMeta,
    ) -> Result<(), ExcelError> {
        // Derive region from anchor + shape; enforce in-flight exclusivity only.
        let region = crate::engine::spill::Region {
            sheet_id: anchor_cell.sheet_id as u32,
            row_start: anchor_cell.coord.row(),
            row_end: anchor_cell
                .coord
                .row()
                .saturating_add(shape.rows)
                .saturating_sub(1),
            col_start: anchor_cell.coord.col(),
            col_end: anchor_cell
                .coord
                .col()
                .saturating_add(shape.cols)
                .saturating_sub(1),
        };
        match self.region_locks.reserve(region, owner) {
            Ok(id) => {
                if id != 0 {
                    self.active_locks.insert(owner, id);
                }
                Ok(())
            }
            Err(e) => Err(e),
        }
    }

    /// Release any in-flight region reservation still held for `owner`.
    ///
    /// Reservations are normally released on commit/rollback, but if an anchor is
    /// abandoned without committing (e.g. cycle detection stamps it with #CIRC), a
    /// stale reservation could remain. This is a no-op when nothing is held.
    pub(crate) fn release_owner(&mut self, owner: VertexId) {
        if let Some(id) = self.active_locks.remove(&owner) {
            self.region_locks.release(id);
        }
    }

    pub(crate) fn commit_array_with_value_probe<F>(
        &mut self,
        graph: &mut DependencyGraph,
        anchor_vertex: VertexId,
        targets: &[CellRef],
        rows: Vec<Vec<LiteralValue>>,
        overwritable_formulas: Option<&rustc_hash::FxHashSet<VertexId>>,
        mut value_probe: F,
    ) -> Result<(), ExcelError>
    where
        F: FnMut(&DependencyGraph, &CellRef) -> Option<LiteralValue>,
    {
        use formualizer_common::{ExcelErrorExtra, ExcelErrorKind};

        // Re-run plan on concrete targets before committing to respect blockers.
        // This plan checks formula/spill ownership in the graph, but when the graph value cache
        // is disabled (Arrow-canonical mode), it cannot see non-empty value blockers.
        let plan_res = graph.plan_spill_region_allowing_formula_overwrite(
            anchor_vertex,
            targets,
            overwritable_formulas,
        );
        if let Err(e) = plan_res {
            if let Some(id) = self.active_locks.remove(&anchor_vertex) {
                self.region_locks.release(id);
            }
            return Err(e);
        }

        if !graph.value_cache_enabled() {
            // Compute expected spill shape from the target rectangle for diagnostics.
            let (expected_rows, expected_cols) = if targets.is_empty() {
                (0u32, 0u32)
            } else {
                let mut min_r = u32::MAX;
                let mut max_r = 0u32;
                let mut min_c = u32::MAX;
                let mut max_c = 0u32;
                for cell in targets {
                    let r = cell.coord.row();
                    let c = cell.coord.col();
                    min_r = min_r.min(r);
                    max_r = max_r.max(r);
                    min_c = min_c.min(c);
                    max_c = max_c.max(c);
                }
                (
                    max_r.saturating_sub(min_r).saturating_add(1),
                    max_c.saturating_sub(min_c).saturating_add(1),
                )
            };

            let anchor_cell = graph
                .get_cell_ref(anchor_vertex)
                .expect("anchor cell ref for spill commit");

            for cell in targets {
                // Never treat the anchor as a blocker.
                if *cell == anchor_cell {
                    continue;
                }
                // Skip cells already known to be owned by a spill; plan() handled spill conflicts.
                if graph.spill_registry_anchor_for_cell(*cell).is_some() {
                    continue;
                }
                // Skip formula vertices in the target region; plan() handled them (or allowed).
                if let Some(&vid) = graph.get_vertex_id_for_address(cell)
                    && vid != anchor_vertex
                {
                    match graph.get_vertex_kind(vid) {
                        crate::engine::vertex::VertexKind::FormulaScalar
                        | crate::engine::vertex::VertexKind::FormulaArray => {
                            // plan() already approved allowed overwrites.
                            continue;
                        }
                        _ => {}
                    }
                }

                if let Some(v) = value_probe(graph, cell)
                    && !matches!(v, LiteralValue::Empty)
                {
                    if let Some(id) = self.active_locks.remove(&anchor_vertex) {
                        self.region_locks.release(id);
                    }
                    return Err(ExcelError::new(ExcelErrorKind::Spill)
                        .with_message("BlockedByValue")
                        .with_extra(ExcelErrorExtra::Spill {
                            expected_rows,
                            expected_cols,
                        }));
                }
            }
        }

        let commit_res = graph.commit_spill_region_atomic_with_fault(
            anchor_vertex,
            targets.to_vec(),
            rows,
            None,
        );
        if let Some(id) = self.active_locks.remove(&anchor_vertex) {
            self.region_locks.release(id);
        }
        commit_res.map(|_| ())
    }

    /// Commit a spill and mirror all written cells into Arrow overlay via the owning engine.
    pub(crate) fn commit_array_with_overlay<R: EvaluationContext>(
        &mut self,
        engine: &mut Engine<R>,
        anchor_vertex: VertexId,
        targets: &[CellRef],
        rows: Vec<Vec<LiteralValue>>,
        overwritable_formulas: Option<&rustc_hash::FxHashSet<VertexId>>,
    ) -> Result<(), ExcelError> {
        // Re-run plan on concrete targets before committing to respect blockers.
        let plan_res = engine.graph.plan_spill_region_allowing_formula_overwrite(
            anchor_vertex,
            targets,
            overwritable_formulas,
        );
        if let Err(e) = plan_res {
            if let Some(id) = self.active_locks.remove(&anchor_vertex) {
                self.region_locks.release(id);
            }
            return Err(e);
        }

        let commit_res = engine.graph.commit_spill_region_atomic_with_fault(
            anchor_vertex,
            targets.to_vec(),
            rows.clone(),
            None,
        );
        if let Some(id) = self.active_locks.remove(&anchor_vertex) {
            self.region_locks.release(id);
        }
        commit_res.map(|_| ())?;

        // Mirror into Arrow overlay when enabled
        if engine.config.arrow_storage_enabled
            && engine.config.delta_overlay_enabled
            && engine.config.write_formula_overlay_enabled
        {
            // Expect targets to be a contiguous rectangle row-major starting at some anchor
            for (idx, cell) in targets.iter().enumerate() {
                let (r_off, c_off) = {
                    if rows.is_empty() || rows[0].is_empty() {
                        (0usize, 0usize)
                    } else {
                        let width = rows[0].len();
                        (idx / width, idx % width)
                    }
                };
                let v = rows
                    .get(r_off)
                    .and_then(|r| r.get(c_off))
                    .cloned()
                    .unwrap_or(LiteralValue::Empty);
                let sheet_name = engine.graph.sheet_name(cell.sheet_id).to_string();
                engine.mirror_value_to_computed_overlay(
                    &sheet_name,
                    cell.coord.row() + 1,
                    cell.coord.col() + 1,
                    &v,
                );
            }
        }
        Ok(())
    }
}

impl<R> Engine<R>
where
    R: EvaluationContext,
{
    fn resolve_shared_ref(
        &self,
        reference: &ReferenceType,
        current_sheet: &str,
    ) -> Result<formualizer_common::SheetRef<'static>, ExcelError> {
        use formualizer_common::{
            SheetCellRef as SharedCellRef, SheetLocator, SheetRangeRef as SharedRangeRef,
            SheetRef as SharedRef,
        };

        // Preserve anchor flags from the parsed reference when possible.
        let sr = match reference {
            ReferenceType::Cell {
                sheet,
                row,
                col,
                row_abs,
                col_abs,
            } => {
                let row0 = row
                    .checked_sub(1)
                    .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref))?;
                let col0 = col
                    .checked_sub(1)
                    .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref))?;
                let sheet_loc = match sheet.as_deref() {
                    Some(name) => SheetLocator::from_name(name),
                    None => SheetLocator::Current,
                };
                let coord = formualizer_common::RelativeCoord::new(row0, col0, *row_abs, *col_abs);
                SharedRef::Cell(SharedCellRef::new(sheet_loc, coord))
            }
            ReferenceType::Range {
                sheet,
                start_row,
                start_col,
                end_row,
                end_col,
                start_row_abs,
                start_col_abs,
                end_row_abs,
                end_col_abs,
            } => {
                let sheet_loc = match sheet.as_deref() {
                    Some(name) => SheetLocator::from_name(name),
                    None => SheetLocator::Current,
                };
                let sr = start_row
                    .map(|r| {
                        r.checked_sub(1)
                            .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref))
                    })
                    .transpose()?;
                let sc = start_col
                    .map(|c| {
                        c.checked_sub(1)
                            .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref))
                    })
                    .transpose()?;
                let er = end_row
                    .map(|r| {
                        r.checked_sub(1)
                            .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref))
                    })
                    .transpose()?;
                let ec = end_col
                    .map(|c| {
                        c.checked_sub(1)
                            .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref))
                    })
                    .transpose()?;
                let range = SharedRangeRef::from_parts(
                    sheet_loc,
                    sr.map(|idx| formualizer_common::AxisBound::new(idx, *start_row_abs)),
                    sc.map(|idx| formualizer_common::AxisBound::new(idx, *start_col_abs)),
                    er.map(|idx| formualizer_common::AxisBound::new(idx, *end_row_abs)),
                    ec.map(|idx| formualizer_common::AxisBound::new(idx, *end_col_abs)),
                )
                .map_err(|_| ExcelError::new(ExcelErrorKind::Ref))?;
                SharedRef::Range(range)
            }
            _ => return Err(ExcelError::new(ExcelErrorKind::Ref)),
        };

        let current_id = self
            .graph
            .sheet_id(current_sheet)
            .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref))?;

        let resolve_loc = |loc: SheetLocator<'_>| -> Result<SheetLocator<'static>, ExcelError> {
            match loc {
                SheetLocator::Current => Ok(SheetLocator::Id(current_id)),
                SheetLocator::Id(id) => Ok(SheetLocator::Id(id)),
                SheetLocator::Name(name) => {
                    let n = name.as_ref();
                    self.graph
                        .sheet_id(n)
                        .map(SheetLocator::Id)
                        .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref))
                }
            }
        };

        match sr {
            SharedRef::Cell(cell) => {
                let owned = cell.into_owned();
                let sheet = resolve_loc(owned.sheet)?;
                Ok(SharedRef::Cell(SharedCellRef::new(sheet, owned.coord)))
            }
            SharedRef::Range(range) => {
                let owned = range.into_owned();
                let sheet = resolve_loc(owned.sheet)?;
                Ok(SharedRef::Range(SharedRangeRef {
                    sheet,
                    start_row: owned.start_row,
                    start_col: owned.start_col,
                    end_row: owned.end_row,
                    end_col: owned.end_col,
                }))
            }
        }
    }
}

// Implement the resolver traits for the Engine.
// This allows the interpreter to resolve references by querying the engine's graph.
impl<R> crate::traits::ReferenceResolver for Engine<R>
where
    R: EvaluationContext,
{
    fn resolve_cell_reference(
        &self,
        sheet: Option<&str>,
        row: u32,
        col: u32,
    ) -> Result<LiteralValue, ExcelError> {
        // This context-free trait method has no knowledge of the formula's
        // current sheet, so an unqualified (`None`) reference cannot be resolved
        // here. Previously this fell back to `default_sheet_name()`, which leaked
        // the reference onto an unrelated sheet (issue #110). Interpreter paths
        // already qualify references with the current sheet before reaching this
        // method (see `Interpreter::implicit_intersection_from_reference`), and
        // the sheet-aware scalar path goes through `resolve_cell_reference_value`
        // with an explicit `current_sheet`. Returning #REF! for an unqualified
        // reference here surfaces the missing context instead of silently
        // returning data from the wrong sheet.
        let Some(sheet_name) = sheet else {
            return Err(ExcelError::new(ExcelErrorKind::Ref).with_message(
                "Unqualified cell reference resolved without sheet context".to_string(),
            ));
        };
        // Prefer engine's unified accessor which consults Arrow store for base values
        // and falls back to graph for formulas and stored values.
        if let Some(v) = self.get_cell_value(sheet_name, row, col) {
            Ok(v)
        } else {
            // Excel semantics: empty cell coerces to 0 in numeric contexts
            Ok(LiteralValue::Number(0.0))
        }
    }
}

impl<R> crate::traits::RangeResolver for Engine<R>
where
    R: EvaluationContext,
{
    fn resolve_range_reference(
        &self,
        sheet: Option<&str>,
        sr: Option<u32>,
        sc: Option<u32>,
        er: Option<u32>,
        ec: Option<u32>,
    ) -> Result<Box<dyn crate::traits::Range>, ExcelError> {
        // For now, delegate range resolution to the external resolver.
        // A future optimization could be to handle this within the graph.
        self.resolver.resolve_range_reference(sheet, sr, sc, er, ec)
    }
}

impl<R> crate::traits::NamedRangeResolver for Engine<R>
where
    R: EvaluationContext,
{
    fn resolve_named_range_reference(
        &self,
        name: &str,
    ) -> Result<Vec<Vec<LiteralValue>>, ExcelError> {
        self.resolver.resolve_named_range_reference(name)
    }
}

impl<R> crate::traits::TableResolver for Engine<R>
where
    R: EvaluationContext,
{
    fn resolve_table_reference(
        &self,
        tref: &formualizer_parse::parser::TableReference,
    ) -> Result<Box<dyn crate::traits::Table>, ExcelError> {
        self.resolver.resolve_table_reference(tref)
    }
}

impl<R> crate::traits::SourceResolver for Engine<R>
where
    R: EvaluationContext,
{
    fn source_scalar_version(&self, name: &str) -> Option<u64> {
        self.resolver.source_scalar_version(name)
    }

    fn resolve_source_scalar(&self, name: &str) -> Result<LiteralValue, ExcelError> {
        self.resolver.resolve_source_scalar(name)
    }

    fn source_table_version(&self, name: &str) -> Option<u64> {
        self.resolver.source_table_version(name)
    }

    fn resolve_source_table(
        &self,
        name: &str,
    ) -> Result<Box<dyn crate::traits::Table>, ExcelError> {
        self.resolver.resolve_source_table(name)
    }
}

// The Engine is a Resolver because it implements the constituent traits.
impl<R> crate::traits::Resolver for Engine<R> where R: EvaluationContext {}

// The Engine provides functions by delegating to its internal resolver.
impl<R> crate::traits::FunctionProvider for Engine<R>
where
    R: EvaluationContext,
{
    fn planning_semantic_revision(&self) -> Option<u64> {
        self.resolver.planning_semantic_revision()
    }

    fn get_function(
        &self,
        prefix: &str,
        name: &str,
    ) -> Option<std::sync::Arc<dyn crate::function::Function>> {
        self.resolver.get_function(prefix, name)
    }

    fn get_function_for_planning(
        &self,
        prefix: &str,
        name: &str,
    ) -> Option<std::sync::Arc<dyn crate::function::Function>> {
        self.resolver.get_function_for_planning(prefix, name)
    }
}

impl<R> Engine<R>
where
    R: EvaluationContext,
{
    /// Semantic used coordinates exclude graph-only dependency placeholders.
    ///
    /// Non-empty base/overlay/computed cells come from Arrow storage, while
    /// scalar and array formulas come from graph formula kinds even before
    /// their results are materialized. The legacy graph fallback is omitted:
    /// `load_packed_to_vertex` entries are either represented by those sources
    /// or are `Empty` dependency placeholders, not a third value authority.
    pub(crate) fn semantic_used_rows_for_columns(
        &self,
        sheet: &str,
        start_col: u32,
        end_col: u32,
    ) -> Option<(u32, u32)> {
        let arrow_bounds = self
            .sheet_store()
            .sheet(sheet)
            .and_then(|_| self.arrow_used_row_bounds(sheet, start_col, end_col));
        let formula_bounds = self.formula_row_bounds_for_columns(sheet, start_col, end_col);
        Self::union_used_bounds(arrow_bounds, formula_bounds)
    }

    pub(crate) fn semantic_used_cols_for_rows(
        &self,
        sheet: &str,
        start_row: u32,
        end_row: u32,
    ) -> Option<(u32, u32)> {
        let arrow_bounds = self
            .sheet_store()
            .sheet(sheet)
            .and_then(|_| self.arrow_used_col_bounds(sheet, start_row, end_row));
        let formula_bounds = self.formula_col_bounds_for_rows(sheet, start_row, end_row);
        Self::union_used_bounds(arrow_bounds, formula_bounds)
    }
}

// Override EvaluationContext to provide thread pool access
impl<R> crate::traits::EvaluationContext for Engine<R>
where
    R: EvaluationContext,
{
    fn clock(&self) -> &dyn crate::timezone::ClockProvider {
        &self.clock
    }

    fn thread_pool(&self) -> Option<&Arc<rayon::ThreadPool>> {
        self.thread_pool.as_ref()
    }

    fn cancellation_token(&self) -> Option<crate::engine::CancelToken> {
        self.active_cancel_flag.clone()
    }

    fn chunk_hint(&self) -> Option<usize> {
        // Use a simple heuristic from configuration (stripe width * height) as a default hint.
        let hint =
            (self.config.stripe_height as usize).saturating_mul(self.config.stripe_width as usize);
        Some(hint.clamp(1024, 1 << 20)) // clamp between 1K and ~1M
    }

    fn volatile_level(&self) -> crate::traits::VolatileLevel {
        self.config.volatile_level
    }

    fn workbook_seed(&self) -> u64 {
        self.config.workbook_seed
    }

    fn recalc_epoch(&self) -> u64 {
        self.recalc_epoch
    }

    fn workbook_sheet_count(&self) -> Option<usize> {
        Some(self.graph.sheet_reg().active_len())
    }

    fn sheet_index_by_name(&self, sheet: &str) -> Option<usize> {
        self.graph.sheet_reg().active_position(sheet)
    }

    fn current_sheet_index(&self, current_sheet: &str) -> Option<usize> {
        self.sheet_index_by_name(current_sheet)
    }

    fn inspect_reference(
        &self,
        reference: &ReferenceType,
        current_sheet: &str,
    ) -> Result<Option<ReferenceInfo>, ExcelError> {
        let sheet_info = |sheet_name: &str| -> Result<(SheetId, usize), ExcelError> {
            let sheet_id = self
                .graph
                .sheet_id(sheet_name)
                .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref))?;
            let sheet_index = self
                .graph
                .sheet_reg()
                .active_position_by_id(sheet_id)
                .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref))?;
            Ok((sheet_id, sheet_index))
        };

        let cell_info =
            |sheet_name: &str, row: u32, col: u32| -> Result<ReferenceInfo, ExcelError> {
                let (sheet_id, sheet_index) = sheet_info(sheet_name)?;
                let row0 = row
                    .checked_sub(1)
                    .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref))?;
                let col0 = col
                    .checked_sub(1)
                    .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref))?;
                Ok(ReferenceInfo {
                    first_sheet_index: Some(sheet_index),
                    sheet_count: Some(1),
                    first_cell: Some(CellRef::new(sheet_id, Coord::new(row0, col0, true, true))),
                })
            };

        let range_info = |sheet_name: &str,
                          start_row: Option<u32>,
                          start_col: Option<u32>|
         -> Result<ReferenceInfo, ExcelError> {
            let (sheet_id, sheet_index) = sheet_info(sheet_name)?;
            let row = start_row.unwrap_or(1);
            let col = start_col.unwrap_or(1);
            let row0 = row
                .checked_sub(1)
                .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref))?;
            let col0 = col
                .checked_sub(1)
                .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref))?;
            Ok(ReferenceInfo {
                first_sheet_index: Some(sheet_index),
                sheet_count: Some(1),
                first_cell: Some(CellRef::new(sheet_id, Coord::new(row0, col0, true, true))),
            })
        };

        let info = match reference {
            ReferenceType::Cell {
                sheet, row, col, ..
            } => {
                let sheet_name = sheet.as_deref().unwrap_or(current_sheet);
                cell_info(sheet_name, *row, *col)?
            }
            ReferenceType::Range {
                sheet,
                start_row,
                start_col,
                ..
            } => {
                let sheet_name = sheet.as_deref().unwrap_or(current_sheet);
                range_info(sheet_name, *start_row, *start_col)?
            }
            ReferenceType::Cell3D {
                sheet_first,
                sheet_last,
                row,
                col,
                ..
            } => {
                let first = cell_info(sheet_first, *row, *col)?;
                ReferenceInfo {
                    first_sheet_index: first.first_sheet_index,
                    sheet_count: self
                        .graph
                        .sheet_reg()
                        .active_span_len(sheet_first, sheet_last),
                    first_cell: first.first_cell,
                }
            }
            ReferenceType::Range3D {
                sheet_first,
                sheet_last,
                start_row,
                start_col,
                ..
            } => {
                let first = range_info(sheet_first, *start_row, *start_col)?;
                ReferenceInfo {
                    first_sheet_index: first.first_sheet_index,
                    sheet_count: self
                        .graph
                        .sheet_reg()
                        .active_span_len(sheet_first, sheet_last),
                    first_cell: first.first_cell,
                }
            }
            ReferenceType::NamedRange(name) => {
                let current_id = self
                    .graph
                    .sheet_id(current_sheet)
                    .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref))?;
                let named = self
                    .graph
                    .resolve_name_entry(name, current_id)
                    .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref))?;
                match &named.definition {
                    NamedDefinition::Cell(cell) => ReferenceInfo {
                        first_sheet_index: self
                            .graph
                            .sheet_reg()
                            .active_position_by_id(cell.sheet_id),
                        sheet_count: Some(1),
                        first_cell: Some(*cell),
                    },
                    NamedDefinition::Range(range) => ReferenceInfo {
                        first_sheet_index: self
                            .graph
                            .sheet_reg()
                            .active_position_by_id(range.start.sheet_id),
                        sheet_count: Some(1),
                        first_cell: Some(range.start),
                    },
                    NamedDefinition::Literal(_) | NamedDefinition::Formula { .. } => {
                        ReferenceInfo {
                            first_sheet_index: None,
                            sheet_count: None,
                            first_cell: None,
                        }
                    }
                }
            }
            ReferenceType::Table(tref) => {
                let table = self
                    .graph
                    .resolve_table_entry(&tref.name)
                    .ok_or_else(|| ExcelError::new(ExcelErrorKind::Ref))?;
                ReferenceInfo {
                    first_sheet_index: self
                        .graph
                        .sheet_reg()
                        .active_position_by_id(table.range.start.sheet_id),
                    sheet_count: Some(1),
                    first_cell: Some(table.range.start),
                }
            }
            ReferenceType::External(_) => return Err(ExcelError::new(ExcelErrorKind::Ref)),
        };

        Ok(Some(info))
    }

    fn formula_text_at_cell(&self, cell: CellRef) -> Result<Option<String>, ExcelError> {
        let sheet_name = self.graph.sheet_name(cell.sheet_id);
        if sheet_name.is_empty() {
            return Err(ExcelError::new(ExcelErrorKind::Ref));
        }
        let row = cell.coord.row() + 1;
        let col = cell.coord.col() + 1;

        if let Some(entries) = self.staged_formulas.get(sheet_name)
            && let Some(text) = entries.get(row, col)
        {
            return Ok(Some(if text.starts_with('=') {
                text.to_owned()
            } else {
                format!("={text}")
            }));
        }

        let Some((Some(ast), _)) = self.get_cell(sheet_name, row, col) else {
            return Ok(None);
        };
        Ok(Some(formualizer_parse::pretty::canonical_formula(&ast)))
    }

    fn used_rows_for_columns(
        &self,
        sheet: &str,
        start_col: u32,
        end_col: u32,
    ) -> Option<(u32, u32)> {
        // Union Arrow-backed used-region with formula rows that have not been materialized yet.
        let sheet_id = self.graph.sheet_id(sheet)?;
        let snap = self.data_snapshot_id();
        if let Some(cached) = self.used_axis_bounds_cache.read().ok().and_then(|guard| {
            guard
                .as_ref()
                .and_then(|cache| cache.get_row_bounds(sheet_id, start_col, end_col, snap))
        }) {
            return cached;
        }

        let arrow_bounds = self
            .sheet_store()
            .sheet(sheet)
            .and_then(|_| self.arrow_used_row_bounds(sheet, start_col, end_col));
        let formula_bounds = self.formula_row_bounds_for_columns(sheet, start_col, end_col);
        let computed = if let Some(bounds) = Self::union_used_bounds(arrow_bounds, formula_bounds) {
            Some(bounds)
        } else {
            let sc0 = start_col.saturating_sub(1);
            let ec0 = end_col.saturating_sub(1);
            self.graph
                .used_row_bounds_for_columns(sheet_id, sc0, ec0)
                .map(|(a0, b0)| (a0 + 1, b0 + 1))
        };

        if let Ok(mut guard) = self.used_axis_bounds_cache.write() {
            guard
                .get_or_insert_with(|| UsedAxisBoundsCache::new(snap))
                .put_row_bounds(sheet_id, start_col, end_col, snap, computed);
        }

        computed
    }

    fn used_cols_for_rows(&self, sheet: &str, start_row: u32, end_row: u32) -> Option<(u32, u32)> {
        // Union Arrow-backed used-region with formula columns that have not been materialized yet.
        let sheet_id = self.graph.sheet_id(sheet)?;
        let snap = self.data_snapshot_id();
        if let Some(cached) = self.used_axis_bounds_cache.read().ok().and_then(|guard| {
            guard
                .as_ref()
                .and_then(|cache| cache.get_col_bounds(sheet_id, start_row, end_row, snap))
        }) {
            return cached;
        }

        let arrow_bounds = self
            .sheet_store()
            .sheet(sheet)
            .and_then(|_| self.arrow_used_col_bounds(sheet, start_row, end_row));
        let formula_bounds = self.formula_col_bounds_for_rows(sheet, start_row, end_row);
        let computed = if let Some(bounds) = Self::union_used_bounds(arrow_bounds, formula_bounds) {
            Some(bounds)
        } else {
            let sr0 = start_row.saturating_sub(1);
            let er0 = end_row.saturating_sub(1);
            self.graph
                .used_col_bounds_for_rows(sheet_id, sr0, er0)
                .map(|(a0, b0)| (a0 + 1, b0 + 1))
        };

        if let Ok(mut guard) = self.used_axis_bounds_cache.write() {
            guard
                .get_or_insert_with(|| UsedAxisBoundsCache::new(snap))
                .put_col_bounds(sheet_id, start_row, end_row, snap, computed);
        }

        computed
    }

    fn sheet_bounds(&self, sheet: &str) -> Option<(u32, u32)> {
        let _ = self.graph.sheet_id(sheet)?;
        // Excel-like upper bounds; we expose something finite but large.
        // Backends may override with real bounds.
        Some((1_048_576, 16_384)) // 1048576 rows, 16384 cols (XFD)
    }

    fn data_snapshot_id(&self) -> u64 {
        self.snapshot_id.load(std::sync::atomic::Ordering::Relaxed)
    }

    fn backend_caps(&self) -> crate::traits::BackendCaps {
        crate::traits::BackendCaps {
            streaming: true,
            used_region: true,
            write: false,
            tables: false,
            async_stream: false,
        }
    }

    fn build_lookup_index(
        &self,
        view: &RangeView<'_>,
        axis: LookupAxis,
    ) -> Option<Arc<LookupIndex>> {
        self.build_lookup_index_impl(view, axis)
    }

    // Flats removed

    fn date_system(&self) -> crate::engine::DateSystem {
        self.config.date_system
    }
    /// New: resolve a reference into a RangeView (Phase 2 API)
    fn resolve_range_view<'c>(
        &'c self,
        reference: &ReferenceType,
        current_sheet: &str,
    ) -> Result<RangeView<'c>, ExcelError> {
        match reference {
            ReferenceType::External(ext) => {
                let name = ext.raw.as_str();
                match ext.kind {
                    formualizer_parse::parser::ExternalRefKind::Cell { .. } => {
                        let Some(source) = self.graph.resolve_source_scalar_entry(name) else {
                            return Err(ExcelError::new(ExcelErrorKind::Name)
                                .with_message(format!("Undefined name: {name}")));
                        };
                        let version = source
                            .version
                            .or_else(|| self.resolver.source_scalar_version(name));
                        let v = self.resolve_source_scalar_cached(name, version)?;
                        Ok(RangeView::from_owned_rows(
                            vec![vec![v]],
                            self.config.date_system,
                        ))
                    }
                    formualizer_parse::parser::ExternalRefKind::Range { .. } => {
                        let Some(source) = self.graph.resolve_source_table_entry(name) else {
                            return Err(ExcelError::new(ExcelErrorKind::Name)
                                .with_message(format!("Undefined table: {name}")));
                        };
                        let version = source
                            .version
                            .or_else(|| self.resolver.source_table_version(name));
                        let table = self.resolve_source_table_cached(name, version)?;
                        let spec = Some(formualizer_parse::parser::TableSpecifier::Data);
                        self.source_table_to_range_view(table.as_ref(), &spec)
                    }
                }
            }
            ReferenceType::Range { .. } => {
                let shared = self.resolve_shared_ref(reference, current_sheet)?;
                let formualizer_common::SheetRef::Range(range) = shared else {
                    return Err(ExcelError::new(ExcelErrorKind::Ref));
                };
                let sheet_id = match range.sheet {
                    formualizer_common::SheetLocator::Id(id) => id,
                    _ => return Err(ExcelError::new(ExcelErrorKind::Ref)),
                };
                let sheet_name = self.graph.sheet_name(sheet_id);

                let bounded_range = if range.start_row.is_some()
                    && range.start_col.is_some()
                    && range.end_row.is_some()
                    && range.end_col.is_some()
                {
                    Some(RangeRef::try_from_shared(range.as_ref())?)
                } else {
                    None
                };

                let sr = bounded_range
                    .as_ref()
                    .map(|r| r.start.coord.row() + 1)
                    .or_else(|| range.start_row.map(|b| b.index + 1));
                let sc = bounded_range
                    .as_ref()
                    .map(|r| r.start.coord.col() + 1)
                    .or_else(|| range.start_col.map(|b| b.index + 1));
                let er = bounded_range
                    .as_ref()
                    .map(|r| r.end.coord.row() + 1)
                    .or_else(|| range.end_row.map(|b| b.index + 1));
                let ec = bounded_range
                    .as_ref()
                    .map(|r| r.end.coord.col() + 1)
                    .or_else(|| range.end_col.map(|b| b.index + 1));

                let extent = resolve_used_extent_with_fallback(
                    OpenRangeBounds {
                        start_row: sr,
                        start_column: sc,
                        end_row: er,
                        end_column: ec,
                    },
                    ExtentPolicy::EvaluationCompat {
                        fallback_row: None,
                        fallback_column: None,
                    },
                    || {
                        self.sheet_bounds(sheet_name)
                            .map(|_| self.config.max_open_ended_rows)
                    },
                    || {
                        self.sheet_bounds(sheet_name)
                            .map(|_| self.config.max_open_ended_cols)
                    },
                    |first, last| self.used_rows_for_columns(sheet_name, first, last),
                    |first, last| self.used_cols_for_rows(sheet_name, first, last),
                );
                let (sr, sc, er, ec) = extent
                    .map(|extent| {
                        (
                            extent.start_row,
                            extent.start_column,
                            extent.end_row,
                            extent.end_column,
                        )
                    })
                    .unwrap_or((1, 1, 0, 0));

                if self.force_materialize_range_views {
                    if er < sr || ec < sc {
                        return Ok(RangeView::from_owned_rows(
                            Vec::new(),
                            self.config.date_system,
                        ));
                    }
                    let h = (er - sr + 1) as u64;
                    let w = (ec - sc + 1) as u64;
                    let cell_count = h.saturating_mul(w);
                    if cell_count <= self.config.spill.max_spill_cells as u64 {
                        let mut rows: Vec<Vec<LiteralValue>> = Vec::with_capacity(h as usize);
                        for r in sr..=er {
                            let mut rowv: Vec<LiteralValue> = Vec::with_capacity(w as usize);
                            for c in sc..=ec {
                                rowv.push(
                                    self.get_cell_value(sheet_name, r, c)
                                        .unwrap_or(LiteralValue::Empty),
                                );
                            }
                            rows.push(rowv);
                        }
                        return Ok(RangeView::from_owned_rows(rows, self.config.date_system));
                    }
                }

                let Some(asheet) = self.sheet_store().sheet(sheet_name) else {
                    return Ok(RangeView::from_owned_rows(
                        Vec::new(),
                        self.config.date_system,
                    ));
                };

                let rv = if er < sr || ec < sc {
                    asheet.range_view(1, 1, 0, 0)
                } else {
                    let sr0 = sr.saturating_sub(1) as usize;
                    let sc0 = sc.saturating_sub(1) as usize;
                    let er0 = er.saturating_sub(1) as usize;
                    let ec0 = ec.saturating_sub(1) as usize;
                    asheet.range_view(sr0, sc0, er0, ec0)
                };

                Ok(rv)
            }
            ReferenceType::Cell { .. } => {
                let shared = self.resolve_shared_ref(reference, current_sheet)?;
                let formualizer_common::SheetRef::Cell(cell) = shared else {
                    return Err(ExcelError::new(ExcelErrorKind::Ref));
                };
                let addr = CellRef::try_from_shared(cell)?;
                let sheet_id = addr.sheet_id;
                let sheet_name = self.graph.sheet_name(sheet_id);
                let row = addr.coord.row() + 1;
                let col = addr.coord.col() + 1;

                if self.force_materialize_range_views {
                    let v = self
                        .get_cell_value(sheet_name, row, col)
                        .unwrap_or(LiteralValue::Empty);
                    return Ok(RangeView::from_owned_rows(
                        vec![vec![v]],
                        self.config.date_system,
                    ));
                }

                if let Some(asheet) = self.sheet_store().sheet(sheet_name) {
                    let r0 = row.saturating_sub(1) as usize;
                    let c0 = col.saturating_sub(1) as usize;
                    let rv = asheet.range_view(r0, c0, r0, c0);
                    Ok(rv)
                } else {
                    let v = self
                        .get_cell_value(sheet_name, row, col)
                        .unwrap_or(LiteralValue::Empty);
                    Ok(RangeView::from_owned_rows(
                        vec![vec![v]],
                        self.config.date_system,
                    ))
                }
            }
            ReferenceType::NamedRange(name) => {
                if let Some(current_id) = self.graph.sheet_id(current_sheet)
                    && let Some(named) = self.graph.resolve_name_entry(name, current_id)
                {
                    match &named.definition {
                        NamedDefinition::Cell(cell_ref) => {
                            let sheet_name = self.graph.sheet_name(cell_ref.sheet_id);
                            if self.force_materialize_range_views {
                                let v = self
                                    .get_cell_value(
                                        sheet_name,
                                        cell_ref.coord.row() + 1,
                                        cell_ref.coord.col() + 1,
                                    )
                                    .unwrap_or(LiteralValue::Empty);
                                return Ok(RangeView::from_owned_rows(
                                    vec![vec![v]],
                                    self.config.date_system,
                                ));
                            } else {
                                let asheet = self
                                    .sheet_store()
                                    .sheet(sheet_name)
                                    .expect("Arrow sheet missing for named cell");
                                let r0 = cell_ref.coord.row() as usize;
                                let c0 = cell_ref.coord.col() as usize;
                                let rv = asheet.range_view(r0, c0, r0, c0);
                                return Ok(rv);
                            }
                        }
                        NamedDefinition::Range(range_ref) => {
                            let sheet_name = self.graph.sheet_name(range_ref.start.sheet_id);
                            let sr = range_ref.start.coord.row() + 1;
                            let sc = range_ref.start.coord.col() + 1;
                            let er = range_ref.end.coord.row() + 1;
                            let ec = range_ref.end.coord.col() + 1;
                            if self.force_materialize_range_views {
                                let h = (er.saturating_sub(sr) + 1) as u64;
                                let w = (ec.saturating_sub(sc) + 1) as u64;
                                let cell_count = h.saturating_mul(w);
                                if cell_count <= self.config.spill.max_spill_cells as u64 {
                                    let mut rows: Vec<Vec<LiteralValue>> =
                                        Vec::with_capacity(h as usize);
                                    for r in sr..=er {
                                        let mut rowv: Vec<LiteralValue> =
                                            Vec::with_capacity(w as usize);
                                        for c in sc..=ec {
                                            rowv.push(
                                                self.get_cell_value(sheet_name, r, c)
                                                    .unwrap_or(LiteralValue::Empty),
                                            );
                                        }
                                        rows.push(rowv);
                                    }
                                    return Ok(RangeView::from_owned_rows(
                                        rows,
                                        self.config.date_system,
                                    ));
                                }
                            }
                            let asheet = self
                                .sheet_store()
                                .sheet(sheet_name)
                                .expect("Arrow sheet missing for named range");
                            let sr0 = range_ref.start.coord.row() as usize;
                            let sc0 = range_ref.start.coord.col() as usize;
                            let er0 = range_ref.end.coord.row() as usize;
                            let ec0 = range_ref.end.coord.col() as usize;
                            let rv = asheet.range_view(sr0, sc0, er0, ec0);
                            return Ok(rv);
                        }
                        NamedDefinition::Literal(v) => {
                            return Ok(RangeView::from_owned_rows(
                                vec![vec![v.clone()]],
                                self.config.date_system,
                            ));
                        }
                        NamedDefinition::Formula { .. } => {
                            if let Some(value) = self.graph.get_value(named.vertex) {
                                return Ok(RangeView::from_owned_rows(
                                    vec![vec![value]],
                                    self.config.date_system,
                                ));
                            }
                        }
                    }
                }

                if let Some(source) = self.graph.resolve_source_scalar_entry(name) {
                    let version = source
                        .version
                        .or_else(|| self.resolver.source_scalar_version(name));
                    let v = self.resolve_source_scalar_cached(name, version)?;
                    return Ok(RangeView::from_owned_rows(
                        vec![vec![v]],
                        self.config.date_system,
                    ));
                }

                let data = self.resolver.resolve_named_range_reference(name)?;
                Ok(RangeView::from_owned_rows(data, self.config.date_system))
            }
            ReferenceType::Table(tref) => {
                if let Some(table) = self.graph.resolve_table_entry(&tref.name) {
                    let sheet_name = self.graph.sheet_name(table.range.start.sheet_id);
                    let asheet = self
                        .sheet_store()
                        .sheet(sheet_name)
                        .expect("Arrow sheet missing for table reference");

                    let sr0 = table.range.start.coord.row() as usize;
                    let sc0 = table.range.start.coord.col() as usize;
                    let er0 = table.range.end.coord.row() as usize;
                    let ec0 = table.range.end.coord.col() as usize;

                    let has_totals = table.totals_row;
                    let has_headers = table.header_row;
                    let data_sr = if has_headers {
                        sr0.saturating_add(1)
                    } else {
                        sr0
                    };
                    let data_er = if has_totals {
                        er0.saturating_sub(1)
                    } else {
                        er0
                    };

                    let select = |sr: usize, sc: usize, er: usize, ec: usize| {
                        if sr > er || sc > ec {
                            asheet.range_view(1, 1, 0, 0)
                        } else {
                            asheet.range_view(sr, sc, er, ec)
                        }
                    };

                    let av = match &tref.specifier {
                        None => {
                            return Err(ExcelError::new(ExcelErrorKind::NImpl).with_message(
                                "Table reference without specifier is unsupported".to_string(),
                            ));
                        }
                        Some(formualizer_parse::parser::TableSpecifier::Column(col)) => {
                            let Some(idx) = table.col_index(col) else {
                                return Err(ExcelError::new(ExcelErrorKind::Ref).with_message(
                                    "Column refers to unknown table column".to_string(),
                                ));
                            };
                            let c0 = sc0 + idx;
                            select(data_sr, c0, data_er, c0)
                        }
                        Some(formualizer_parse::parser::TableSpecifier::ColumnRange(
                            start,
                            end,
                        )) => {
                            let Some(si) = table.col_index(start) else {
                                return Err(ExcelError::new(ExcelErrorKind::Ref).with_message(
                                    "Column range refers to unknown column(s)".to_string(),
                                ));
                            };
                            let Some(ei) = table.col_index(end) else {
                                return Err(ExcelError::new(ExcelErrorKind::Ref).with_message(
                                    "Column range refers to unknown column(s)".to_string(),
                                ));
                            };
                            let (mut a, mut b) = (si, ei);
                            if a > b {
                                std::mem::swap(&mut a, &mut b);
                            }
                            let c_start = sc0 + a;
                            let c_end = sc0 + b;
                            select(data_sr, c_start, data_er, c_end)
                        }
                        Some(formualizer_parse::parser::TableSpecifier::All)
                        | Some(formualizer_parse::parser::TableSpecifier::SpecialItem(
                            formualizer_parse::parser::SpecialItem::All,
                        )) => select(sr0, sc0, er0, ec0),
                        Some(formualizer_parse::parser::TableSpecifier::Data)
                        | Some(formualizer_parse::parser::TableSpecifier::SpecialItem(
                            formualizer_parse::parser::SpecialItem::Data,
                        )) => select(data_sr, sc0, data_er, ec0),
                        Some(formualizer_parse::parser::TableSpecifier::Headers)
                        | Some(formualizer_parse::parser::TableSpecifier::SpecialItem(
                            formualizer_parse::parser::SpecialItem::Headers,
                        )) => {
                            if !has_headers {
                                asheet.range_view(1, 1, 0, 0)
                            } else {
                                select(sr0, sc0, sr0, ec0)
                            }
                        }
                        Some(formualizer_parse::parser::TableSpecifier::Totals)
                        | Some(formualizer_parse::parser::TableSpecifier::SpecialItem(
                            formualizer_parse::parser::SpecialItem::Totals,
                        )) => {
                            if !has_totals {
                                asheet.range_view(1, 1, 0, 0)
                            } else {
                                select(er0, sc0, er0, ec0)
                            }
                        }
                        Some(formualizer_parse::parser::TableSpecifier::SpecialItem(
                            formualizer_parse::parser::SpecialItem::ThisRow,
                        )) => {
                            return Err(ExcelError::new(ExcelErrorKind::NImpl).with_message(
                                "@ (This Row) requires table-aware context; not yet supported"
                                    .to_string(),
                            ));
                        }
                        Some(formualizer_parse::parser::TableSpecifier::Row(_))
                        | Some(formualizer_parse::parser::TableSpecifier::Combination(_)) => {
                            return Err(ExcelError::new(ExcelErrorKind::NImpl).with_message(
                                "Complex structured references not yet supported".to_string(),
                            ));
                        }
                    };

                    return Ok(av);
                }

                if let Some(source) = self.graph.resolve_source_table_entry(&tref.name) {
                    let version = source
                        .version
                        .or_else(|| self.resolver.source_table_version(&tref.name));
                    let table = self.resolve_source_table_cached(&tref.name, version)?;
                    return self.source_table_to_range_view(table.as_ref(), &tref.specifier);
                }

                // Fallback: materialize via Resolver::resolve_range_like tranche 1
                let boxed = self.resolve_range_like(&ReferenceType::Table(tref.clone()))?;
                let owned = boxed.materialise().into_owned();
                Ok(RangeView::from_owned_rows(owned, self.config.date_system))
            }
            ReferenceType::Cell3D { .. } | ReferenceType::Range3D { .. } => {
                Err(ExcelError::new(ExcelErrorKind::NImpl)
                    .with_message("3D references are not yet supported".to_string()))
            }
        }
    }

    fn resolve_cell_reference_value(
        &self,
        sheet: Option<&str>,
        row: u32,
        col: u32,
        current_sheet: &str,
    ) -> Result<LiteralValue, ExcelError> {
        let sheet_name = sheet.unwrap_or(current_sheet);
        if self.graph.sheet_id(sheet_name).is_none() {
            return Err(ExcelError::new(ExcelErrorKind::Ref));
        }
        Ok(self
            .get_cell_value(sheet_name, row, col)
            .unwrap_or(LiteralValue::Empty))
    }

    fn build_criteria_mask(
        &self,
        view: &RangeView<'_>,
        col_in_view: usize,
        pred: &crate::args::CriteriaPredicate,
    ) -> Option<std::sync::Arc<arrow_array::BooleanArray>> {
        if view.dims().1 == 0 {
            return None;
        }
        // If the view is logically open-ended but the backing sheet has no physical rows,
        // treat the mask as empty (0-len) rather than attempting to build a huge mask.
        let sheet_rows = view.sheet().nrows as usize;
        if sheet_rows == 0 || view.start_row() >= sheet_rows {
            return Some(std::sync::Arc::new(arrow_array::BooleanArray::new_null(0)));
        }
        compute_criteria_mask(view, col_in_view, pred)
    }

    fn build_row_visibility_mask(
        &self,
        view: &RangeView<'_>,
        mode: VisibilityMaskMode,
    ) -> Option<std::sync::Arc<arrow_array::BooleanArray>> {
        self.build_row_visibility_mask_for_view(view, mode)
    }
}

impl<R> Engine<R>
where
    R: EvaluationContext,
{
    fn clear_spill_projection_and_mirror(
        &mut self,
        anchor_vertex: VertexId,
        delta: Option<&mut DeltaCollector>,
    ) {
        let spill_cells = self
            .graph
            .spill_cells_for_anchor(anchor_vertex)
            .map(|cells| cells.to_vec())
            .unwrap_or_default();
        if spill_cells.is_empty() {
            return;
        }

        if let Some(delta) = delta
            && delta.mode != DeltaMode::Off
        {
            let empty = LiteralValue::Empty;
            for cell in spill_cells.iter() {
                let sheet_name = self.graph.sheet_name(cell.sheet_id);
                let old = self
                    .get_cell_value(sheet_name, cell.coord.row() + 1, cell.coord.col() + 1)
                    .unwrap_or(LiteralValue::Empty);
                if old != empty {
                    delta.record_cell(cell.sheet_id, cell.coord.row(), cell.coord.col());
                }
            }
        }

        self.graph.clear_spill_region(anchor_vertex);
        if let Some(scope) = Self::formula_plane_region_from_cells(&spill_cells) {
            self.record_formula_plane_structural_change(scope);
        }

        if self.config.arrow_storage_enabled
            && self.config.delta_overlay_enabled
            && self.config.write_formula_overlay_enabled
        {
            let empty = LiteralValue::Empty;
            for cell in spill_cells.iter() {
                let sheet_name = self.graph.sheet_name(cell.sheet_id).to_string();
                self.mirror_value_to_computed_overlay(
                    &sheet_name,
                    cell.coord.row() + 1,
                    cell.coord.col() + 1,
                    &empty,
                );
            }
        }
    }

    /// Apply the evaluation outcome for one cyclic SCC: stamp `#CIRC!` on its
    /// (optionally filtered) members via `stamp_cycle_error`.
    ///
    /// This is the single per-SCC application point used by every schedule
    /// consumer walking `Schedule::units` (pre-work for #112, where cyclic
    /// SCCs will gain runtime verdicts instead of an unconditional stamp).
    ///
    /// `dirty_filter` preserves the recalc-plan quirk: when `Some(dirty)`,
    /// only members present in the set are stamped.
    ///
    /// Returns the number of vertices stamped (0 when a filter excludes every
    /// member), so callers can keep their site-specific `cycle_errors`
    /// accounting.
    fn apply_cycle_outcome(
        &mut self,
        cycle: &[VertexId],
        mut delta: Option<&mut DeltaCollector>,
        dirty_filter: Option<&FxHashSet<VertexId>>,
    ) -> usize {
        let circ_error = LiteralValue::Error(
            ExcelError::new(ExcelErrorKind::Circ)
                .with_message("Circular dependency detected".to_string()),
        );
        let mut stamped = 0usize;
        for &vertex_id in cycle {
            if let Some(filter) = dirty_filter
                && !filter.contains(&vertex_id)
            {
                continue;
            }
            self.stamp_cycle_error(vertex_id, &circ_error, delta.as_deref_mut());
            stamped += 1;
        }
        stamped
    }

    /// Stamp a vertex with `#CIRC!` as part of cycle handling.
    ///
    /// Unlike a bare `update_vertex_value`, this first tears down any spill the
    /// vertex previously anchored: it clears the spilled cells, releases the graph
    /// spill registry, drops any lingering region reservation, and mirrors the
    /// cleared cells into the computed overlay — the same teardown a normal scalar/
    /// error result performs (see `apply_non_array_result_from_parallel` /
    /// `clear_spill_projection_and_mirror`). Without this, a #CIRC stamp on a former
    /// spill anchor would leave stale spilled values and a reserved region behind
    /// (issue #111).
    ///
    /// When `delta` is provided, the cleared spill cells are recorded (by
    /// `clear_spill_projection_and_mirror`) and the anchor's own #CIRC change is
    /// recorded here, matching how other result paths emit deltas.
    fn stamp_cycle_error(
        &mut self,
        vertex_id: VertexId,
        circ_error: &LiteralValue,
        mut delta: Option<&mut DeltaCollector>,
    ) {
        // Tear down any previous spill projection/region before overwriting the anchor.
        if self.graph.spill_registry_has_anchor(vertex_id) {
            self.clear_spill_projection_and_mirror(vertex_id, delta.as_deref_mut());
        }
        // Drop any reservation that was never committed (defensive; normally released
        // on the prior successful commit).
        self.spill_mgr.release_owner(vertex_id);

        // Record the anchor's own #CIRC delta, like other result paths.
        if let Some(d) = delta
            && d.mode != DeltaMode::Off
            && let Some(cell) = self.graph.get_cell_ref_for_vertex(vertex_id)
        {
            let sheet_name = self.graph.sheet_name(cell.sheet_id);
            let old = self
                .read_cell_value(sheet_name, cell.coord.row() + 1, cell.coord.col() + 1)
                .unwrap_or(LiteralValue::Empty);
            if old != *circ_error {
                d.record_cell(cell.sheet_id, cell.coord.row(), cell.coord.col());
            }
        }

        self.graph
            .update_vertex_value(vertex_id, circ_error.clone());
        self.mirror_vertex_value_to_overlay(vertex_id, circ_error);
    }

    /// Dispatch point for one `ScheduleUnit::Cycle` (RFC #112, Stage 2).
    ///
    /// * `CycleDetection::Static` — today's behavior, byte-for-byte: stamp
    ///   `#CIRC!` on the (optionally dirty-filtered) members.
    /// * `CycleDetection::Runtime` — evaluate the SCC via
    ///   [`Self::evaluate_scc_unit`]. The recalc-plan dirty quirk maps to:
    ///   no dirty member → skip the task entirely (values stand); any dirty
    ///   member → the whole SCC evaluates (an SCC cannot be partially
    ///   evaluated).
    ///
    /// Returns the number of `#CIRC!`-stamped vertices, so call sites can
    /// keep their `cycle_errors` accounting (`> 0` ⇒ count the unit).
    fn handle_cycle_unit(
        &mut self,
        cycle: &[VertexId],
        mut delta: Option<&mut DeltaCollector>,
        dirty_filter: Option<&FxHashSet<VertexId>>,
        cancel_flag: Option<&AtomicBool>,
    ) -> Result<usize, ExcelError> {
        self.resource_checkpoint(cycle.len() as u64)?;
        match self.config.cycle.detection {
            CycleDetection::Static => {
                Ok(self.apply_cycle_outcome(cycle, delta.as_deref_mut(), dirty_filter))
            }
            CycleDetection::Runtime => {
                if let Some(filter) = dirty_filter
                    && !cycle.iter().any(|v| filter.contains(v))
                {
                    return Ok(0);
                }
                // Both policies share `evaluate_scc_unit`; they differ only
                // in the settle loop's live-cycle arm (Error stamps,
                // Iterate keeps passing — RFC #113).
                self.evaluate_scc_unit(cycle, delta, cancel_flag)
            }
        }
    }

    /// Evaluate one statically-cyclic SCC under `CycleDetection::Runtime`
    /// (design doc `formualizer-stage2-scc-evaluation-design.md` §3; contract
    /// spec §3; Iterate policy arm per RFC #113).
    ///
    /// Phantom SCCs (live-acyclic) produce ordinary values under both
    /// policies; live cycles get `#CIRC!` with live-cycle-only blast radius
    /// under `CyclePolicy::Error`, or Excel-style iterative calculation
    /// (converge per spec §6 or cap at `max_iterations` passes) under
    /// `CyclePolicy::Iterate`. Runs sequentially on the
    /// coordinating thread; commits are write-through per member (no
    /// `ComputedWriteBuffer` — that buffer is scoped to layer evaluation and
    /// always flushed before a Cycle unit runs, G1), so later members' scalar
    /// *and* range reads observe earlier members' results through the overlay
    /// cascade. Deltas are recorded once per member at end of task (G11).
    ///
    /// Returns the number of vertices stamped `#CIRC!`.
    ///
    /// `pub(crate)` so tests can drive SCC shapes (e.g. name-vertex members)
    /// that ingest-time cycle rejection makes unreachable via public edits.
    pub(crate) fn evaluate_scc_unit(
        &mut self,
        cycle: &[VertexId],
        mut delta: Option<&mut DeltaCollector>,
        cancel_flag: Option<&AtomicBool>,
    ) -> Result<usize, ExcelError> {
        struct SccMember {
            vertex: VertexId,
            cell: Option<CellRef>,
        }

        let task_start = crate::instant::FzInstant::now();

        // ── 0. Member order (spec §7.13): cells ascending (sheet, row, col);
        // name vertices after, lexicographic by folded canonical name; any
        // other vertex kind (defensive — `get_evaluation_vertices` only emits
        // formula/name kinds) last by id, never evaluated.
        let mut cell_members: Vec<(VertexId, CellRef)> = Vec::new();
        let mut name_members: Vec<(VertexId, String)> = Vec::new();
        let mut other_members: Vec<VertexId> = Vec::new();
        for &v in cycle {
            match self.graph.get_vertex_kind(v) {
                VertexKind::FormulaScalar | VertexKind::FormulaArray => {
                    match self.graph.get_cell_ref(v) {
                        Some(cell) => cell_members.push((v, cell)),
                        None => other_members.push(v),
                    }
                }
                VertexKind::NamedScalar | VertexKind::NamedArray => {
                    match self.graph.name_key_for_vertex(v) {
                        Some(key) => name_members.push((v, key)),
                        None => other_members.push(v),
                    }
                }
                _ => other_members.push(v),
            }
        }
        cell_members.sort_unstable_by_key(|(_, c)| (c.sheet_id, c.coord.row(), c.coord.col()));
        name_members.sort_unstable_by(|(av, ak), (bv, bk)| ak.cmp(bk).then(av.cmp(bv)));
        other_members.sort_unstable();

        let cell_refs: Vec<CellRef> = cell_members.iter().map(|(_, c)| *c).collect();
        let name_keys: Vec<String> = name_members.iter().map(|(_, k)| k.clone()).collect();
        let mut members: Vec<SccMember> = Vec::with_capacity(cycle.len());
        for (v, c) in &cell_members {
            members.push(SccMember {
                vertex: *v,
                cell: Some(*c),
            });
        }
        for (v, _) in &name_members {
            members.push(SccMember {
                vertex: *v,
                cell: None,
            });
        }
        for v in &other_members {
            members.push(SccMember {
                vertex: *v,
                cell: None,
            });
        }
        let n = members.len();
        // Indices addressable by the collector (cells + names); `other`
        // members can be neither edge sources nor targets.
        let recordable = cell_refs.len() + name_keys.len();

        let circ_error = LiteralValue::Error(
            ExcelError::new(ExcelErrorKind::Circ)
                .with_message("Circular dependency detected".to_string()),
        );

        // ── 0b. Spec-§4 persistence repair: structural edits clear computed
        // overlays wholesale (`clear_computed_overlay_after_row/_col`), but
        // an iterating member's committed value is cycle STATE, not a
        // recomputable cache — and in canonical mode the overlay is its ONLY
        // home. If the overlay entry vanished since the last recalc, re-seed
        // it from the end-of-recalc snapshot (`iterative_state_values`) so
        // pass-1 reads (scalar AND range, via the overlay cascade) observe
        // the persisted value instead of silently restarting at Empty→0.
        // (Found by the iterate edge corpus: inserting/deleting an unrelated
        // row reset accumulators, violating spec §4/§7.15.)
        if !self.iterative_state_values.is_empty() {
            let restore: Vec<(VertexId, LiteralValue)> = members
                .iter()
                .filter_map(|m| {
                    let cell = m.cell?;
                    let persisted = self.iterative_state_values.get(&m.vertex)?;
                    let sheet_name = self.graph.sheet_name(cell.sheet_id);
                    let overlay = self
                        .get_cell_value(sheet_name, cell.coord.row() + 1, cell.coord.col() + 1)
                        .unwrap_or(LiteralValue::Empty);
                    if matches!(overlay, LiteralValue::Empty) {
                        Some((m.vertex, persisted.clone()))
                    } else {
                        None
                    }
                })
                .collect();
            for (vertex, value) in restore {
                self.mirror_vertex_value_to_overlay(vertex, &value);
            }
        }

        // ── 1. Pre-task value snapshot (overlay-first for cells — G3; the
        // graph value map may be evicted in value-cache-disabled mode).
        let snapshot: Vec<LiteralValue> = members
            .iter()
            .map(|m| match m.cell {
                Some(cell) => {
                    let sheet_name = self.graph.sheet_name(cell.sheet_id);
                    self.get_cell_value(sheet_name, cell.coord.row() + 1, cell.coord.col() + 1)
                        .unwrap_or(LiteralValue::Empty)
                }
                None => self
                    .graph
                    .get_value(m.vertex)
                    .unwrap_or(LiteralValue::Empty),
            })
            .collect();

        // ── 2. Pre-scan: spill anchors (FormulaArray) are stamped `#CIRC!`
        // with full spill teardown (spec §7.9, #115) and excluded from
        // evaluation. They stay recordable edge TARGETS (readers see `#CIRC!`
        // and propagate). Non-evaluable defensive members are excluded too.
        let mut excluded = vec![false; n];
        let mut last_value = snapshot.clone();
        let mut stamped = 0usize;
        for (i, m) in members.iter().enumerate() {
            match self.graph.get_vertex_kind(m.vertex) {
                VertexKind::FormulaArray => {
                    // Deltas for the cleared spill-region cells (non-members)
                    // can only be recorded here; the anchor's own delta is
                    // covered by the end-of-task snapshot comparison (dedup).
                    self.stamp_cycle_error(m.vertex, &circ_error, delta.as_deref_mut());
                    excluded[i] = true;
                    last_value[i] = circ_error.clone();
                    stamped += 1;
                }
                VertexKind::FormulaScalar | VertexKind::NamedScalar | VertexKind::NamedArray => {}
                _ => excluded[i] = true,
            }
        }

        let collector = LiveEdgeCollector::new_with_names(&cell_refs, &name_keys);

        // Per-member live out-edges, refreshed whenever a member re-runs.
        let mut out_edges: Vec<Vec<u32>> = vec![Vec::new(); n];
        // Position of each member in the most recent pass (-1 = did not run).
        let mut pos: Vec<i64> = vec![-1; n];
        // Whether each member's committed value changed in the most recent pass.
        let mut changed = vec![false; n];

        // Evaluate-and-commit one member; returns Ok(true) when the member was
        // stamped `#CIRC!` (array result — would-be spill anchor, spec §7.9).
        macro_rules! run_member {
            ($i:expr) => {{
                let i: usize = $i;
                let m = &members[i];
                if i < recordable {
                    collector.set_current(i as u32);
                }
                let value = {
                    let ctx = RecordingContext::new(&*self, &collector);
                    match self.evaluate_vertex_recorded(m.vertex, &ctx, &collector) {
                        Ok(v) => v,
                        Err(e) => LiteralValue::Error(e),
                    }
                };
                let is_cell_formula = m.cell.is_some();
                if is_cell_formula && matches!(value, LiteralValue::Array(_)) {
                    // A member that *would* spill inside an SCC gets the
                    // conservative §7.9 verdict. It has never spilled before
                    // (a prior spill would make it FormulaArray, pre-stamped
                    // above), so there is no projection to tear down.
                    self.stamp_cycle_error(m.vertex, &circ_error, None);
                    excluded[i] = true;
                    stamped += 1;
                    changed[i] = last_value[i] != circ_error;
                    last_value[i] = circ_error.clone();
                } else {
                    self.graph.update_vertex_value(m.vertex, value.clone());
                    self.mirror_vertex_value_to_overlay(m.vertex, &value);
                    // §7.14 invariant (G2): a formula member must never be
                    // shadowed by a user/delta overlay entry, or iteration
                    // reads would silently diverge from committed values.
                    #[cfg(debug_assertions)]
                    if let Some(cell) = m.cell {
                        let sheet_name = self.graph.sheet_name(cell.sheet_id).to_string();
                        debug_assert!(
                            self.read_delta_overlay_cell(
                                &sheet_name,
                                cell.coord.row() + 1,
                                cell.coord.col() + 1
                            )
                            .is_none(),
                            "user overlay must never shadow a formula SCC member ({sheet_name}!r{}c{})",
                            cell.coord.row() + 1,
                            cell.coord.col() + 1
                        );
                    }
                    changed[i] = last_value[i] != value;
                    last_value[i] = value;
                }
            }};
        }

        let check_cancel = |flag: Option<&AtomicBool>| -> Result<(), ExcelError> {
            if let Some(flag) = flag
                && flag.load(Ordering::Relaxed)
            {
                return Err(ExcelError::new(ExcelErrorKind::Cancelled)
                    .with_message("Evaluation cancelled during SCC evaluation".to_string()));
            }
            Ok(())
        };

        // ── 3. Pass 1: all evaluable members in member order.
        check_cancel(cancel_flag)?;
        let mut passes = 1usize;
        {
            let mut p = 0i64;
            for i in 0..n {
                if excluded[i] {
                    continue;
                }
                run_member!(i);
                pos[i] = p;
                p += 1;
            }
        }

        // ── 4. Settle loop (design doc §3 step 4; RFC #113 policy arm).
        //
        // Acyclic classifications settle stale readers exactly (identical
        // under both policies — phantom SCCs never iterate). A witnessed
        // live cycle dispatches on policy: `Error` stamps `#CIRC!` and
        // stops; `Iterate` keeps running full passes over all members in
        // member order until converged (spec §6) or capped at
        // `max_iterations` total passes. A live cycle that only appears
        // mid-settle takes the same arm, and a cycle that dissolves
        // mid-iteration falls back to exact acyclic settling.
        //
        // Defensive acyclic budget: the acyclic settle is monotone, so more
        // than |SCC| + 2 settle passes can only be a bug; cap hits stamp the
        // remainder and set telemetry. Tracked via `settle_passes` so
        // iteration passes (legitimately many) don't consume the budget.
        let policy = self.config.cycle.policy;
        let cap = n + 2;
        let mut witnessed_cycles = 0usize;
        let mut capped = false;
        // ── Iterate-policy state ──
        let mut iterating = false;
        let mut converged = false;
        // Values committed by the last *full* pass; `None` until the first
        // iteration pass runs (pass 1 has no predecessor to compare against)
        // and reset when a settle pass runs (no cross-kind comparisons).
        let mut prev_pass: Option<Vec<LiteralValue>> = None;
        // Final-round convergence stats (overwritten per round so the values
        // reported are the ones observed at stop).
        let mut iter_max_delta = 0f64;
        let mut iter_nan_converged = 0usize;
        // Acyclic stale-reader re-eval passes (defensive budget; under pure
        // Error flow `1 + settle_passes == passes`, preserving Stage-2
        // behavior exactly).
        let mut settle_passes = 0usize;
        loop {
            // Drain this pass's recordings; members that ran replace their
            // out-edge set, members that didn't keep last-known edges.
            let drained = collector.take_edges();
            for i in 0..n {
                if pos[i] >= 0 {
                    out_edges[i].clear();
                }
            }
            for (from, to) in drained {
                debug_assert!(
                    pos[from as usize] >= 0,
                    "edge from a member that did not run"
                );
                out_edges[from as usize].push(to);
            }
            let mut edges: Vec<(u32, u32)> = Vec::new();
            for (i, outs) in out_edges.iter().enumerate() {
                if excluded[i] {
                    continue;
                }
                for &t in outs {
                    edges.push((i as u32, t));
                }
            }
            edges.sort_unstable();
            edges.dedup();

            let analysis = analyze_live_graph(n, &edges);

            if analysis.cycle_count > 0 {
                // Classification repeats every iteration pass under
                // `Iterate`; record the widest single witness instead of
                // accumulating so the count stays "distinct live cycles".
                witnessed_cycles = witnessed_cycles.max(analysis.cycle_count);
                match policy {
                    CyclePolicy::Error => {
                        // POLICY (Error): stamp every member of a live cycle,
                        // then one settling pass over the remaining members in
                        // live-topological order so error propagation
                        // downstream is consistent (spec §3.4). Blast radius =
                        // live cycles only.
                        for i in 0..n {
                            if analysis.in_cycle[i] && !excluded[i] {
                                self.stamp_cycle_error(members[i].vertex, &circ_error, None);
                                excluded[i] = true;
                                last_value[i] = circ_error.clone();
                                stamped += 1;
                            }
                        }
                        check_cancel(cancel_flag)?;
                        let order: Vec<usize> = analysis
                            .topo
                            .iter()
                            .map(|&i| i as usize)
                            .filter(|&i| !excluded[i])
                            .collect();
                        if !order.is_empty() {
                            passes += 1;
                            for i in order {
                                run_member!(i);
                            }
                        }
                        break;
                    }
                    CyclePolicy::Iterate {
                        max_iterations,
                        max_change,
                    } => {
                        // POLICY (Iterate), spec §3.5/§6.
                        iterating = true;

                        // Convergence test: the full pass that just completed
                        // vs the previous full pass, per the spec-§6 rules.
                        // `prev_pass` is `None` until an iteration pass has
                        // run — pass 1 has no predecessor, so no convergence
                        // test occurs before the second pass (spec §6).
                        if let Some(prev) = &prev_pass {
                            let mut round_max_delta = 0f64;
                            let mut round_nan = 0usize;
                            let mut all_converged = true;
                            for i in 0..n {
                                if excluded[i] {
                                    // Stamped mid-iteration (array result,
                                    // §7.9): the value is pinned and cannot
                                    // change again — trivially settled.
                                    continue;
                                }
                                let out = crate::engine::convergence::values_converged(
                                    &prev[i],
                                    &last_value[i],
                                    max_change,
                                    self.config.date_system,
                                );
                                if out.nan_converged {
                                    round_nan += 1;
                                }
                                if let Some(d) = out.abs_delta {
                                    round_max_delta = round_max_delta.max(d);
                                }
                                if !out.converged {
                                    all_converged = false;
                                }
                            }
                            // Overwrite (not max): telemetry reports the
                            // round observed at stop.
                            iter_max_delta = round_max_delta;
                            iter_nan_converged = round_nan;
                            if all_converged {
                                converged = true;
                                break;
                            }
                        }

                        // ── Pass-counting reconciliation (spec §6/§7.6):
                        // `max_iterations` counts TOTAL passes, pass 1
                        // included, and pass 1 has already run by the time a
                        // live cycle is first witnessed here. The budget is
                        // therefore checked BEFORE evaluating anything more:
                        // with `max_iterations: 1` we stop right here — each
                        // member was evaluated exactly once this recalc (the
                        // Excel accumulator contract) and no convergence test
                        // ran (`prev_pass` is still `None`). Capping keeps
                        // the last committed values and is NOT an error
                        // (Excel parity); telemetry records it.
                        if passes >= max_iterations as usize {
                            capped = true;
                            break;
                        }

                        check_cancel(cancel_flag)?;
                        // One more full pass over every evaluable member in
                        // member order (Gauss–Seidel: each commit is visible
                        // to later members within the pass). Live edges
                        // re-record — guards can flip near convergence
                        // (§7.3) — so classification repeats next time
                        // around, and a cycle that dissolves drops back to
                        // the exact acyclic settle below.
                        prev_pass = Some(last_value.clone());
                        for x in pos.iter_mut() {
                            *x = -1;
                        }
                        changed.fill(false);
                        passes += 1;
                        let mut p = 0i64;
                        for i in 0..n {
                            if excluded[i] {
                                continue;
                            }
                            run_member!(i);
                            pos[i] = p;
                            p += 1;
                        }
                        continue;
                    }
                }
            }

            // Acyclic: find stale readers — members whose live read of `to`
            // happened before `to`'s value changed in the pass that just ran.
            let mut stale: Vec<usize> = Vec::new();
            for i in 0..n {
                if excluded[i] {
                    continue;
                }
                let is_stale = out_edges[i].iter().any(|&t| {
                    let t = t as usize;
                    changed[t] && (pos[i] < 0 || (pos[t] >= 0 && pos[i] < pos[t]))
                });
                if is_stale {
                    stale.push(i);
                }
            }
            if stale.is_empty() {
                break; // values exact — phantom SCC (or dissolved live cycle)
            }
            if 1 + settle_passes >= cap {
                // Defensive only; hitting this is a bug (loud telemetry).
                capped = true;
                for (i, m) in members.iter().enumerate() {
                    if !excluded[i] {
                        self.stamp_cycle_error(m.vertex, &circ_error, None);
                        excluded[i] = true;
                        last_value[i] = circ_error.clone();
                        stamped += 1;
                    }
                }
                break;
            }

            check_cancel(cancel_flag)?;
            // Re-evaluate stale readers in live-topo order, recording fresh
            // edges (branches may flip on re-eval — spec §7.3 — which is why
            // classification repeats).
            // A settle pass is a partial sweep: drop the full-pass baseline
            // so a live cycle (re)appearing afterwards never compares values
            // across mixed pass kinds.
            prev_pass = None;
            let topo_pos = analysis.topo_positions();
            stale.sort_unstable_by_key(|&i| topo_pos[i]);
            for x in pos.iter_mut() {
                *x = -1;
            }
            changed.fill(false);
            passes += 1;
            settle_passes += 1;
            for (p, i) in stale.into_iter().enumerate() {
                run_member!(i);
                pos[i] = p as i64;
            }
        }

        // Iteration that ended because the live cycle dissolved and the
        // acyclic settle reached exactness counts as converged (values are
        // exact, strictly better than threshold-converged). The defensive
        // settle cap (`capped` + stamping) is not.
        if iterating && !converged && !capped {
            converged = true;
        }

        // ── 5. End of task: one delta per member whose final value differs
        // from the pre-task snapshot (spec §3 side-effect rule, G11).
        collector.clear_current();
        if let Some(d) = delta
            && d.mode != DeltaMode::Off
        {
            for (i, m) in members.iter().enumerate() {
                if let Some(cell) = m.cell
                    && last_value[i] != snapshot[i]
                {
                    d.record_cell(cell.sheet_id, cell.coord.row(), cell.coord.col());
                }
            }
        }

        // Members of an SCC that iterated re-evaluate on EVERY recalc, like
        // Excel's circular cells: register them for the end-of-recalc
        // volatile-like redirty (see `pending_iterative_redirty`). Marking
        // any one member propagates around the (strongly connected) SCC and
        // to downstream dependents, but all members are registered so the
        // contract survives partial structural edits between recalcs.
        if iterating {
            self.pending_iterative_redirty
                .extend(members.iter().map(|m| m.vertex));
        }

        {
            let t = &mut self.last_cycle_telemetry;
            t.static_sccs += 1;
            if witnessed_cycles == 0 && stamped == 0 && !capped {
                t.phantom_sccs += 1;
            }
            t.live_cycles_witnessed += witnessed_cycles;
            t.circ_cells_stamped += stamped;
            t.settle_passes_total += passes;
            t.max_passes_single_scc = t.max_passes_single_scc.max(passes);
            if iterating {
                t.iterated_sccs += 1;
                if converged {
                    t.converged_sccs += 1;
                }
                t.max_abs_delta_at_stop = t.max_abs_delta_at_stop.max(iter_max_delta);
                t.nan_converged += iter_nan_converged;
            }
            if capped {
                t.capped_sccs += 1;
            }
            t.elapsed_ms += task_start.elapsed().as_millis();
        }

        Ok(stamped)
    }

    /// Recorded sibling of [`Self::evaluate_vertex_immutable`]: evaluates one
    /// SCC member's AST via an [`Interpreter`] over a [`RecordingContext`] so
    /// reads that actually occur are captured as live edges. Value semantics
    /// must match `evaluate_vertex_immutable` exactly (including the missing-
    /// AST `Number(0.0)` quirk, G14); named Cell/Range/Literal definitions
    /// delegate to it after recording the definition region by hand (those
    /// reads bypass the context).
    fn evaluate_vertex_recorded(
        &self,
        vertex_id: VertexId,
        ctx: &RecordingContext<'_, R>,
        collector: &LiveEdgeCollector,
    ) -> Result<LiteralValue, ExcelError> {
        if !self.graph.vertex_exists(vertex_id) {
            return Err(ExcelError::new(formualizer_common::ExcelErrorKind::Ref)
                .with_message(format!("Vertex not found: {vertex_id:?}")));
        }

        let kind = self.graph.get_vertex_kind(vertex_id);
        let sheet_id = self.graph.get_vertex_sheet_id(vertex_id);

        match kind {
            VertexKind::FormulaScalar | VertexKind::FormulaArray => {
                let Some(ast_id) = self.graph.get_formula_id(vertex_id) else {
                    return Ok(LiteralValue::Number(0.0)); // G14 quirk
                };
                let sheet_name = self.graph.sheet_name(sheet_id);
                let cell_ref = self
                    .graph
                    .get_cell_ref(vertex_id)
                    .expect("cell ref for vertex");
                let interpreter = Interpreter::new_with_cell(ctx, sheet_name, cell_ref);
                interpreter
                    .evaluate_arena_ast(ast_id, self.graph.data_store(), self.graph.sheet_reg())
                    .map(|cv| {
                        crate::engine::result_finalization::finalize_formula_result(
                            cv.into_literal(),
                        )
                    })
            }
            VertexKind::NamedScalar | VertexKind::NamedArray => {
                let named_range = self.graph.named_range_by_vertex(vertex_id).ok_or_else(|| {
                    ExcelError::new(ExcelErrorKind::Name)
                        .with_message("Named range metadata missing".to_string())
                })?;

                match &named_range.definition {
                    NamedDefinition::Formula { ast, .. } => {
                        let context_sheet = match named_range.scope {
                            NameScope::Sheet(id) => id,
                            NameScope::Workbook => sheet_id,
                        };
                        let sheet_name = self.graph.sheet_name(context_sheet);
                        let cell_ref = self
                            .graph
                            .get_cell_ref(vertex_id)
                            .unwrap_or_else(|| self.graph.make_cell_ref(sheet_name, 0, 0));
                        let interpreter = Interpreter::new_with_cell(ctx, sheet_name, cell_ref);
                        if kind == VertexKind::NamedScalar {
                            interpreter.evaluate_ast(ast).map(|cv| cv.into_literal())
                        } else {
                            match interpreter.evaluate_ast(ast) {
                                Ok(cv) => match cv.into_literal() {
                                    v @ LiteralValue::Array(_) => Ok(v),
                                    other => Ok(LiteralValue::Array(vec![vec![other]])),
                                },
                                Err(err) => Ok(LiteralValue::Error(err)),
                            }
                        }
                    }
                    NamedDefinition::Cell(cell_ref) => {
                        // The definition is read via direct grid access in
                        // `evaluate_vertex_immutable`; record the live edge
                        // by hand before delegating.
                        collector.record_scalar(
                            cell_ref.sheet_id,
                            cell_ref.coord.row(),
                            cell_ref.coord.col(),
                        );
                        self.evaluate_vertex_immutable(vertex_id)
                    }
                    NamedDefinition::Range(range_ref) => {
                        if range_ref.start.sheet_id == range_ref.end.sheet_id {
                            collector.record_rect(
                                range_ref.start.sheet_id,
                                range_ref.start.coord.row(),
                                range_ref.start.coord.col(),
                                range_ref.end.coord.row(),
                                range_ref.end.coord.col(),
                            );
                        }
                        self.evaluate_vertex_immutable(vertex_id)
                    }
                    NamedDefinition::Literal(_) => self.evaluate_vertex_immutable(vertex_id),
                }
            }
            _ => self.evaluate_vertex_immutable(vertex_id),
        }
    }

    /// Helper: commit spill via shim and mirror resulting cells into Arrow overlay when enabled.
    fn commit_spill_and_mirror(
        &mut self,
        anchor_vertex: VertexId,
        targets: &[CellRef],
        rows: Vec<Vec<LiteralValue>>,
        delta: Option<&mut DeltaCollector>,
        overwritable_formulas: Option<&rustc_hash::FxHashSet<VertexId>>,
    ) -> Result<(), ExcelError> {
        let prev_spill_cells = self
            .graph
            .spill_cells_for_anchor(anchor_vertex)
            .map(|cells| cells.to_vec())
            .unwrap_or_default();

        if let Some(delta) = delta
            && delta.mode != DeltaMode::Off
        {
            let target_set: std::collections::HashSet<CellRef, CoordBuildHasher> =
                targets.iter().copied().collect();
            let empty = LiteralValue::Empty;

            // Clears (prev - targets)
            for cell in prev_spill_cells.iter() {
                if target_set.contains(cell) {
                    continue;
                }
                let sheet_name = self.graph.sheet_name(cell.sheet_id);
                let old = self
                    .get_cell_value(sheet_name, cell.coord.row() + 1, cell.coord.col() + 1)
                    .unwrap_or(LiteralValue::Empty);
                if old != empty {
                    delta.record_cell(cell.sheet_id, cell.coord.row(), cell.coord.col());
                }
            }

            // Writes (targets)
            if !targets.is_empty() && !rows.is_empty() && !rows[0].is_empty() {
                let width = rows[0].len();
                for (idx, cell) in targets.iter().enumerate() {
                    let r_off = idx / width;
                    let c_off = idx % width;
                    let new = rows
                        .get(r_off)
                        .and_then(|r| r.get(c_off))
                        .cloned()
                        .unwrap_or(LiteralValue::Empty);
                    let sheet_name = self.graph.sheet_name(cell.sheet_id);
                    let old = self
                        .get_cell_value(sheet_name, cell.coord.row() + 1, cell.coord.col() + 1)
                        .unwrap_or(LiteralValue::Empty);
                    if old != new {
                        delta.record_cell(cell.sheet_id, cell.coord.row(), cell.coord.col());
                    }
                }
            } else {
                // Degenerate shapes: if we have targets but no rows, treat as writing Empty.
                for cell in targets.iter() {
                    let sheet_name = self.graph.sheet_name(cell.sheet_id);
                    let old = self
                        .get_cell_value(sheet_name, cell.coord.row() + 1, cell.coord.col() + 1)
                        .unwrap_or(LiteralValue::Empty);
                    if !matches!(old, LiteralValue::Empty) {
                        delta.record_cell(cell.sheet_id, cell.coord.row(), cell.coord.col());
                    }
                }
            }
        }

        // Commit via shim (releases locks). When the graph value cache is disabled (Arrow-canonical
        // values), plan/commit must consult Arrow storage to detect non-empty value blockers.
        let arrow_sheets = &self.arrow_sheets;
        self.spill_mgr.commit_array_with_value_probe(
            &mut self.graph,
            anchor_vertex,
            targets,
            rows.clone(),
            overwritable_formulas,
            |g, cell| {
                let sheet_name = g.sheet_name(cell.sheet_id);
                let asheet = arrow_sheets.sheet(sheet_name)?;
                let r0 = cell.coord.row() as usize;
                let c0 = cell.coord.col() as usize;
                let v = asheet.get_cell_value(r0, c0);
                if matches!(v, LiteralValue::Empty) {
                    None
                } else {
                    Some(v)
                }
            },
        )?;

        if let Some(scope) = Self::formula_plane_region_from_cells(&prev_spill_cells) {
            self.record_formula_plane_structural_change(scope);
        }
        if let Some(scope) = Self::formula_plane_region_from_cells(targets) {
            self.record_formula_plane_structural_change(scope);
        }

        if self.config.arrow_storage_enabled
            && self.config.delta_overlay_enabled
            && self.config.write_formula_overlay_enabled
        {
            if !prev_spill_cells.is_empty() {
                let target_set: std::collections::HashSet<CellRef, CoordBuildHasher> =
                    targets.iter().copied().collect();
                let empty = LiteralValue::Empty;
                for cell in prev_spill_cells.iter() {
                    if !target_set.contains(cell) {
                        let sheet_name = self.graph.sheet_name(cell.sheet_id).to_string();
                        self.mirror_value_to_computed_overlay(
                            &sheet_name,
                            cell.coord.row() + 1,
                            cell.coord.col() + 1,
                            &empty,
                        );
                    }
                }
            }

            for (idx, cell) in targets.iter().enumerate() {
                if rows.is_empty() || rows[0].is_empty() {
                    break;
                }
                let width = rows[0].len();
                let r_off = idx / width;
                let c_off = idx % width;
                let v = rows[r_off][c_off].clone();
                let sheet_name = self.graph.sheet_name(cell.sheet_id).to_string();
                self.mirror_value_to_computed_overlay(
                    &sheet_name,
                    cell.coord.row() + 1,
                    cell.coord.col() + 1,
                    &v,
                );
            }
        }
        Ok(())
    }
}

// ── Effects pipeline (ticket 603) ──────────────────────────────────────────
//
// Compute → Plan → Apply separation for evaluation side-effects.

use crate::engine::effects::Effect;
use crate::engine::graph::editor::change_log::{ChangeEvent, ChangeLog, SpillSnapshot};

impl<R> Engine<R>
where
    R: EvaluationContext,
{
    /// Plan effects for a single vertex after its value has been computed.
    ///
    /// This reads graph state but only performs lightweight mutations
    /// (`set_kind`, `spill_mgr.reserve`) that are needed for correctness
    /// during the planning phase.  Value-changing mutations are deferred to
    /// `apply_effect`.
    pub(crate) fn plan_vertex_effects(
        &mut self,
        vertex_id: VertexId,
        computed_value: LiteralValue,
        overwritable_formulas: Option<&rustc_hash::FxHashSet<VertexId>>,
    ) -> Result<Vec<Effect>, ExcelError> {
        let kind = self.graph.get_vertex_kind(vertex_id);
        let is_formula = matches!(kind, VertexKind::FormulaScalar | VertexKind::FormulaArray);

        // If this vertex's cell is currently covered by a spill from a different
        // anchor, ignore the computed result.  Formula vertices are exempt:
        // they must still evaluate so that overlapping spills produce #SPILL!.
        if !is_formula {
            if let Some(cell) = self.graph.get_cell_ref(vertex_id)
                && let Some(owner) = self.graph.spill_registry_anchor_for_cell(cell)
                && owner != vertex_id
            {
                return Ok(Vec::new());
            }
            // Non-formula vertices: store value as-is (arrays remain arrays; no spill).
            return Ok(vec![Effect::WriteCell {
                vertex_id,
                value: computed_value,
            }]);
        }

        match computed_value {
            LiteralValue::Array(rows) => {
                self.plan_array_effects(vertex_id, rows, overwritable_formulas)
            }
            other => self.plan_scalar_effects(vertex_id, other),
        }
    }

    /// Plan effects for a formula vertex that produced a scalar/error result.
    fn plan_scalar_effects(
        &self,
        vertex_id: VertexId,
        value: LiteralValue,
    ) -> Result<Vec<Effect>, ExcelError> {
        let has_spill = self
            .graph
            .spill_cells_for_anchor(vertex_id)
            .is_some_and(|c| !c.is_empty());

        let mut effects = Vec::new();
        if has_spill {
            effects.push(Effect::SpillClear {
                anchor_vertex: vertex_id,
            });
        }
        effects.push(Effect::WriteCell { vertex_id, value });
        Ok(effects)
    }

    /// Plan effects for a formula vertex that produced an array result.
    fn plan_array_effects(
        &mut self,
        vertex_id: VertexId,
        rows: Vec<Vec<LiteralValue>>,
        overwritable_formulas: Option<&rustc_hash::FxHashSet<VertexId>>,
    ) -> Result<Vec<Effect>, ExcelError> {
        // Lightweight mutation needed for correct spill-blocking checks.
        self.graph.set_kind(vertex_id, VertexKind::FormulaArray);

        let anchor = self
            .graph
            .get_cell_ref(vertex_id)
            .expect("cell ref for vertex");
        let sheet_id = anchor.sheet_id;
        let h = rows.len() as u32;
        let w = rows.first().map(|r| r.len()).unwrap_or(0) as u32;

        // Hard cap to avoid vertex explosion from huge dynamic arrays.
        let spill_cells = (h as u64).saturating_mul(w as u64);
        if spill_cells > self.config.spill.max_spill_cells as u64 {
            return self.plan_spill_error_effects(vertex_id, "SpillTooLarge", h, w);
        }

        // Bounds check to avoid out-of-range writes (align to AbsCoord capacity).
        const PACKED_MAX_ROW: u32 = 1_048_575;
        const PACKED_MAX_COL: u32 = 16_383;
        let end_row = anchor.coord.row().saturating_add(h).saturating_sub(1);
        let end_col = anchor.coord.col().saturating_add(w).saturating_sub(1);
        if end_row > PACKED_MAX_ROW || end_col > PACKED_MAX_COL {
            return self.plan_spill_error_effects(vertex_id, "Spill exceeds sheet bounds", h, w);
        }

        let mut targets = Vec::new();
        for r in 0..h {
            for c in 0..w {
                targets.push(self.graph.make_cell_ref_internal(
                    sheet_id,
                    anchor.coord.row() + r,
                    anchor.coord.col() + c,
                ));
            }
        }

        // Region lock via spill manager.
        match self.spill_mgr.reserve(
            vertex_id,
            anchor,
            SpillShape { rows: h, cols: w },
            SpillMeta {
                epoch: self.recalc_epoch,
                config: self.config.spill,
            },
        ) {
            Ok(()) => {
                // Validate spill region is available.
                if let Err(_e) = self.graph.plan_spill_region_allowing_formula_overwrite(
                    vertex_id,
                    &targets,
                    overwritable_formulas,
                ) {
                    return self.plan_spill_error_effects(vertex_id, "Spill blocked", h, w);
                }

                // Arrow-canonical mode: graph planning cannot see non-empty value blockers because
                // cell values are not cached in the dependency graph. Consult Arrow storage to
                // detect occupied cells in the target region.
                if !self.graph.value_cache_enabled() {
                    let sheet_name = self.graph.sheet_name(sheet_id);
                    if let Some(asheet) = self.sheet_store().sheet(sheet_name) {
                        for cell in targets.iter() {
                            // Allow overwriting the anchor itself.
                            if *cell == anchor {
                                continue;
                            }
                            // Allow cells already owned by a spill (plan() validated spill ownership).
                            if self.graph.spill_registry_anchor_for_cell(*cell).is_some() {
                                continue;
                            }
                            // Skip formula blockers; plan() handled them (or allowed).
                            if let Some(&vid) = self.graph.get_vertex_id_for_address(cell)
                                && vid != vertex_id
                            {
                                match self.graph.get_vertex_kind(vid) {
                                    VertexKind::FormulaScalar | VertexKind::FormulaArray => {
                                        continue;
                                    }
                                    _ => {}
                                }
                            }

                            let v = asheet.get_cell_value(
                                cell.coord.row() as usize,
                                cell.coord.col() as usize,
                            );
                            if !matches!(v, LiteralValue::Empty) {
                                return self.plan_spill_error_effects(
                                    vertex_id,
                                    "BlockedByValue",
                                    h,
                                    w,
                                );
                            }
                        }
                    }
                }

                let top_left = rows
                    .first()
                    .and_then(|r| r.first())
                    .cloned()
                    .unwrap_or(LiteralValue::Empty);

                let mut effects = Vec::new();
                // Clear previous spill if any.
                let has_prev = self
                    .graph
                    .spill_cells_for_anchor(vertex_id)
                    .is_some_and(|c| !c.is_empty());
                if has_prev {
                    effects.push(Effect::SpillClear {
                        anchor_vertex: vertex_id,
                    });
                }
                effects.push(Effect::SpillCommit {
                    anchor_vertex: vertex_id,
                    anchor_cell: anchor,
                    target_cells: targets,
                    values: rows,
                });
                effects.push(Effect::WriteCell {
                    vertex_id,
                    value: top_left,
                });
                Ok(effects)
            }
            Err(e) => {
                let msg = e.message.unwrap_or_else(|| "Spill blocked".to_string());
                self.plan_spill_error_effects(vertex_id, &msg, h, w)
            }
        }
    }

    /// Build the effect list for a spill that failed validation.
    fn plan_spill_error_effects(
        &self,
        vertex_id: VertexId,
        message: &str,
        expected_rows: u32,
        expected_cols: u32,
    ) -> Result<Vec<Effect>, ExcelError> {
        let spill_err = ExcelError::new(ExcelErrorKind::Spill)
            .with_message(message)
            .with_extra(formualizer_common::ExcelErrorExtra::Spill {
                expected_rows,
                expected_cols,
            });
        let spill_val = LiteralValue::Error(spill_err);

        let effects = vec![
            Effect::SpillClear {
                anchor_vertex: vertex_id,
            },
            Effect::WriteCell {
                vertex_id,
                value: spill_val,
            },
        ];
        Ok(effects)
    }

    /// Apply a single effect, performing the actual graph mutations.
    pub(crate) fn apply_effect(
        &mut self,
        effect: &Effect,
        delta: Option<&mut DeltaCollector>,
        log: Option<&mut ChangeLog>,
    ) -> Result<(), ExcelError> {
        self.apply_effect_with_computed_writes(effect, delta, log, None)
    }

    fn apply_effect_with_computed_writes(
        &mut self,
        effect: &Effect,
        delta: Option<&mut DeltaCollector>,
        log: Option<&mut ChangeLog>,
        computed_writes: Option<&mut ComputedWriteBuffer>,
    ) -> Result<(), ExcelError> {
        match effect {
            Effect::WriteCell { vertex_id, value } => {
                self.apply_write_cell(*vertex_id, value, delta, computed_writes)?;
            }
            Effect::SpillClear { anchor_vertex } => {
                self.apply_spill_clear(*anchor_vertex, delta, log, computed_writes)?;
            }
            Effect::SpillCommit {
                anchor_vertex,
                anchor_cell: _,
                target_cells,
                values,
            } => {
                self.apply_spill_commit(
                    *anchor_vertex,
                    target_cells,
                    values.clone(),
                    delta,
                    log,
                    computed_writes,
                )?;
            }
        }
        Ok(())
    }

    /// Apply a WriteCell effect.
    fn apply_write_cell(
        &mut self,
        vertex_id: VertexId,
        value: &LiteralValue,
        delta: Option<&mut DeltaCollector>,
        mut computed_writes: Option<&mut ComputedWriteBuffer>,
    ) -> Result<(), ExcelError> {
        if let Some(d) = delta
            && d.mode != DeltaMode::Off
        {
            if let Some(buffer) = computed_writes.as_deref_mut() {
                self.flush_computed_write_buffer(buffer)?;
            }
            if let Some(cell) = self.graph.get_cell_ref_for_vertex(vertex_id) {
                let sheet_name = self.graph.sheet_name(cell.sheet_id);
                let old = self
                    .read_cell_value(sheet_name, cell.coord.row() + 1, cell.coord.col() + 1)
                    .unwrap_or(LiteralValue::Empty);
                if old != *value {
                    d.record_cell(cell.sheet_id, cell.coord.row(), cell.coord.col());
                }
            }
        }
        self.graph.update_vertex_value(vertex_id, value.clone());
        self.record_vertex_value_to_overlay(vertex_id, value, computed_writes)?;
        Ok(())
    }

    /// Apply a SpillClear effect.
    fn apply_spill_clear(
        &mut self,
        anchor_vertex: VertexId,
        delta: Option<&mut DeltaCollector>,
        log: Option<&mut ChangeLog>,
        computed_writes: Option<&mut ComputedWriteBuffer>,
    ) -> Result<(), ExcelError> {
        if let Some(buffer) = computed_writes {
            self.flush_computed_write_buffer(buffer)?;
        }

        let spill_cells = self
            .graph
            .spill_cells_for_anchor(anchor_vertex)
            .map(|cells| cells.to_vec())
            .unwrap_or_default();
        if spill_cells.is_empty() {
            return Ok(());
        }

        // Snapshot for ChangeLog before clearing.
        let snapshot = if log.is_some() {
            self.snapshot_spill_for_anchor(anchor_vertex)
        } else {
            None
        };

        // Record delta for cleared cells.
        if let Some(d) = delta
            && d.mode != DeltaMode::Off
        {
            let empty = LiteralValue::Empty;
            for cell in spill_cells.iter() {
                let sheet_name = self.graph.sheet_name(cell.sheet_id);
                let old = self
                    .get_cell_value(sheet_name, cell.coord.row() + 1, cell.coord.col() + 1)
                    .unwrap_or(LiteralValue::Empty);
                if old != empty {
                    d.record_cell(cell.sheet_id, cell.coord.row(), cell.coord.col());
                }
            }
        }

        self.graph.clear_spill_region(anchor_vertex);
        if let Some(scope) = Self::formula_plane_region_from_cells(&spill_cells) {
            self.record_formula_plane_structural_change(scope);
        }

        // Mirror Empty to Arrow overlay for cleared cells.
        if self.config.arrow_storage_enabled
            && self.config.delta_overlay_enabled
            && self.config.write_formula_overlay_enabled
        {
            let empty = LiteralValue::Empty;
            for cell in spill_cells.iter() {
                let sheet_name = self.graph.sheet_name(cell.sheet_id).to_string();
                self.mirror_value_to_computed_overlay(
                    &sheet_name,
                    cell.coord.row() + 1,
                    cell.coord.col() + 1,
                    &empty,
                );
            }
        }

        // ChangeLog.
        if let Some(log) = log
            && let Some(old) = snapshot
        {
            log.record(ChangeEvent::SpillCleared {
                anchor: anchor_vertex,
                old,
            });
        }
        Ok(())
    }

    /// Apply a SpillCommit effect.
    fn apply_spill_commit(
        &mut self,
        anchor_vertex: VertexId,
        target_cells: &[CellRef],
        values: Vec<Vec<LiteralValue>>,
        delta: Option<&mut DeltaCollector>,
        log: Option<&mut ChangeLog>,
        computed_writes: Option<&mut ComputedWriteBuffer>,
    ) -> Result<(), ExcelError> {
        if let Some(buffer) = computed_writes {
            self.flush_computed_write_buffer(buffer)?;
        }

        // Snapshot for ChangeLog before commit.
        let old_snapshot = if log.is_some() {
            self.snapshot_spill_for_anchor(anchor_vertex)
        } else {
            None
        };

        // Delegate to existing commit_spill_and_mirror for delta + overlay logic.
        self.commit_spill_and_mirror(
            anchor_vertex,
            target_cells,
            values.clone(),
            delta,
            None, // overwritable_formulas already validated in plan phase
        )?;

        // ChangeLog.
        if let Some(log) = log {
            log.record(ChangeEvent::SpillCommitted {
                anchor: anchor_vertex,
                old: old_snapshot,
                new: SpillSnapshot {
                    target_cells: target_cells.to_vec(),
                    values,
                },
            });
        }
        Ok(())
    }

    /// Snapshot a spill region for ChangeLog recording.
    ///
    /// Extracted from `VertexEditor::snapshot_spill_for_anchor` to be usable
    /// without creating a `VertexEditor`.
    fn snapshot_spill_for_anchor(&self, anchor: VertexId) -> Option<SpillSnapshot> {
        let cells = self.graph.spill_cells_for_anchor(anchor)?.to_vec();
        if cells.is_empty() {
            return None;
        }

        let max = self.config.spill.max_spill_cells as usize;
        let mut cells = cells;
        if cells.len() > max {
            cells.truncate(max);
        }

        let first = *cells.first().expect("non-empty spill cells");
        let sheet_name = self.graph.sheet_name(first.sheet_id).to_string();
        let row0 = first.coord.row();
        let col0 = first.coord.col();

        let mut max_row = row0;
        let mut max_col = col0;
        let mut by_coord: FxHashMap<(u32, u32), LiteralValue> = FxHashMap::default();
        for cell in &cells {
            max_row = max_row.max(cell.coord.row());
            max_col = max_col.max(cell.coord.col());
            let v = self
                .get_cell_value(&sheet_name, cell.coord.row() + 1, cell.coord.col() + 1)
                .unwrap_or(LiteralValue::Empty);
            by_coord.insert((cell.coord.row(), cell.coord.col()), v);
        }

        let rows = (max_row - row0 + 1) as usize;
        let cols = (max_col - col0 + 1) as usize;
        let mut values: Vec<Vec<LiteralValue>> = Vec::with_capacity(rows);
        for r in 0..rows {
            let mut row: Vec<LiteralValue> = Vec::with_capacity(cols);
            for c in 0..cols {
                row.push(
                    by_coord
                        .get(&(row0 + r as u32, col0 + c as u32))
                        .cloned()
                        .unwrap_or(LiteralValue::Empty),
                );
            }
            values.push(row);
        }

        Some(SpillSnapshot {
            target_cells: cells,
            values,
        })
    }

    fn flush_before_range_dependent_vertex(
        &mut self,
        vertex_id: VertexId,
        computed_writes: &mut ComputedWriteBuffer,
    ) -> Result<(), ExcelError> {
        if self.graph.get_range_dependencies(vertex_id).is_some() {
            self.flush_computed_write_buffer(computed_writes)?;
        }
        Ok(())
    }

    fn plan_vertex_effects_with_computed_flush(
        &mut self,
        vertex_id: VertexId,
        computed_value: LiteralValue,
        overwritable_formulas: Option<&rustc_hash::FxHashSet<VertexId>>,
        computed_writes: &mut ComputedWriteBuffer,
    ) -> Result<Vec<Effect>, ExcelError> {
        if matches!(&computed_value, LiteralValue::Array(_)) {
            self.flush_computed_write_buffer(computed_writes)?;
        }
        self.plan_vertex_effects(vertex_id, computed_value, overwritable_formulas)
    }

    // ── Layer evaluation via effects pipeline ──────────────────────────────

    fn evaluate_small_layer_direct_effects(
        &mut self,
        layer: &super::scheduler::Layer,
        mut delta: Option<&mut DeltaCollector>,
        mut log: Option<&mut ChangeLog>,
        cancel_flag: Option<&AtomicBool>,
        cancel_check_every: usize,
        cancel_message: &'static str,
    ) -> Result<usize, ExcelError> {
        for (i, &vertex_id) in layer.vertices.iter().enumerate() {
            if cancel_check_every > 0
                && i % cancel_check_every == 0
                && cancel_flag.is_some_and(|flag| flag.load(Ordering::Relaxed))
            {
                return Err(ExcelError::new(ExcelErrorKind::Cancelled)
                    .with_message(cancel_message.to_string()));
            }
            let value = match self.evaluate_vertex_immutable(vertex_id) {
                Ok(v) => v,
                Err(e) => LiteralValue::Error(e),
            };
            let effects = self.plan_vertex_effects(vertex_id, value, None)?;
            for effect in &effects {
                self.apply_effect_with_computed_writes(
                    effect,
                    delta.as_deref_mut(),
                    log.as_deref_mut(),
                    None,
                )?;
            }
        }
        Ok(layer.vertices.len())
    }

    /// Evaluate a layer sequentially using the effects pipeline.
    fn evaluate_layer_sequential_effects(
        &mut self,
        layer: &super::scheduler::Layer,
    ) -> Result<usize, ExcelError> {
        if layer.vertices.len() < COMPUTED_WRITE_COALESCING_MIN_LAYER_WIDTH {
            return self.evaluate_small_layer_direct_effects(
                layer,
                None,
                None,
                None,
                0,
                "Evaluation cancelled within layer",
            );
        }

        let mut computed_writes = ComputedWriteBuffer::default();
        for &vertex_id in &layer.vertices {
            self.flush_before_range_dependent_vertex(vertex_id, &mut computed_writes)?;
            let value = match self.evaluate_vertex_immutable(vertex_id) {
                Ok(v) => v,
                Err(e) => LiteralValue::Error(e),
            };
            let effects = match self.plan_vertex_effects_with_computed_flush(
                vertex_id,
                value,
                None,
                &mut computed_writes,
            ) {
                Ok(effects) => effects,
                Err(e) => {
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                    return Err(e);
                }
            };
            for effect in &effects {
                if let Err(e) = self.apply_effect_with_computed_writes(
                    effect,
                    None,
                    None,
                    Some(&mut computed_writes),
                ) {
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                    return Err(e);
                }
            }
        }
        self.flush_computed_write_buffer(&mut computed_writes)?;
        Ok(layer.vertices.len())
    }

    /// Evaluate a layer sequentially with delta collection via effects pipeline.
    fn evaluate_layer_sequential_with_delta_effects(
        &mut self,
        layer: &super::scheduler::Layer,
        delta: &mut DeltaCollector,
    ) -> Result<usize, ExcelError> {
        if layer.vertices.len() < COMPUTED_WRITE_COALESCING_MIN_LAYER_WIDTH {
            return self.evaluate_small_layer_direct_effects(
                layer,
                Some(delta),
                None,
                None,
                0,
                "Evaluation cancelled within layer",
            );
        }

        let mut computed_writes = ComputedWriteBuffer::default();
        for &vertex_id in &layer.vertices {
            self.flush_before_range_dependent_vertex(vertex_id, &mut computed_writes)?;
            let value = match self.evaluate_vertex_immutable(vertex_id) {
                Ok(v) => v,
                Err(e) => LiteralValue::Error(e),
            };
            let effects = match self.plan_vertex_effects_with_computed_flush(
                vertex_id,
                value,
                None,
                &mut computed_writes,
            ) {
                Ok(effects) => effects,
                Err(e) => {
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                    return Err(e);
                }
            };
            for effect in &effects {
                if let Err(e) = self.apply_effect_with_computed_writes(
                    effect,
                    Some(delta),
                    None,
                    Some(&mut computed_writes),
                ) {
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                    return Err(e);
                }
            }
        }
        self.flush_computed_write_buffer(&mut computed_writes)?;
        Ok(layer.vertices.len())
    }

    /// Evaluate a layer sequentially with cancellation support via effects pipeline.
    fn evaluate_layer_sequential_cancellable_effects(
        &mut self,
        layer: &super::scheduler::Layer,
        cancel_flag: &AtomicBool,
    ) -> Result<usize, ExcelError> {
        if layer.vertices.len() < COMPUTED_WRITE_COALESCING_MIN_LAYER_WIDTH {
            return self.evaluate_small_layer_direct_effects(
                layer,
                None,
                None,
                Some(cancel_flag),
                256,
                "Evaluation cancelled within layer",
            );
        }

        let mut computed_writes = ComputedWriteBuffer::default();
        for (i, &vertex_id) in layer.vertices.iter().enumerate() {
            if i % 256 == 0 && cancel_flag.load(Ordering::Relaxed) {
                self.flush_computed_write_buffer(&mut computed_writes)?;
                return Err(ExcelError::new(ExcelErrorKind::Cancelled)
                    .with_message("Evaluation cancelled within layer".to_string()));
            }
            self.flush_before_range_dependent_vertex(vertex_id, &mut computed_writes)?;
            let value = match self.evaluate_vertex_immutable(vertex_id) {
                Ok(v) => v,
                Err(e) => LiteralValue::Error(e),
            };
            let effects = match self.plan_vertex_effects_with_computed_flush(
                vertex_id,
                value,
                None,
                &mut computed_writes,
            ) {
                Ok(effects) => effects,
                Err(e) => {
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                    return Err(e);
                }
            };
            for effect in &effects {
                if let Err(e) = self.apply_effect_with_computed_writes(
                    effect,
                    None,
                    None,
                    Some(&mut computed_writes),
                ) {
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                    return Err(e);
                }
            }
        }
        self.flush_computed_write_buffer(&mut computed_writes)?;
        Ok(layer.vertices.len())
    }

    /// Evaluate a layer sequentially with more frequent cancellation for demand-driven eval.
    fn evaluate_layer_sequential_cancellable_demand_driven_effects(
        &mut self,
        layer: &super::scheduler::Layer,
        cancel_flag: &AtomicBool,
    ) -> Result<usize, ExcelError> {
        if layer.vertices.len() < COMPUTED_WRITE_COALESCING_MIN_LAYER_WIDTH {
            return self.evaluate_small_layer_direct_effects(
                layer,
                None,
                None,
                Some(cancel_flag),
                128,
                "Demand-driven evaluation cancelled within layer",
            );
        }

        let mut computed_writes = ComputedWriteBuffer::default();
        for (i, &vertex_id) in layer.vertices.iter().enumerate() {
            if i % 128 == 0 && cancel_flag.load(Ordering::Relaxed) {
                self.flush_computed_write_buffer(&mut computed_writes)?;
                return Err(ExcelError::new(ExcelErrorKind::Cancelled)
                    .with_message("Demand-driven evaluation cancelled within layer".to_string()));
            }
            self.flush_before_range_dependent_vertex(vertex_id, &mut computed_writes)?;
            let value = match self.evaluate_vertex_immutable(vertex_id) {
                Ok(v) => v,
                Err(e) => LiteralValue::Error(e),
            };
            let effects = match self.plan_vertex_effects_with_computed_flush(
                vertex_id,
                value,
                None,
                &mut computed_writes,
            ) {
                Ok(effects) => effects,
                Err(e) => {
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                    return Err(e);
                }
            };
            for effect in &effects {
                if let Err(e) = self.apply_effect_with_computed_writes(
                    effect,
                    None,
                    None,
                    Some(&mut computed_writes),
                ) {
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                    return Err(e);
                }
            }
        }
        self.flush_computed_write_buffer(&mut computed_writes)?;
        Ok(layer.vertices.len())
    }

    /// Evaluate a layer in parallel, applying via effects pipeline.
    fn evaluate_layer_parallel_effects(
        &mut self,
        layer: &super::scheduler::Layer,
    ) -> Result<usize, ExcelError> {
        use rayon::prelude::*;

        let thread_pool = self.thread_pool.as_ref().unwrap().clone();

        let mut phase1: Vec<VertexId> = Vec::new();
        let mut phase2: Vec<VertexId> = Vec::new();
        for &vid in &layer.vertices {
            if self.graph.get_range_dependencies(vid).is_some() {
                phase2.push(vid);
            } else {
                phase1.push(vid);
            }
        }

        let inflight: rustc_hash::FxHashSet<VertexId> = layer.vertices.iter().copied().collect();
        let mut applied = 0usize;

        for group in [&phase1[..], &phase2[..]] {
            if group.is_empty() {
                continue;
            }
            let mut computed_writes = ComputedWriteBuffer::default();

            let results: Result<Vec<(VertexId, LiteralValue)>, ExcelError> =
                thread_pool.install(|| {
                    group
                        .par_iter()
                        .map(
                            |&vertex_id| match self.evaluate_vertex_immutable(vertex_id) {
                                Ok(v) => Ok((vertex_id, v)),
                                Err(e) => Ok((vertex_id, LiteralValue::Error(e))),
                            },
                        )
                        .collect()
                });

            match results {
                Ok(vertex_results) => {
                    // Arrays first, then scalars — establishes spill regions before
                    // scalar results that might land inside a spilled region.
                    let mut arrays: Vec<(VertexId, LiteralValue)> = Vec::new();
                    let mut others: Vec<(VertexId, LiteralValue)> = Vec::new();
                    for (vertex_id, result) in vertex_results {
                        if matches!(result, LiteralValue::Array(_)) {
                            arrays.push((vertex_id, result));
                        } else {
                            others.push((vertex_id, result));
                        }
                    }
                    for (vertex_id, result) in arrays {
                        let effects = match self.plan_vertex_effects_with_computed_flush(
                            vertex_id,
                            result,
                            Some(&inflight),
                            &mut computed_writes,
                        ) {
                            Ok(effects) => effects,
                            Err(e) => {
                                self.flush_computed_write_buffer(&mut computed_writes)?;
                                return Err(e);
                            }
                        };
                        for effect in &effects {
                            if let Err(e) = self.apply_effect_with_computed_writes(
                                effect,
                                None,
                                None,
                                Some(&mut computed_writes),
                            ) {
                                self.flush_computed_write_buffer(&mut computed_writes)?;
                                return Err(e);
                            }
                        }
                        applied = applied.saturating_add(1);
                    }
                    // Make all array spill/top-left writes visible before scalar effects in this group.
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                    for (vertex_id, result) in others {
                        let effects = match self.plan_vertex_effects_with_computed_flush(
                            vertex_id,
                            result,
                            Some(&inflight),
                            &mut computed_writes,
                        ) {
                            Ok(effects) => effects,
                            Err(e) => {
                                self.flush_computed_write_buffer(&mut computed_writes)?;
                                return Err(e);
                            }
                        };
                        for effect in &effects {
                            if let Err(e) = self.apply_effect_with_computed_writes(
                                effect,
                                None,
                                None,
                                Some(&mut computed_writes),
                            ) {
                                self.flush_computed_write_buffer(&mut computed_writes)?;
                                return Err(e);
                            }
                        }
                        applied = applied.saturating_add(1);
                    }
                    // Flush at the group boundary; phase1 must be visible before phase2.
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                }
                Err(e) => {
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                    return Err(e);
                }
            }
        }

        Ok(applied)
    }

    /// Evaluate a layer in parallel with delta collection via effects pipeline.
    fn evaluate_layer_parallel_with_delta_effects(
        &mut self,
        layer: &super::scheduler::Layer,
        delta: &mut DeltaCollector,
    ) -> Result<usize, ExcelError> {
        use rayon::prelude::*;

        let thread_pool = self.thread_pool.as_ref().unwrap().clone();

        let mut phase1: Vec<VertexId> = Vec::new();
        let mut phase2: Vec<VertexId> = Vec::new();
        for &vid in &layer.vertices {
            if self.graph.get_range_dependencies(vid).is_some() {
                phase2.push(vid);
            } else {
                phase1.push(vid);
            }
        }

        let inflight: rustc_hash::FxHashSet<VertexId> = layer.vertices.iter().copied().collect();
        let mut applied = 0usize;

        for group in [&phase1[..], &phase2[..]] {
            if group.is_empty() {
                continue;
            }
            let mut computed_writes = ComputedWriteBuffer::default();
            let results: Result<Vec<(VertexId, LiteralValue)>, ExcelError> =
                thread_pool.install(|| {
                    group
                        .par_iter()
                        .map(
                            |&vertex_id| match self.evaluate_vertex_immutable(vertex_id) {
                                Ok(v) => Ok((vertex_id, v)),
                                Err(e) => Ok((vertex_id, LiteralValue::Error(e))),
                            },
                        )
                        .collect()
                });

            match results {
                Ok(vertex_results) => {
                    let mut arrays: Vec<(VertexId, LiteralValue)> = Vec::new();
                    let mut others: Vec<(VertexId, LiteralValue)> = Vec::new();
                    for (vertex_id, result) in vertex_results {
                        if matches!(result, LiteralValue::Array(_)) {
                            arrays.push((vertex_id, result));
                        } else {
                            others.push((vertex_id, result));
                        }
                    }
                    for (vertex_id, result) in arrays {
                        let effects = match self.plan_vertex_effects_with_computed_flush(
                            vertex_id,
                            result,
                            Some(&inflight),
                            &mut computed_writes,
                        ) {
                            Ok(effects) => effects,
                            Err(e) => {
                                self.flush_computed_write_buffer(&mut computed_writes)?;
                                return Err(e);
                            }
                        };
                        for effect in &effects {
                            if let Err(e) = self.apply_effect_with_computed_writes(
                                effect,
                                Some(delta),
                                None,
                                Some(&mut computed_writes),
                            ) {
                                self.flush_computed_write_buffer(&mut computed_writes)?;
                                return Err(e);
                            }
                        }
                        applied = applied.saturating_add(1);
                    }
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                    for (vertex_id, result) in others {
                        let effects = match self.plan_vertex_effects_with_computed_flush(
                            vertex_id,
                            result,
                            Some(&inflight),
                            &mut computed_writes,
                        ) {
                            Ok(effects) => effects,
                            Err(e) => {
                                self.flush_computed_write_buffer(&mut computed_writes)?;
                                return Err(e);
                            }
                        };
                        for effect in &effects {
                            if let Err(e) = self.apply_effect_with_computed_writes(
                                effect,
                                Some(delta),
                                None,
                                Some(&mut computed_writes),
                            ) {
                                self.flush_computed_write_buffer(&mut computed_writes)?;
                                return Err(e);
                            }
                        }
                        applied = applied.saturating_add(1);
                    }
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                }
                Err(e) => {
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                    return Err(e);
                }
            }
        }

        Ok(applied)
    }

    /// Evaluate a layer in parallel with cancellation support via effects pipeline.
    fn evaluate_layer_parallel_cancellable_effects(
        &mut self,
        layer: &super::scheduler::Layer,
        cancel_flag: &AtomicBool,
    ) -> Result<usize, ExcelError> {
        use rayon::prelude::*;

        let thread_pool = self.thread_pool.as_ref().unwrap().clone();

        if cancel_flag.load(Ordering::Relaxed) {
            return Err(ExcelError::new(ExcelErrorKind::Cancelled)
                .with_message("Parallel evaluation cancelled before starting".to_string()));
        }

        let mut phase1: Vec<VertexId> = Vec::new();
        let mut phase2: Vec<VertexId> = Vec::new();
        for &vid in &layer.vertices {
            if self.graph.get_range_dependencies(vid).is_some() {
                phase2.push(vid);
            } else {
                phase1.push(vid);
            }
        }

        let inflight: rustc_hash::FxHashSet<VertexId> = layer.vertices.iter().copied().collect();
        let mut applied = 0usize;

        for group in [&phase1[..], &phase2[..]] {
            if group.is_empty() {
                continue;
            }
            let mut computed_writes = ComputedWriteBuffer::default();

            let results: Result<Vec<(VertexId, LiteralValue)>, ExcelError> =
                thread_pool.install(|| {
                    group
                        .par_iter()
                        .map(|&vertex_id| {
                            if cancel_flag.load(Ordering::Relaxed) {
                                return Err(ExcelError::new(ExcelErrorKind::Cancelled)
                                    .with_message(
                                        "Parallel evaluation cancelled during execution"
                                            .to_string(),
                                    ));
                            }
                            match self.evaluate_vertex_immutable(vertex_id) {
                                Ok(v) => Ok((vertex_id, v)),
                                Err(e) => Ok((vertex_id, LiteralValue::Error(e))),
                            }
                        })
                        .collect()
                });

            match results {
                Ok(vertex_results) => {
                    let mut arrays: Vec<(VertexId, LiteralValue)> = Vec::new();
                    let mut others: Vec<(VertexId, LiteralValue)> = Vec::new();
                    for (vertex_id, result) in vertex_results {
                        if matches!(result, LiteralValue::Array(_)) {
                            arrays.push((vertex_id, result));
                        } else {
                            others.push((vertex_id, result));
                        }
                    }
                    for (vertex_id, result) in arrays {
                        let effects = match self.plan_vertex_effects_with_computed_flush(
                            vertex_id,
                            result,
                            Some(&inflight),
                            &mut computed_writes,
                        ) {
                            Ok(effects) => effects,
                            Err(e) => {
                                self.flush_computed_write_buffer(&mut computed_writes)?;
                                return Err(e);
                            }
                        };
                        for effect in &effects {
                            if let Err(e) = self.apply_effect_with_computed_writes(
                                effect,
                                None,
                                None,
                                Some(&mut computed_writes),
                            ) {
                                self.flush_computed_write_buffer(&mut computed_writes)?;
                                return Err(e);
                            }
                        }
                        applied = applied.saturating_add(1);
                    }
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                    for (vertex_id, result) in others {
                        let effects = match self.plan_vertex_effects_with_computed_flush(
                            vertex_id,
                            result,
                            Some(&inflight),
                            &mut computed_writes,
                        ) {
                            Ok(effects) => effects,
                            Err(e) => {
                                self.flush_computed_write_buffer(&mut computed_writes)?;
                                return Err(e);
                            }
                        };
                        for effect in &effects {
                            if let Err(e) = self.apply_effect_with_computed_writes(
                                effect,
                                None,
                                None,
                                Some(&mut computed_writes),
                            ) {
                                self.flush_computed_write_buffer(&mut computed_writes)?;
                                return Err(e);
                            }
                        }
                        applied = applied.saturating_add(1);
                    }
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                }
                Err(e) => {
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                    return Err(e);
                }
            }
        }

        Ok(applied)
    }

    // ── Top-level evaluate_all_logged ───────────────────────────────────────

    /// Evaluate all dirty/volatile vertices, recording effects into a ChangeLog.
    ///
    /// This is the same flow as `evaluate_all` but threads a ChangeLog through
    /// every effect application so that spill commits/clears are captured.
    pub fn evaluate_all_logged(&mut self, log: &mut ChangeLog) -> Result<EvalResult, ExcelError> {
        self.observe_evaluation_resource_request(EvaluationRequestKind::FullLogged, |engine| {
            engine.evaluate_all_logged_unobserved(log)
        })
    }

    fn evaluate_all_logged_unobserved(
        &mut self,
        log: &mut ChangeLog,
    ) -> Result<EvalResult, ExcelError> {
        self.observe_function_semantic_epoch()?;
        self.begin_evaluation_request();
        let _source_cache = self.source_cache_session();
        self.validate_deterministic_mode()?;
        if self.config.defer_graph_building {
            self.build_graph_all()?;
        }
        if self.graph.formula_authority().active_span_count() > 0 {
            return self.evaluate_authoritative_formula_plane_all();
        }
        self.reset_virtual_dep_telemetry_if_disabled();
        let start = crate::instant::FzInstant::now();
        let mut computed_vertices = 0;
        let mut cycle_errors = 0;

        let mut replan_iterations = 0;
        const MAX_REPLAN: usize = 5;
        let mut telemetry = self
            .config
            .enable_virtual_dep_telemetry
            .then(|| self.start_virtual_dep_telemetry());

        log.begin_compound(format!("evaluate_all(epoch={})", self.recalc_epoch));

        let result = (|| -> Result<EvalResult, ExcelError> {
            loop {
                let to_evaluate = self.graph.get_evaluation_vertices();
                if to_evaluate.is_empty() {
                    if let Some(t) = telemetry.as_mut()
                        && t.bailout_reason.is_none()
                    {
                        t.bailout_reason = Some("no_work");
                    }
                    break;
                }

                let (schedule, old_vdeps, meta) = self.create_evaluation_schedule(&to_evaluate)?;
                if let Some(t) = telemetry.as_mut() {
                    Self::accumulate_schedule_meta(t, &meta);
                }

                // Walk units in condensation order: stamp cycles at their
                // position, evaluate layers with ChangeLog recording.
                for &unit in &schedule.units {
                    match unit {
                        ScheduleUnit::Cycle(i) => {
                            // Journal integration (design doc §4 last row): the
                            // ChangeLog in this path only records SpillClear /
                            // SpillCommit events; WriteCell effects are never
                            // logged (see `apply_write_cell`). Runtime SCC tasks
                            // write values directly and never spill (§7.9 stamps
                            // would-be anchors), and their spill *teardown* is the
                            // same unlogged `stamp_cycle_error` the Static path
                            // already uses here — so direct commits coexist with
                            // the journal cleanly, with identical semantics to
                            // Static. Pinned by `scc_runtime_cycles` tests.
                            if self.handle_cycle_unit(schedule.unit_cycle(i), None, None, None)? > 0
                            {
                                cycle_errors += 1;
                            }
                        }
                        ScheduleUnit::Layer(i) => {
                            computed_vertices +=
                                self.evaluate_layer_logged(schedule.unit_layer(i), log)?;
                        }
                    }
                }

                let changed_vertices = self.changed_virtual_dep_vertices(&to_evaluate, &old_vdeps);
                if let Some(t) = telemetry.as_mut() {
                    t.changed_vdeps_total += changed_vertices.len();
                }
                self.resource_checkpoint(0)?;
                self.graph.clear_dirty_flags(&to_evaluate);
                for v in &changed_vertices {
                    self.graph.set_dirty(*v, true);
                }

                if changed_vertices.is_empty() {
                    if let Some(t) = telemetry.as_mut() {
                        t.bailout_reason = Some("converged");
                    }
                    break;
                }
                if replan_iterations >= MAX_REPLAN {
                    if let Some(mut t) = telemetry.take() {
                        t.bailout_reason = Some("max_replan");
                        t.replan_iterations = replan_iterations;
                        self.last_virtual_dep_telemetry = t;
                    }
                    return Err(
                        self.replan_exhausted_error(MAX_REPLAN, "dynamic dependency evaluation")
                    );
                }
                replan_iterations += 1;
            }

            if let Some(mut t) = telemetry {
                t.replan_iterations = replan_iterations;
                self.last_virtual_dep_telemetry = t;
            }

            self.redirty_for_next_recalc();
            self.recalc_epoch = self.recalc_epoch.wrapping_add(1);

            Ok(EvalResult {
                computed_vertices,
                cycle_errors,
                elapsed: start.elapsed(),
            })
        })();
        log.end_compound();
        result
    }

    /// Evaluate a single layer with ChangeLog recording.
    fn evaluate_layer_logged(
        &mut self,
        layer: &super::scheduler::Layer,
        log: &mut ChangeLog,
    ) -> Result<usize, ExcelError> {
        self.resource_checkpoint(layer.vertices.len() as u64)?;
        let mut computed_writes = ComputedWriteBuffer::default();
        for &vertex_id in &layer.vertices {
            self.flush_before_range_dependent_vertex(vertex_id, &mut computed_writes)?;
            let value = match self.evaluate_vertex_immutable(vertex_id) {
                Ok(v) => v,
                Err(e) => LiteralValue::Error(e),
            };
            let effects = match self.plan_vertex_effects_with_computed_flush(
                vertex_id,
                value,
                None,
                &mut computed_writes,
            ) {
                Ok(effects) => effects,
                Err(e) => {
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                    return Err(e);
                }
            };
            for effect in &effects {
                if let Err(e) = self.apply_effect_with_computed_writes(
                    effect,
                    None,
                    Some(log),
                    Some(&mut computed_writes),
                ) {
                    self.flush_computed_write_buffer(&mut computed_writes)?;
                    return Err(e);
                }
            }
        }
        self.flush_computed_write_buffer(&mut computed_writes)?;
        Ok(layer.vertices.len())
    }
}