Struct Engine 

pub struct Engine<R> {
    pub config: EvalConfig,
    pub recalc_epoch: u64,
    /* private fields */
}

Fields

config: EvalConfig

recalc_epoch: u64

Implementations

impl<R: EvaluationContext> Engine<R>

pub fn current_read_affected_closure( &self, roots: &[AffectedRoot], limits: ClosureLimits, ) -> Result<CurrentReadClosure<'_>, ClosureError>

Immutable, request-local relation query. Output borrows the engine so a policy decision cannot retain it across a safe mutable engine operation. Negative facts apply only to the reported relation and declared unknowns.

impl<R: EvaluationContext> Engine<R>

pub fn begin_recalc( &mut self, options: RecalcJobOptions, ) -> Result<(), RecalcJobError>

Start an explicit job in O(1). Planning and clock sampling happen in the first step. Returns AlreadyPending for either kind of continuation.

pub fn has_active_recalc_job(&self) -> bool

True only for an explicit job. Implicit Phase 1 continuations are reported by has_pending_resumable_evaluation.

pub fn prioritize_recalc( &mut self, targets: &[EvaluationTarget], ) -> Result<(), RecalcJobError>

Last request wins; materialization is deferred until the next step.

pub fn cancel_recalc(&mut self) -> Option<StepReport>

Preserve installed values and dirtiness; cancellation never advances the epoch. Returns None without touching state when the engine is poisoned.

pub fn step_recalc( &mut self, stop: EvaluationStop, ) -> Result<StepReport, RecalcJobError>

Execute the next soft-budgeted step. Only installed units become clean.

A returned evaluation error ends the job and leaves unfinished work dirty. Function panics become typed cell errors and operation diagnostics. Engine-internal unwinds propagate and permanently poison the engine (see the module documentation).

pub fn recalc_with( &mut self, options: RecalcJobOptions, stop_per_step: EvaluationStop, on_step: impl FnMut(&mut Self, &StepReport) -> ControlFlow<()>, ) -> Result<RecalcOutcome, RecalcJobError>

Drive an explicit job, invoking the callback after every successful step, including the terminal report. The callback may read, edit, prioritize or cancel the engine. Break pauses an active job; step errors end it.

Finished/Cancelled take precedence over Break on a terminal step. Do not begin a replacement job inside the callback. Callback panics propagate without additional lifecycle cleanup: the job keeps the state it reached before the panic, so an untouched non-terminal job stays active while a finished or cancelled job has already ended. Function panics become typed cell errors as described in resumable.

pub fn has_pending_in_rect( &self, sheet: SheetId, r0: u32, c0: u32, r1: u32, c1: u32, ) -> bool

Zero-based inclusive viewport. Visits only coordinates inside it, including staged formulas; no workbook-wide dirty-set scan.

pub fn pending_cells_in_rect( &self, sheet: SheetId, r0: u32, c0: u32, r1: u32, c1: u32, ) -> TargetEvalDelta

Pending formula cells in a zero-based inclusive viewport, including staged formulas. Work is O(viewport area); reads may still return old values.

impl<R> Engine<R>

where R: EvaluationContext,

pub fn new(resolver: R, config: EvalConfig) -> Self

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 with_thread_pool( resolver: R, config: EvalConfig, thread_pool: Arc<ThreadPool>, ) -> Self

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 workbook_load_limits(&self) -> &WorkbookLoadLimits

pub fn set_workbook_load_limits(&mut self, limits: WorkbookLoadLimits)

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn last_virtual_dep_telemetry(&self) -> &VirtualDepTelemetry

pub fn last_cycle_telemetry(&self) -> &CycleTelemetry

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_evaluation_resource_request_stats( &self, ) -> Option<&EvaluationResourceRequestStats>

Resource observations for the most recently completed public evaluation request.

pub fn evaluation_resource_baseline_stats( &self, ) -> EvaluationResourceBaselineStats

Cumulative resource observations since engine creation or the last telemetry reset.

pub fn evaluation_resource_budgets(&self) -> &EvaluationBudgets

pub fn evaluation_resource_config_diagnostic( &self, ) -> Option<&EvaluationResourceConfigDiagnostic>

At most one diagnostic is emitted for deprecated resource fields.

pub fn reset_evaluation_resource_telemetry(&mut self)

Reset accumulated and last-request observations without reusing request IDs.

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn set_evaluation_resource_budgets(&mut self, budgets: EvaluationBudgets)

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn enable_operation_diagnostics(&mut self, sample_limit: usize)

Enable request-operation evidence before ingestion/evaluation. Each evaluation request resets events; this is not retained-result coverage.

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn configure_operation_diagnostics( &mut self, options: OperationDiagnosticOptions, )

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn disable_operation_diagnostics(&mut self)

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn operation_diagnostics( &self, ) -> Result<Option<OperationDiagnostics>, ExcelError>

pub fn take_operation_diagnostics( &mut self, ) -> Result<Option<OperationDiagnostics>, ExcelError>

Finalize exact request evidence once, without disabling next-request collection.

pub fn virtual_dep_fallback_activations(&self) -> u64

pub fn default_sheet_id(&self) -> SheetId

pub fn default_sheet_name(&self) -> &str

pub fn set_workbook_seed(&mut self, seed: u64)

Update the workbook seed for deterministic RNGs in functions.

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn set_volatile_level(&mut self, level: VolatileLevel)

Set the volatile level policy (Always/OnRecalc/OnOpen)

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn set_temporal_egress(&mut self, policy: TemporalEgress)

Set public temporal materialisation to native values or raw serials.

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn temporal_egress(&self) -> TemporalEgress

pub fn set_deterministic_mode( &mut self, mode: DeterministicMode, ) -> Result<(), ExcelError>

Enable/disable deterministic evaluation mode (fixed clock + timezone).

pub fn set_clock(&mut self, clock: Arc<dyn ClockProvider>)

Inject a custom 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.

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

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

pub fn sheet_id_mut(&mut self, name: &str) -> SheetId

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn sheet_name(&self, id: SheetId) -> &str

pub fn add_sheet(&mut self, name: &str) -> Result<SheetId, ExcelError>

pub fn duplicate_sheet( &mut self, source: &str, new_name: &str, ) -> Result<SheetId, ExcelError>

pub fn remove_sheet(&mut self, sheet_id: SheetId) -> Result<(), ExcelError>

pub fn rename_sheet( &mut self, sheet_id: SheetId, new_name: &str, ) -> Result<(), ExcelError>

pub fn named_ranges_iter(&self) -> impl Iterator<Item = (&String, &NamedRange)>

pub fn sheet_named_ranges_iter( &self, ) -> impl Iterator<Item = (&(SheetId, String), &NamedRange)>

pub fn resolve_name_entry( &self, name: &str, current_sheet: SheetId, ) -> Option<&NamedRange>

pub fn has_name(&self, name: &str, scope_sheet: Option<&str>) -> bool

pub fn resolved_name_value( &self, name: &str, scope_sheet: Option<&str>, ) -> Option<LiteralValue>

The current value of name in the scope denoted by scope_sheet.

Scoping follows Self::has_name: None is workbook scope only.

pub fn cell_in_empty_table(&self, sheet: &str, row: u32, col: u32) -> bool

Whether a cell lies in a logically empty table’s reserved body.

pub fn table_metadata(&self, name: &str) -> Option<TableMetadata>

pub fn tables(&self) -> Vec<TableMetadata>

Metadata for every defined table, ordered by name.

pub fn named_ranges_snapshot(&self) -> Vec<NamedRangeSnapshot>

pub fn named_ranges_snapshot_for_sheet( &self, sheet_id: SheetId, ) -> Vec<NamedRangeSnapshot>

pub fn define_name( &mut self, name: &str, definition: NamedDefinition, scope: NameScope, ) -> Result<(), ExcelError>

pub fn update_name( &mut self, name: &str, definition: NamedDefinition, scope: NameScope, ) -> Result<(), ExcelError>

pub fn delete_name( &mut self, name: &str, scope: NameScope, ) -> Result<(), ExcelError>

pub fn define_table( &mut self, name: &str, range: RangeRef, header_row: bool, headers: Vec<String>, totals_row: bool, ) -> Result<(), ExcelError>

pub fn resize_table( &mut self, name: &str, new_end_row: u32, ) -> Result<TableMetadata, ExcelError>

Resize a native table’s row extent. For history, use an EngineAction.

pub fn resize_table_body( &mut self, name: &str, new_end_row: u32, empty_body: bool, ) -> Result<TableMetadata, ExcelError>

Resize a table, retaining a physical row for a logically empty body.

pub fn define_source_scalar( &mut self, name: &str, version: Option<u64>, ) -> Result<(), ExcelError>

pub fn define_source_table( &mut self, name: &str, version: Option<u64>, ) -> Result<(), ExcelError>

pub fn set_source_scalar_version( &mut self, name: &str, version: Option<u64>, ) -> Result<(), ExcelError>

pub fn set_source_table_version( &mut self, name: &str, version: Option<u64>, ) -> Result<(), ExcelError>

pub fn invalidate_source(&mut self, name: &str) -> Result<(), ExcelError>

pub fn vertex_value(&self, vertex: VertexId) -> Option<LiteralValue>

pub fn graph_cell_value( &self, sheet: &str, row: u32, col: u32, ) -> Option<LiteralValue>

pub fn cell_has_spill_projection(&self, sheet: &str, row: u32, col: u32) -> bool

Whether a cell belongs to a currently committed spill projection.

This indexed ownership query does not read values, calculate spill bounds, prepare formulas, or evaluate the workbook.

pub fn vertex_for_cell(&self, cell: &CellRef) -> Option<VertexId>

pub fn evaluation_vertices(&self) -> Vec<VertexId>

pub fn baseline_stats(&self) -> EngineBaselineStats

Return read-only baseline counters for dispatch benchmarking.

pub fn set_first_load_assume_new(&mut self, enabled: bool)

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn first_load_assume_new(&self) -> bool

pub fn reset_ensure_touched(&mut self)

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn finalize_sheet_index(&mut self, sheet: &str)

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn action<T>( &mut self, name: impl AsRef<str>, f: impl FnOnce(&mut EngineAction<'_, R>) -> Result<T, EditorError>, ) -> Result<T, EditorError>

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_atomic<T>( &mut self, name: impl Into<String>, f: impl FnOnce(&mut EngineAction<'_, R>) -> Result<T, EditorError>, ) -> Result<T, EditorError>

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_journal<T>( &mut self, name: impl Into<String>, f: impl FnOnce(&mut EngineAction<'_, R>) -> Result<T, EditorError>, ) -> Result<(T, ActionJournal), EditorError>

Like action_atomic, but returns the committed journal entry for undo/redo storage.

pub fn action_with_logger<T>( &mut self, log: &mut ChangeLog, name: impl AsRef<str>, f: impl FnOnce(&mut EngineAction<'_, R>) -> Result<T, EditorError>, ) -> Result<T, EditorError>

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 (published only after a successful commit)

pub fn define_name_with_logger( &mut self, log: &mut ChangeLog, name: &str, definition: NamedDefinition, scope: NameScope, ) -> Result<(), EditorError>

pub fn update_name_with_logger( &mut self, log: &mut ChangeLog, name: &str, definition: NamedDefinition, scope: NameScope, ) -> Result<(), EditorError>

pub fn delete_name_with_logger( &mut self, log: &mut ChangeLog, name: &str, scope: NameScope, ) -> Result<(), EditorError>

pub fn edit_with_logger<T>( &mut self, log: &mut ChangeLog, f: impl FnOnce(&mut VertexEditor<'_>) -> T, ) -> Result<T, EditorError>

pub fn undo_logged( &mut self, undo: &mut UndoEngine, log: &mut ChangeLog, ) -> Result<(), EditorError>

Undo the last group still retained by the provided audit log.

Disabled, zero-cap, and evicted history is unavailable on this index-based path. Use an explicit ActionJournal with undo_action when undo must be independent of audit retention.

pub fn redo_logged( &mut self, undo: &mut UndoEngine, log: &mut ChangeLog, ) -> Result<(), EditorError>

pub fn undo_action(&mut self, undo: &mut UndoEngine) -> Result<(), EditorError>

Undo the last committed atomic action using the journal stack.

This path does not require a ChangeLog.

pub fn redo_action(&mut self, undo: &mut UndoEngine) -> Result<(), EditorError>

Redo the last undone atomic action using the journal stack.

This path does not require a ChangeLog.

pub fn set_default_sheet_by_name(&mut self, name: &str)

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn set_default_sheet_by_id(&mut self, id: SheetId)

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn set_sheet_index_mode(&mut self, mode: SheetIndexMode)

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn mark_data_edited(&mut self)

Mark data edited: bump snapshot and set edited flag. Value-only edits keep the stable-topology schedule cache alive.

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn mark_topology_edited(&mut self)

Mark a topology-changing edit: bump snapshot + topology epoch and invalidate cached schedules.

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn sheet_store(&self) -> &SheetStore

Access Arrow sheet store (read-only)

pub fn sheet_store_mut(&mut self) -> &mut SheetStore

Access Arrow sheet store (mutable)

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn has_staged_formulas(&self) -> bool

pub fn staged_formula_count(&self) -> usize

pub fn stage_formula_text( &mut self, sheet: &str, row: u32, col: u32, text: String, )

Stage a formula text instead of inserting into the graph (used when deferring is enabled).

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn clear_staged_formula_text( &mut self, sheet: &str, row: u32, col: u32, ) -> Option<String>

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn clear_staged_formulas_for_sheet(&mut self, sheet: &str)

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn rename_staged_formula_sheet(&mut self, old: &str, new: &str)

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn get_staged_formula_text( &self, sheet: &str, row: u32, col: u32, ) -> Option<String>

Get a staged formula text for a given cell if present (cloned).

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

pub fn take_formula_parse_diagnostics(&mut self) -> Vec<FormulaParseDiagnostic>

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn clear_formula_parse_diagnostics(&mut self)

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn last_formula_ingest_report(&self) -> Option<&FormulaIngestReport>

pub fn formula_ingest_report_total(&self) -> &FormulaIngestReport

pub fn ingest_formula_batches( &mut self, batches: Vec<FormulaIngestBatch>, ) -> Result<FormulaIngestReport, ExcelError>

pub fn handle_formula_parse_error( &mut self, sheet: &str, row: u32, col: u32, formula: &str, message: String, ) -> Result<Option<ASTNode>, ExcelError>

pub fn prepare_graph_for_targets( &mut self, targets: &[EvaluationTarget], options: TargetEvalOptions<'_>, ) -> Result<PreparedTargetGraphReport, ExcelError>

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 build_graph_all(&mut self) -> Result<(), ExcelError>

Build graph for all staged formulas.

pub fn build_graph_for_sheets<'a, I: IntoIterator<Item = &'a str>>( &mut self, sheets: I, ) -> Result<(), ExcelError>

Build graph for specific sheets (consuming only those staged entries).

pub fn begin_bulk_ingest_arrow(&mut self) -> ArrowBulkIngestBuilder<'_, R>

Begin bulk Arrow ingest for base values (Phase A)

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn begin_bulk_update_arrow(&mut self) -> ArrowBulkUpdateBuilder<'_, R>

Begin bulk updates to Arrow store (Phase C)

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn set_row_hidden( &mut self, sheet: &str, row_1based: u32, hidden: bool, source: RowVisibilitySource, ) -> Result<(), EditorError>

pub fn set_rows_hidden( &mut self, sheet: &str, start_row_1based: u32, end_row_1based: u32, hidden: bool, source: RowVisibilitySource, ) -> Result<(), EditorError>

pub fn is_row_hidden( &self, sheet: &str, row_1based: u32, source: Option<RowVisibilitySource>, ) -> Option<bool>

pub fn row_visibility_version(&self, sheet: &str) -> Option<u64>

pub fn insert_rows( &mut self, sheet: &str, before: u32, count: u32, ) -> Result<ShiftSummary, EditorError>

Insert rows (1-based) and mirror into Arrow store when enabled

pub fn delete_rows( &mut self, sheet: &str, start: u32, count: u32, ) -> Result<ShiftSummary, EditorError>

Delete rows (1-based) and mirror into Arrow store when enabled

pub fn insert_columns( &mut self, sheet: &str, before: u32, count: u32, ) -> Result<ShiftSummary, EditorError>

Insert columns (1-based) and mirror into Arrow store when enabled

pub fn delete_columns( &mut self, sheet: &str, start: u32, count: u32, ) -> Result<ShiftSummary, EditorError>

Delete columns (1-based) and mirror into Arrow store when enabled

pub fn overlay_memory_usage(&self) -> usize

Estimated memory usage for computed overlays (formula/spill mirroring).

pub fn set_cell_value( &mut self, sheet: &str, row: u32, col: u32, value: LiteralValue, ) -> Result<(), ExcelError>

Set a cell value

pub fn set_cell_value_ref( &mut self, cell: SheetCellRef<'_>, current_sheet: &str, value: LiteralValue, ) -> Result<(), ExcelError>

pub fn set_cell_formula_ref( &mut self, cell: SheetCellRef<'_>, current_sheet: &str, ast: ASTNode, ) -> Result<(), ExcelError>

pub fn get_cell_value_ref( &self, cell: SheetCellRef<'_>, current_sheet: &str, ) -> Result<Option<LiteralValue>, ExcelError>

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

pub fn set_cell_formula( &mut self, sheet: &str, row: u32, col: u32, ast: ASTNode, ) -> Result<(), ExcelError>

Set a cell formula

pub fn bulk_set_formulas<I>( &mut self, sheet: &str, items: I, ) -> Result<usize, ExcelError>

where I: IntoIterator<Item = (u32, u32, ASTNode)>,

Bulk set many formulas on a sheet. Skips per-cell snapshot bumping and minimizes edge rebuilds.

pub fn declare_dynamic_array_anchor( &mut self, sheet: &str, row: u32, col: u32, ) -> Result<(), ExcelError>

Declare the formula cell at sheet!(row, col) (1-based) a dynamic array anchor whose spill identity comes from the source document, for example an XLSX t="array" formula bound to XLDAPR cell metadata.

This changes only spill references to the anchor (A1#, _xlfn.ANCHORARRAY(A1)). A declared anchor with a committed multi-cell spill resolves to that spill, exactly as an undeclared one. Without a committed spill, a declared anchor whose current result is a scalar (not an error, so not a blocked #SPILL! anchor, and not empty) resolves to its own cell as a 1x1 reference, matching a spilled 1x1 dynamic array. Every other case keeps the #REF! of an undeclared anchor. Undeclared cells are unaffected, and fresh 1x1 results are not given spill identity by function name.

The declaration belongs to the formula vertex. It is dropped when the cell’s formula is replaced, the cell is cleared or overwritten with a value, the vertex is removed (including with its sheet), or a structural row/column edit moves the vertex. A structural edit that only adjusts the formula’s references, without moving the anchor, keeps it. Declaring again re-establishes it.

The anchor and its dependents are marked dirty, so the next evaluation observes the declaration.

Returns #REF! if the sheet does not exist or the cell holds no formula vertex. A formula still staged by deferred graph building has no vertex: build the graph (for example Self::build_graph_all) before declaring.

pub fn declare_fixed_array_formula( &mut self, sheet: &str, row: u32, col: u32, rows: u32, cols: u32, ) -> Result<(), ExcelError>

Declare a legacy array formula with a fixed output rectangle after ingestion and before evaluation. Coordinates are one-based. Replacement, removal or movement of the formula clears the declaration. Single-cell declarations do not register a spill anchor. Requires EvalConfig::family_execution = false to bypass family memoization.

pub fn get_cell_value( &self, sheet: &str, row: u32, col: u32, ) -> Option<LiteralValue>

Get a cell value through the single temporal egress boundary.

pub fn get_range_values( &self, sheet: &str, sr: u32, sc: u32, er: u32, ec: u32, ) -> Vec<Vec<LiteralValue>>

Read a rectangular range through the temporal egress boundary.

pub fn get_cell( &self, sheet: &str, row: u32, col: u32, ) -> Option<(Option<ASTNode>, Option<LiteralValue>)>

Get formula AST (if any) and current stored value for a cell

pub fn begin_batch(&mut self)

Begin batch operations - defer CSR rebuilds for better performance

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn end_batch(&mut self)

End batch operations and trigger CSR rebuild

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn begin_deferred_dirty(&mut self)

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.

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn end_deferred_dirty(&mut self)

End a deferred-dirty scope, flushing the queued propagation when the outermost scope closes. See Engine::begin_deferred_dirty.

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn dirty_propagation_visits(&self) -> u64

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 evaluate_vertex( &mut self, vertex_id: VertexId, ) -> Result<LiteralValue, ExcelError>

pub fn evaluate_targets( &mut self, targets: &[EvaluationTarget], ) -> Result<EvalResult, ExcelError>

Evaluate the necessary mixed producer closure for typed cell, range, name, and table targets.

pub fn evaluate_targets_with_options( &mut self, targets: &[EvaluationTarget], options: TargetEvalOptions<'_>, ) -> Result<EvalResult, ExcelError>

Evaluate typed targets with explicit preparation policy and request controls.

pub fn evaluate_targets_with_delta( &mut self, targets: &[EvaluationTarget], ) -> Result<(EvalResult, TargetEvalDelta), ExcelError>

Evaluate typed targets and return the versioned run/region delta for the request.

pub fn evaluate_until( &mut self, targets: &[(&str, u32, u32)], ) -> Result<EvalResult, ExcelError>

Evaluate only the necessary precedents for specific target cells (demand-driven)

pub fn build_recalc_plan(&self) -> Result<RecalcPlan, ExcelError>

Build a revision-bound compatibility plan covering every prepared formula vertex.

pub fn build_recalc_plan_for_targets( &mut self, targets: &[EvaluationTarget], ) -> Result<RecalcPlan, ExcelError>

Prepare stable typed targets and retain a revision-bound run-local recipe.

pub fn build_recalc_plan_for_targets_with_options( &mut self, targets: &[EvaluationTarget], options: TargetEvalOptions<'_>, ) -> Result<RecalcPlan, ExcelError>

pub fn evaluate_recalc_plan( &mut self, plan: &RecalcPlan, ) -> Result<EvalResult, ExcelError>

Evaluate using a previously constructed compatibility or target plan.

pub fn evaluate_recalc_plan_with_controls( &mut self, plan: &RecalcPlan, cancel: Option<CancelToken>, deadline: Option<Instant>, ) -> Result<EvalResult, ExcelError>

impl<R> Engine<R>

where R: EvaluationContext,

pub fn pending_snapshot_iterative_members(&self) -> usize

Iterative members whose next-request invalidation was deferred by a completed snapshot. This does not establish source-cache seed provenance.

pub fn evaluate_all_for_snapshot( &mut self, cancel: Option<CancelToken>, ) -> Result<EvalResult, ExcelError>

Evaluate a current result snapshot, optionally with cancellation.

This evaluates exactly like Self::evaluate_all (or its cancellable counterpart), but leaves volatile vertices and their dependents Current at return rather than marking them dirty for the next cycle. It does not suppress iterative-SCC redirty or any other freshness check.

Callers retaining the engine must start another evaluation request (evaluate_all, evaluate_until, evaluate_cell, or equivalent) to refresh volatile values. That request restores the deferred volatile redirty before selecting its work. Iterative SCC invalidation is deferred on the same boundary, preserving completed snapshot values as Current. Errors and cancellation never leave the snapshot mode active.

pub fn evaluate_all_until( &mut self, stop: EvaluationStop, ) -> Result<EvaluationProgress, ExcelError>

Evaluate until a soft boundary, preserving installed work for a later call. A family run or cycle may overrun the budget. Cancellation keeps its existing post-work boundary: the observing unit is not completed.

Results are independent of call boundaries, except for iterative cycles created by edits during a pending recalculation. Such new cycles start from the cells’ current values when they form, including values installed by earlier calls; they need not match a fresh, uninterrupted calculation. SCCs already present at the start retain their original recalc seeds.

Function providers without a semantic revision (planning_semantic_revision returns None) are assumed stable for the duration of a logical recalculation. Hosts changing provider behaviour must bump its semantic revision or mark the affected cells dirty.

Load-time mutation APIs, including ArrowBulkIngestBuilder::finish and raw sheet_store_mut access, are unsupported while a resumable recalculation is pending; they do not publish mutation revisions.

pub fn has_pending_resumable_evaluation(&self) -> bool

Whether a logical recalculation is awaiting another resumable call.

pub fn evaluate_all(&mut self) -> Result<EvalResult, ExcelError>

Evaluate all dirty/volatile vertices.

pub fn evaluate_all_with_target_delta( &mut self, ) -> Result<(EvalResult, TargetEvalDelta), ExcelError>

pub fn evaluate_all_with_delta( &mut self, ) -> Result<(EvalResult, EvalDelta), ExcelError>

pub fn evaluate_all_with_delta_policy( &mut self, policy: EvalDeltaCompatibilityPolicy, ) -> Result<(EvalResult, EvalDelta), ExcelError>

pub fn evaluate_cell( &mut self, sheet: &str, row: u32, col: u32, ) -> Result<Option<LiteralValue>, ExcelError>

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_cells( &mut self, targets: &[(&str, u32, u32)], ) -> Result<Vec<Option<LiteralValue>>, ExcelError>

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_cancellable( &mut self, targets: &[(&str, u32, u32)], cancel: CancelToken, ) -> Result<Vec<Option<LiteralValue>>, ExcelError>

pub fn evaluate_cells_with_target_delta( &mut self, targets: &[(&str, u32, u32)], ) -> Result<(Vec<Option<LiteralValue>>, TargetEvalDelta), ExcelError>

pub fn evaluate_cells_with_delta( &mut self, targets: &[(&str, u32, u32)], ) -> Result<(Vec<Option<LiteralValue>>, EvalDelta), ExcelError>

pub fn evaluate_cells_with_delta_policy( &mut self, targets: &[(&str, u32, u32)], policy: EvalDeltaCompatibilityPolicy, ) -> Result<(Vec<Option<LiteralValue>>, EvalDelta), ExcelError>

pub fn get_eval_plan( &self, targets: &[(&str, u32, u32)], ) -> Result<EvalPlan, ExcelError>

Get the evaluation plan for target cells without actually evaluating them

pub fn evaluate_all_cancellable( &mut self, cancel: CancelToken, ) -> Result<EvalResult, ExcelError>

Evaluate all dirty/volatile vertices with cancellation support

pub fn evaluate_until_cancellable( &mut self, targets: &[&str], cancel: CancelToken, ) -> Result<EvalResult, ExcelError>

Evaluate only the necessary precedents for specific target cells with cancellation support

pub fn thread_pool(&self) -> Option<&Arc<ThreadPool>>

Get access to the shared thread pool for parallel evaluation

impl<R> Engine<R>

where R: EvaluationContext,

pub fn evaluate_all_logged( &mut self, log: &mut ChangeLog, ) -> Result<EvalResult, ExcelError>

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.

impl<R: EvaluationContext> Engine<R>

pub fn is_poisoned(&self) -> bool

Whether an engine-internal panic has permanently disabled work.

Reads and inspection remain available, but may expose stale or partially installed values. Discard a poisoned engine; there is no recovery API.

Panics

Infallible mutation methods linked here panic before doing work when poisoned, with “formualizer engine is poisoned by an earlier internal panic; discard it”. Fallible methods return a typed EnginePoisoned error instead.

impl<R> Engine<R>

where R: EvaluationContext,

pub fn adopt_file_sheets<'a, I>( &mut self, names: I, ) -> Result<Vec<SheetId>, ExcelError>

where I: IntoIterator<Item = &'a str>,

Register the sheets of a file being loaded, folding the engine’s seeded default sheet into the file’s first sheet when that is safe.

This is the single entry point every EngineLoadStream implementation must use instead of looping over add_sheet. A freshly constructed Engine is seeded with one default sheet (Sheet1 unless configured otherwise). Appending the file’s sheets next to that seed leaves a phantom sheet that does not exist in the file and shifts every SHEET()/SHEETS() result and every SheetId by one (issue #332).

Behaviour:

• Duplicate names are rejected. Sheet names are unique and case-insensitive in Excel; add_sheet is idempotent, so two file sheets sharing a name would silently merge and the second sheet’s cells would overwrite the first’s. That is silent data loss, so it is an error instead.
• The default sheet is only folded into a fresh engine. If the engine already holds user content the default sheet is left exactly as-is and the file’s sheets are added alongside it. Renaming a populated sheet would hand the user’s sheet to the file, letting the file’s cells overwrite it and rewriting formulas that mention it; existing data is always preserved instead.
• The fold is a rename, so the default SheetId and the sheet’s position in the Arrow store are reused by the file’s first sheet and the remaining sheets keep the file’s order.

Returns the SheetId of each name, in the order given.

impl<R: EvaluationContext> Engine<R>

pub fn inspect_cell_result( &self, cell: &CellAddress, ) -> Result<CellResultState, InspectError>

Read result presence, currentness and committed spill ownership without reconstructing or pretty-printing a formula AST. Does not evaluate, prepare dependency state, or materialize compressed formula members.

pub fn inspect_cell( &self, cell: &CellAddress, options: &SnapshotOptions, ) -> Result<CellSnapshotReport, InspectError>

Inspect one cell without evaluating or preparing workbook state.

pub fn precedents( &self, cell: &CellAddress, options: &PrecedentOptions, ) -> Result<PrecedentReport, InspectError>

Return source-ordered, first-occurrence-deduplicated declared formula references for a cell.

pub fn dependents( &self, cell: &CellAddress, options: &DependentsOptions, ) -> Result<DependentsReport, InspectError>

Return direct and compressed-range readers of a cell. Discovery is bounded before candidate materialization.

pub fn trace( &self, roots: &[CellAddress], options: &TraceOptions, ) -> Result<TraceGraph, InspectError>

Build a bounded response-local BFS DAG.

pub fn range_page( &self, area: &RangeArea, options: &RangePageOptions, ) -> Result<RangePage, InspectError>

Return one row-major owned page over the semantic finite extent.

impl<R: EvaluationContext> Engine<R>

pub fn begin_bulk_ingest(&mut self) -> BulkIngestBuilder<'_>

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn intern_formula_ast(&mut self, ast: &ASTNode) -> AstNodeId

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn stage_formula_ast( &mut self, grouper: &mut FormulaFamilyGrouper, row: u32, col: u32, ast: &ASTNode, formula_text: Option<Arc<str>>, ) -> FormulaIngestRecord

Stage one parsed formula at 1-based (row, col) of a bulk ingest batch, with load-time family grouping (Program 2): when the formula is exactly the formula above it (or to its left) in grouper’s sheet relocated to this cell, the record references that family’s template and the formula is never interned; otherwise it is interned as usual. Formulas of one sheet must be staged through one grouper, in any order (only adjacent cells are compared). With EvalConfig::formula_compression off every formula is interned.

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

pub fn note_staged_formula( &mut self, grouper: &mut FormulaFamilyGrouper, row: u32, col: u32, ast_id: AstNodeId, )

Record a formula interned without Self::stage_formula_ast (for example a parse-cache hit) as a family template candidate.

Panics

See Engine::is_poisoned for the permanent poison refusal contract.

Trait Implementations

impl<R> EvaluationContext for Engine<R>

where R: EvaluationContext,

fn resolve_range_view<'c>( &'c self, reference: &ReferenceType, current_sheet: &str, ) -> Result<RangeView<'c>, ExcelError>

New: resolve a reference into a RangeView (Phase 2 API)

fn named_binding_presence( &self, name: &str, current_sheet: &str, ) -> Option<bool>

Metadata-only binding presence in the current sheet scope. None means the resolver cannot attest presence or absence; values are never read.

fn operation_diagnostic_collector( &self, ) -> Option<&OperationDiagnosticCollector>

Optional request-event collector; does not certify retained-result coverage.

fn clock(&self) -> &dyn ClockProvider

Clock provider for volatile date/time builtins.

fn thread_pool(&self) -> Option<&Arc<ThreadPool>>

Get access to the shared thread pool for parallel evaluation Returns None if parallel evaluation is disabled or unavailable

fn cancellation_token(&self) -> Option<CancelToken>

Returns the optional shared cancellation handle for this evaluation.

fn chunk_hint(&self) -> Option<usize>

Optional chunk size hint for streaming visitors.

fn materialized_array_cells(&self) -> u64

Most cells a range or array value may have when it is materialised as a dense array (evaluation_budgets.scratch.materialized_array_cells); larger arrays evaluate to #NUM!. The default is 2^24 cells.

fn volatile_level(&self) -> VolatileLevel

Volatile granularity. Default Always for backwards compatibility.

fn workbook_seed(&self) -> u64

A stable workbook seed for RNG composition.

fn recalc_epoch(&self) -> u64

Recalc epoch that increments on each full recalc when appropriate.

fn workbook_sheet_count(&self) -> Option<usize>

Number of active sheets in the workbook, if known.

fn sheet_index_by_name(&self, sheet: &str) -> Option<usize>

Excel-style 1-based active-sheet index for a sheet name, if known.

fn current_sheet_index(&self, current_sheet: &str) -> Option<usize>

Excel-style 1-based active-sheet index for the current formula sheet, if known.

fn inspect_reference( &self, reference: &ReferenceType, current_sheet: &str, ) -> Result<Option<ReferenceInfo>, ExcelError>

Inspect reference metadata without materializing referenced values.

fn resolve_spill_reference( &self, anchor: &ReferenceType, current_sheet: &str, ) -> Result<ReferenceType, ExcelError>

Resolve a spill-range reference (A1#, ANCHORARRAY(A1)) to the anchor’s current committed spill rectangle.

fn has_formula_at_cell(&self, cell: CellRef) -> Result<bool, ExcelError>

Whether a concrete cell stores a formula, without requiring its text. Existing contexts can keep supplying formula text via the fallback.

fn formula_text_at_cell( &self, cell: CellRef, ) -> Result<Option<String>, ExcelError>

Retrieve formula text for a concrete cell, if that cell stores a formula.

fn used_rows_for_columns( &self, sheet: &str, start_col: u32, end_col: u32, ) -> Option<(u32, u32)>

Optional: Return the min/max used rows for a set of columns on a sheet. When None, the backend does not provide used-region hints.

fn used_cols_for_rows( &self, sheet: &str, start_row: u32, end_row: u32, ) -> Option<(u32, u32)>

Optional: Return the min/max used columns for a set of rows on a sheet. When None, the backend does not provide used-region hints.

fn sheet_bounds(&self, sheet: &str) -> Option<(u32, u32)>

Optional: Physical sheet bounds (max rows, max cols) if known.

fn data_snapshot_id(&self) -> u64

Monotonic identifier for the current data snapshot; increments on mutation.

fn backend_caps(&self) -> BackendCaps

Backend capability advertisement for IO/adapters.

fn build_lookup_index( &self, view: &RangeView<'_>, axis: LookupAxis, ) -> Option<Arc<LookupIndex>>

Optional: Build or fetch an exact-match lookup index over an Arrow-backed view. Implementations should return None if not supported or unsafe.

fn date_system(&self) -> DateSystem

Workbook date system selection (1900 vs 1904). Defaults to 1900 for compatibility.

fn resolve_cell_format( &self, sheet: Option<&str>, row: u32, col: u32, current_sheet: &str, ) -> Option<FormatId>

Resolve the effective number-format annotation of a scalar cell read.

fn format_class(&self, format: FormatId) -> Option<FormatClass>

Resolve an interned format id to its reported class.

fn record_cell_derived_format( &self, sheet: &str, row: u32, col: u32, format: Option<FormatId>, )

Record a formula cell’s derived scalar format during alternate scalar evaluation paths.

fn resolve_cell_reference_value( &self, sheet: Option<&str>, row: u32, col: u32, current_sheet: &str, ) -> Result<LiteralValue, ExcelError>

Resolve a single-cell reference as a scalar value.

fn build_criteria_mask( &self, view: &RangeView<'_>, col_in_view: usize, pred: &CriteriaPredicate, ) -> Option<Arc<BooleanArray>>

Optional: Build or fetch a cached boolean mask for a criterion over an Arrow-backed view. Implementations should return None if not supported.

fn build_row_visibility_mask( &self, view: &RangeView<'_>, mode: VisibilityMaskMode, ) -> Option<Arc<BooleanArray>>

Optional: Build row-visibility mask aligned to view rows. Returns None if not supported by the underlying context.

fn nested_subtotal_cells( &self, view: &RangeView<'_>, include_aggregate: bool, ) -> Option<Vec<(usize, usize, usize)>>

Optional: the cells of a sheet-backed view whose formulas call SUBTOTAL (and AGGREGATE when include_aggregate), as sorted, disjoint (column, first_row, last_row) offset intervals within the view (rows inclusive). SUBTOTAL and AGGREGATE skip these cells (Excel ignores nested subtotals). None when the context does not track formulas.

fn locale(&self) -> Locale

Locale provider: invariant by default

fn timezone(&self) -> &TimeZoneSpec

Timezone spec for date/time functions.

impl<R> FunctionProvider for Engine<R>

where R: EvaluationContext,

fn get_function(&self, prefix: &str, name: &str) -> Option<Arc<dyn Function>>

fn function_semantic_identity( &self, ns: &str, name: &str, arity: usize, ) -> Option<FunctionSemanticIdentity>

impl<R> NamedRangeResolver for Engine<R>

where R: EvaluationContext,

fn resolve_named_range_reference( &self, name: &str, ) -> Result<Vec<Vec<LiteralValue>>, ExcelError>

impl<R> 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 Range>, ExcelError>

impl<R> ReferenceResolver for Engine<R>

where R: EvaluationContext,

fn resolve_cell_reference( &self, sheet: Option<&str>, row: u32, col: u32, ) -> Result<LiteralValue, ExcelError>

impl<R> Resolver for Engine<R>

where R: EvaluationContext,

fn resolve_range_like( &self, r: &ReferenceType, ) -> Result<Box<dyn Range>, ExcelError>

impl<R> SourceResolver for Engine<R>

where R: EvaluationContext,

fn source_scalar_version(&self, name: &str) -> Option<u64>

fn resolve_source_scalar(&self, name: &str) -> Result<LiteralValue, ExcelError>

fn source_table_version(&self, name: &str) -> Option<u64>

fn resolve_source_table(&self, name: &str) -> Result<Box<dyn Table>, ExcelError>

impl<R> TableResolver for Engine<R>

where R: EvaluationContext,

fn resolve_table_reference( &self, tref: &TableReference, ) -> Result<Box<dyn Table>, ExcelError>