A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
refactor: scope down exposed state from the runner, add explicit context (#8247)
Myles Scolnick74561580dd23
diff --git a/marimo/_runtime/app/kernel_runner.py b/marimo/_runtime/app/kernel_runner.pyindex a258388e8a..4d8d9e920f 100644--- a/marimo/_runtime/app/kernel_runner.py+++ b/marimo/_runtime/app/kernel_runner.py@@ -16,7 +16,7 @@ from marimo._runtime.commands import ()from marimo._runtime.context.types import get_contextfrom marimo._runtime.patches import create_main_module-from marimo._runtime.runner import cell_runner+from marimo._runtime.runner import cell_runner, hook_contextfrom marimo._session.model import SessionModefrom marimo._types.ids import CellId_t@@ -86,13 +86,13 @@ class AppKernelRunner:def cache_output(cell: CellImpl,- runner: cell_runner.Runner,+ ctx: hook_context.PostExecutionHookContext,run_result: cell_runner.RunResult,) -> None:"""Update the app's cached outputs."""from marimo._plugins.stateless.flex import vstack- del runner+ del ctxif (run_result.output is Noneand run_result.accumulated_output is not Nonediff --git a/marimo/_runtime/runner/cell_runner.py b/marimo/_runtime/runner/cell_runner.pyindex ba7b211060..51ae67e5f2 100644--- a/marimo/_runtime/runner/cell_runner.py+++ b/marimo/_runtime/runner/cell_runner.py@@ -11,7 +11,7 @@ import tracebackfrom dataclasses import dataclassfrom pathlib import Pathfrom types import TracebackType-from typing import TYPE_CHECKING, Any, Callable, Optional, Union+from typing import TYPE_CHECKING, Any, Optionalfrom marimo._ast.variables import unmangle_localfrom marimo._config.config import ExecutionType, OnCellChangeType@@ -19,7 +19,6 @@ from marimo._dependencies.dependencies import DependencyManagerfrom marimo._dependencies.errors import ManyModulesNotFoundErrorfrom marimo._loggers import marimo_loggerfrom marimo._messaging.errors import (- Error,MarimoExceptionRaisedError,MarimoSQLError,MarimoStrictExecutionError,@@ -39,6 +38,10 @@ from marimo._runtime.executor import (get_executor,)from marimo._runtime.marimo_pdb import MarimoPdb+from marimo._runtime.runner.hook_context import (+ ExceptionOrError,+ ExecutionContextManager,+)from marimo._sql.error_utils import (create_sql_error_from_exception,is_sql_parse_error,@@ -50,19 +53,34 @@ LOGGER = marimo_logger()if TYPE_CHECKING:from collections.abc import Iterator- from marimo._runtime.context.types import ExecutionContextfrom marimo._runtime.runner.hooks import NotebookCellHooksfrom marimo._runtime.state import State+def _should_broadcast_data() -> bool:+ """Whether data (variables, datasets, etc.) should be broadcast.++ Returns True only in edit mode for non-embedded contexts.+ """+ from marimo._runtime.context.kernel_context import KernelRuntimeContext+ from marimo._runtime.context.types import get_context+ from marimo._session.model import SessionMode++ ctx = get_context()+ is_edit_mode = (+ isinstance(ctx, KernelRuntimeContext)+ and ctx.session_mode == SessionMode.EDIT+ )+ # We don't broadcast data in embedded contexts, since the variables+ # panel, etc. should only show the top-level graph's variables.+ return is_edit_mode and not ctx.is_embedded()++def cell_filename(cell_id: CellId_t) -> str:"""Filename to use when running cells through exec."""return f"<cell-{cell_id}>"-ExceptionOrError = Union[BaseException, Error]--@dataclassclass RunResult:# Raw output of cell: last expression@@ -114,10 +132,7 @@ class Runner:execution_mode: OnCellChangeType = "autorun",execution_type: ExecutionType = "relaxed",excluded_cells: set[CellId_t] | None = None,- execution_context: Callable[- [CellId_t], contextlib._GeneratorContextManager[ExecutionContext]- ]- | None = None,+ execution_context: ExecutionContextManager | None = None,):self.graph = graphself.debugger = debugger@@ -647,9 +662,34 @@ class Runner:return ref, blamed_cellasync def run_all(self) -> None:+ from marimo._runtime.runner.hook_context import (+ OnFinishHookContext,+ PostExecutionHookContext,+ PreExecutionHookContext,+ PreparationHookContext,+ )++ prep_ctx = PreparationHookContext(+ graph=self.graph,+ execution_mode=self.execution_mode,+ cells_to_run=self.cells_to_run,+ )LOGGER.debug("Running preparation hooks")for prep_hook in self._hooks.preparation_hooks:- prep_hook(self)+ prep_hook(prep_ctx)++ pre_exec_ctx = PreExecutionHookContext(+ graph=self.graph,+ execution_mode=self.execution_mode,+ )+ post_exec_ctx = PostExecutionHookContext(+ graph=self.graph,+ glbls=self.glbls,+ execution_context=self.execution_context,+ exceptions=self.exceptions,+ cells_cancelled=self.cells_cancelled,+ should_broadcast_data=_should_broadcast_data(),+ )while self.pending():cell_id = self.pop_cell()@@ -678,7 +718,7 @@ class Runner:LOGGER.debug("Running pre_execution hooks")for pre_hook in self._hooks.pre_execution_hooks:- pre_hook(cell, self)+ pre_hook(cell, pre_exec_ctx)LOGGER.debug("Running cell %s", cell_id)if self.execution_context is not None:try:@@ -689,7 +729,7 @@ class Runner:run_result.accumulated_output = exc_ctx.outputLOGGER.debug("Running post_execution hooks in context")for post_hook in self._hooks.post_execution_hooks:- post_hook(cell, self, run_result)+ post_hook(cell, post_exec_ctx, run_result)except KeyboardInterrupt:LOGGER.error("""@@ -701,8 +741,15 @@ class Runner:run_result = await self.run(cell_id)LOGGER.debug("Running post_execution hooks out of context")for post_hook in self._hooks.post_execution_hooks:- post_hook(cell, self, run_result)-+ post_hook(cell, post_exec_ctx, run_result)++ finish_ctx = OnFinishHookContext(+ graph=self.graph,+ cells_to_run=self.cells_to_run,+ interrupted=self.interrupted,+ cells_cancelled=self.cells_cancelled,+ exceptions=self.exceptions,+ )LOGGER.debug("Running on_finish hooks")for finish_hook in self._hooks.on_finish_hooks:- finish_hook(self)+ finish_hook(finish_ctx)diff --git a/marimo/_runtime/runner/hook_context.py b/marimo/_runtime/runner/hook_context.pynew file mode 100644index 0000000000..70512ec21c--- /dev/null+++ b/marimo/_runtime/runner/hook_context.py@@ -0,0 +1,63 @@+# Copyright 2026 Marimo. All rights reserved.+from __future__ import annotations++from dataclasses import dataclass+from typing import TYPE_CHECKING, Any, Callable, TypeAlias, Union++from marimo._config.config import OnCellChangeType+from marimo._messaging.errors import Error+from marimo._types.ids import CellId_t++if TYPE_CHECKING:+ from collections.abc import Mapping, Sequence+ from contextlib import AbstractContextManager++ from marimo._runtime.context.types import ExecutionContext+ from marimo._runtime.dataflow.graph import DirectedGraph++ExceptionOrError = Union[BaseException, Error]++ExecutionContextManager: TypeAlias = Callable[+ [CellId_t], "AbstractContextManager[ExecutionContext]"+]+++@dataclass(frozen=True)+class PreparationHookContext:+ graph: DirectedGraph+ execution_mode: OnCellChangeType+ cells_to_run: Sequence[CellId_t]+++@dataclass(frozen=True)+class PreExecutionHookContext:+ graph: DirectedGraph+ execution_mode: OnCellChangeType+++@dataclass(frozen=True)+class PostExecutionHookContext:+ graph: DirectedGraph+ glbls: dict[str, Any]+ execution_context: ExecutionContextManager | None+ # Dict, because errors get mutated (formatted) by hooks.+ exceptions: dict[CellId_t, ExceptionOrError]+ cells_cancelled: Mapping[CellId_t, set[CellId_t]]+ # Whether data (variables, datasets, etc.) should be broadcast+ # to the frontend. Computed once per run to avoid repeated checks.+ should_broadcast_data: bool = False++ def cancelled(self, cell_id: CellId_t) -> bool:+ """Check if a cell was cancelled."""+ return any(+ cell_id in cancelled for cancelled in self.cells_cancelled.values()+ )+++@dataclass(frozen=True)+class OnFinishHookContext:+ graph: DirectedGraph+ cells_to_run: Sequence[CellId_t]+ interrupted: bool+ cells_cancelled: Mapping[CellId_t, set[CellId_t]]+ exceptions: Mapping[CellId_t, ExceptionOrError]diff --git a/marimo/_runtime/runner/hooks.py b/marimo/_runtime/runner/hooks.pyindex b4dff2e414..5ac4e9abef 100644--- a/marimo/_runtime/runner/hooks.py+++ b/marimo/_runtime/runner/hooks.py@@ -10,6 +10,12 @@ if TYPE_CHECKING:from marimo._ast.cell import CellImplfrom marimo._runtime.runner import cell_runner+ from marimo._runtime.runner.hook_context import (+ OnFinishHookContext,+ PostExecutionHookContext,+ PreExecutionHookContext,+ PreparationHookContext,+ )__all__ = ["NotebookCellHooks",@@ -22,12 +28,12 @@ __all__ = []# Hook type aliases-PreparationHook = Callable[["cell_runner.Runner"], None]-PreExecutionHook = Callable[["CellImpl", "cell_runner.Runner"], None]+PreparationHook = Callable[["PreparationHookContext"], None]+PreExecutionHook = Callable[["CellImpl", "PreExecutionHookContext"], None]PostExecutionHook = Callable[- ["CellImpl", "cell_runner.Runner", "cell_runner.RunResult"], None+ ["CellImpl", "PostExecutionHookContext", "cell_runner.RunResult"], None]-OnFinishHook = Callable[["cell_runner.Runner"], None]+OnFinishHook = Callable[["OnFinishHookContext"], None]class Priority(IntEnum):@@ -48,6 +54,30 @@ class _HookEntry:@dataclass+class _HookList:+ """A list of hook entries with cached priority-sorted access."""++ _entries: list[_HookEntry] = field(default_factory=list)+ _sorted: list[Callable[..., None]] | None = field(+ default=None, init=False, repr=False+ )++ def add(self, hook: Callable[..., None], priority: Priority) -> None:+ self._entries.append(_HookEntry(hook, priority))+ self._sorted = None++ @property+ def sorted_hooks(self) -> Sequence[Callable[..., None]]:+ if self._sorted is None:+ self._sorted = [+ e.hook for e in sorted(self._entries, key=lambda e: e.priority)+ ]+ return self._sorted++ def copy(self) -> _HookList:+ return _HookList(self._entries.copy())++class NotebookCellHooks:"""Container for cell execution hooks with priority-based ordering.@@ -58,56 +88,53 @@ class NotebookCellHooks:4. on_finish_hooks: Run once after all cells complete"""- _preparation: list[_HookEntry] = field(default_factory=list)- _pre_execution: list[_HookEntry] = field(default_factory=list)- _post_execution: list[_HookEntry] = field(default_factory=list)- _on_finish: list[_HookEntry] = field(default_factory=list)+ def __init__(+ self,+ _preparation: _HookList | None = None,+ _pre_execution: _HookList | None = None,+ _post_execution: _HookList | None = None,+ _on_finish: _HookList | None = None,+ ) -> None:+ self._preparation = _preparation or _HookList()+ self._pre_execution = _pre_execution or _HookList()+ self._post_execution = _post_execution or _HookList()+ self._on_finish = _on_finish or _HookList()def add_preparation(self, hook: PreparationHook, priority: Priority = Priority.NORMAL) -> None:- self._preparation.append(_HookEntry(hook, priority))+ self._preparation.add(hook, priority)def add_pre_execution(self, hook: PreExecutionHook, priority: Priority = Priority.NORMAL) -> None:- self._pre_execution.append(_HookEntry(hook, priority))+ self._pre_execution.add(hook, priority)def add_post_execution(self, hook: PostExecutionHook, priority: Priority = Priority.NORMAL) -> None:- self._post_execution.append(_HookEntry(hook, priority))+ self._post_execution.add(hook, priority)def add_on_finish(self, hook: OnFinishHook, priority: Priority = Priority.NORMAL) -> None:- self._on_finish.append(_HookEntry(hook, priority))+ self._on_finish.add(hook, priority)@propertydef preparation_hooks(self) -> Sequence[PreparationHook]:- return [- e.hook for e in sorted(self._preparation, key=lambda e: e.priority)- ]+ return self._preparation.sorted_hooks@propertydef pre_execution_hooks(self) -> Sequence[PreExecutionHook]:- return [- e.hook- for e in sorted(self._pre_execution, key=lambda e: e.priority)- ]+ return self._pre_execution.sorted_hooks@propertydef post_execution_hooks(self) -> Sequence[PostExecutionHook]:- return [- e.hook- for e in sorted(self._post_execution, key=lambda e: e.priority)- ]+ return self._post_execution.sorted_hooks@propertydef on_finish_hooks(self) -> Sequence[OnFinishHook]:- return [- e.hook for e in sorted(self._on_finish, key=lambda e: e.priority)- ]+ return self._on_finish.sorted_hooksdef copy(self) -> NotebookCellHooks:return NotebookCellHooks(@@ -125,10 +152,7 @@ def create_default_hooks() -> NotebookCellHooks:Callers should add mode-specific hooks (e.g., render_toplevel_defs foredit mode, attempt_pytest for reactive tests) after calling this."""- from marimo._runtime.runner.hooks_on_finish import (- _send_cancellation_errors,- _send_interrupt_errors,- )+ from marimo._runtime.runner.hooks_on_finish import ON_FINISH_HOOKSfrom marimo._runtime.runner.hooks_post_execution import (POST_EXECUTION_HOOKS,)@@ -150,7 +174,7 @@ def create_default_hooks() -> NotebookCellHooks:for post_hook in POST_EXECUTION_HOOKS:hooks.add_post_execution(post_hook)- hooks.add_on_finish(_send_interrupt_errors)- hooks.add_on_finish(_send_cancellation_errors)+ for finish_hook in ON_FINISH_HOOKS:+ hooks.add_on_finish(finish_hook)return hooksdiff --git a/marimo/_runtime/runner/hooks_on_finish.py b/marimo/_runtime/runner/hooks_on_finish.pyindex 88e7d67d50..bca01c6f77 100644--- a/marimo/_runtime/runner/hooks_on_finish.py+++ b/marimo/_runtime/runner/hooks_on_finish.py@@ -1,8 +1,6 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations-from typing import Callable-from marimo import _loggersfrom marimo._messaging.errors import (Error,@@ -14,21 +12,20 @@ from marimo._messaging.errors import ()from marimo._messaging.notification_utils import CellNotificationUtilsfrom marimo._runtime.control_flow import MarimoStopError-from marimo._runtime.runner import cell_runner+from marimo._runtime.runner.hook_context import OnFinishHookContext+from marimo._runtime.runner.hooks import OnFinishHookfrom marimo._tracer import kernel_tracerLOGGER = _loggers.marimo_logger()-OnFinishHookType = Callable[[cell_runner.Runner], None]-@kernel_tracer.start_as_current_span("send_interrupt_errors")-def _send_interrupt_errors(runner: cell_runner.Runner) -> None:- if runner.cells_to_run:- assert runner.interrupted- for cid in runner.cells_to_run:+def _send_interrupt_errors(ctx: OnFinishHookContext) -> None:+ if ctx.cells_to_run:+ assert ctx.interrupted+ for cid in ctx.cells_to_run:# `cid` was not run- runner.graph.cells[cid].set_runtime_state("idle")+ ctx.graph.cells[cid].set_runtime_state("idle")CellNotificationUtils.broadcast_error(data=[MarimoInterruptionError()],# these cells are transitioning from queued to stopped@@ -40,17 +37,17 @@ def _send_interrupt_errors(runner: cell_runner.Runner) -> None:@kernel_tracer.start_as_current_span("send_cancellation_errors")-def _send_cancellation_errors(runner: cell_runner.Runner) -> None:- for raising_cell in runner.cells_cancelled:- for cid in runner.cells_cancelled[raising_cell]:+def _send_cancellation_errors(ctx: OnFinishHookContext) -> None:+ for raising_cell in ctx.cells_cancelled:+ for cid in ctx.cells_cancelled[raising_cell]:# `cid` was not run- cell = runner.graph.cells[cid]+ cell = ctx.graph.cells[cid]if cell.runtime_state != "idle":# the cell raising an exception will already be# idle, but its descendants won't be.cell.set_runtime_state("idle")- exception = runner.exceptions[raising_cell]+ exception = ctx.exceptions[raising_cell]data: Errorif isinstance(exception, MarimoStopError):data = MarimoAncestorStoppedError(@@ -89,7 +86,7 @@ def _send_cancellation_errors(runner: cell_runner.Runner) -> None:)-ON_FINISH_HOOKS: list[OnFinishHookType] = [+ON_FINISH_HOOKS: list[OnFinishHook] = [_send_interrupt_errors,_send_cancellation_errors,]diff --git a/marimo/_runtime/runner/hooks_post_execution.py b/marimo/_runtime/runner/hooks_post_execution.pyindex 617722f206..eb2ad7863a 100644--- a/marimo/_runtime/runner/hooks_post_execution.py+++ b/marimo/_runtime/runner/hooks_post_execution.py@@ -2,7 +2,6 @@from __future__ import annotationsimport sys-from typing import Callablefrom marimo import _loggersfrom marimo._ast.cell import CellImpl@@ -32,15 +31,15 @@ from marimo._messaging.tracebacks import write_tracebackfrom marimo._messaging.variables import create_variable_valuefrom marimo._output import formattingfrom marimo._plugins.ui._core.ui_element import UIElement-from marimo._runtime.context.kernel_context import KernelRuntimeContextfrom marimo._runtime.context.types import (get_context,get_global_context,)from marimo._runtime.control_flow import MarimoInterrupt, MarimoStopErrorfrom marimo._runtime.runner import cell_runner+from marimo._runtime.runner.hook_context import PostExecutionHookContext+from marimo._runtime.runner.hooks import PostExecutionHookfrom marimo._runtime.side_effect import SideEffect-from marimo._session.model import SessionModefrom marimo._sql.engines.duckdb import (INTERNAL_DUCKDB_ENGINE,DuckDBEngine,@@ -56,47 +55,42 @@ from marimo._utils.flatten import contains_instanceLOGGER = _loggers.marimo_logger()-PostExecutionHookType = Callable[- [CellImpl, cell_runner.Runner, cell_runner.RunResult], None-]--@kernel_tracer.start_as_current_span("set_imported_defs")def _set_imported_defs(cell: CellImpl,- runner: cell_runner.Runner,+ ctx: PostExecutionHookContext,run_result: cell_runner.RunResult,) -> None:del run_resultLOGGER.debug("Acquiring graph lock to update cell import workspace")- with runner.graph.lock:+ with ctx.graph.lock:LOGGER.debug("Acquired graph lock to update import workspace.")if cell.import_workspace.is_import_block:cell.import_workspace.imported_defs = set(- name for name in cell.defs if name in runner.glbls+ name for name in cell.defs if name in ctx.glbls)@kernel_tracer.start_as_current_span("set_status_idle")def _set_status_idle(cell: CellImpl,- runner: cell_runner.Runner,+ ctx: PostExecutionHookContext,run_result: cell_runner.RunResult,) -> None:del run_result- del runner+ del ctxcell.set_runtime_state(status="idle")@kernel_tracer.start_as_current_span("set_run_result_status")def _set_run_result_status(cell: CellImpl,- runner: cell_runner.Runner,+ ctx: PostExecutionHookContext,run_result: cell_runner.RunResult,) -> None:if isinstance(run_result.exception, MarimoInterruptionError):cell.set_run_result_status("interrupted")- elif runner.cancelled(cell.cell_id):+ elif ctx.cancelled(cell.cell_id):cell.set_run_result_status("cancelled")elif run_result.exception is not None:cell.set_run_result_status(@@ -114,33 +108,20 @@ def _set_run_result_status(cell.set_run_result_status("success")-def _should_broadcast_data() -> bool:- ctx = get_context()- is_edit_mode = (- isinstance(ctx, KernelRuntimeContext)- and ctx.session_mode == SessionMode.EDIT- )- # We don't broadcast data in embedded contexts, since the variables panel,- # etc. should only show the top-level graph's variables.- return is_edit_mode and not ctx.is_embedded()--@kernel_tracer.start_as_current_span("broadcast_variables")def _broadcast_variables(cell: CellImpl,- runner: cell_runner.Runner,+ ctx: PostExecutionHookContext,run_result: cell_runner.RunResult,) -> None:- if not _should_broadcast_data():+ if not ctx.should_broadcast_data:returndel run_resultvalues = [create_variable_value(name=variable,- value=(- runner.glbls[variable] if variable in runner.glbls else None- ),+ value=(ctx.glbls[variable] if variable in ctx.glbls else None),)for variable in cell.defs]@@ -151,18 +132,18 @@ def _broadcast_variables(@kernel_tracer.start_as_current_span("broadcast_datasets")def _broadcast_datasets(cell: CellImpl,- runner: cell_runner.Runner,+ ctx: PostExecutionHookContext,run_result: cell_runner.RunResult,) -> None:- if not _should_broadcast_data():+ if not ctx.should_broadcast_data:returndel run_resulttables = get_datasets_from_variables([- (VariableName(variable), runner.glbls[variable])+ (VariableName(variable), ctx.glbls[variable])for variable in cell.defs- if variable in runner.glbls+ if variable in ctx.glbls])if tables:@@ -173,18 +154,18 @@ def _broadcast_datasets(@kernel_tracer.start_as_current_span("broadcast_data_source_connection")def _broadcast_data_source_connection(cell: CellImpl,- runner: cell_runner.Runner,+ ctx: PostExecutionHookContext,run_result: cell_runner.RunResult,) -> None:- if not _should_broadcast_data():+ if not ctx.should_broadcast_data:returndel run_resultengines = get_engines_from_variables([- (VariableName(variable), runner.glbls[variable])+ (VariableName(variable), ctx.glbls[variable])for variable in cell.defs- if variable in runner.glbls+ if variable in ctx.glbls])@@ -205,14 +186,13 @@ def _broadcast_data_source_connection(@kernel_tracer.start_as_current_span("broadcast_duckdb_datasource")def _broadcast_duckdb_datasource(cell: CellImpl,- runner: cell_runner.Runner,+ ctx: PostExecutionHookContext,run_result: cell_runner.RunResult,) -> None:- if not _should_broadcast_data():+ if not ctx.should_broadcast_data:returndel run_result- del runnerif not DependencyManager.duckdb.has():return@@ -243,10 +223,10 @@ def _broadcast_duckdb_datasource(@kernel_tracer.start_as_current_span("store_reference_to_output")def _store_reference_to_output(cell: CellImpl,- runner: cell_runner.Runner,+ ctx: PostExecutionHookContext,run_result: cell_runner.RunResult,) -> None:- del runner+ del ctx# Stores a reference to the output if it contains a UIElement;# this is required to make RPCs work for unnamed UI elements.@@ -259,28 +239,28 @@ def _store_reference_to_output(def _store_state_reference(cell: CellImpl,- runner: cell_runner.Runner,+ ctx: PostExecutionHookContext,run_result: cell_runner.RunResult,) -> None:del run_result# Associate state variables with variable names- ctx = get_context()- ctx.state_registry.register_scope(runner.glbls, defs=cell.defs)+ runtime_ctx = get_context()+ runtime_ctx.state_registry.register_scope(ctx.glbls, defs=cell.defs)privates = set().union(- *[cell.temporaries for cell in ctx.graph.cells.values()]+ *[cell.temporaries for cell in runtime_ctx.graph.cells.values()])- ctx.state_registry.retain_active_states(- set(runner.graph.definitions.keys()) | privates+ runtime_ctx.state_registry.retain_active_states(+ set(ctx.graph.definitions.keys()) | privates)@kernel_tracer.start_as_current_span("issue_exception_side_effect")def _issue_exception_side_effect(_cell: CellImpl,- _runner: cell_runner.Runner,+ _ctx: PostExecutionHookContext,run_result: cell_runner.RunResult,) -> None:- ctx = get_context()+ runtime_ctx = get_context()if run_result.exception is not None:exception = run_result.exceptionkey = type(exception).__name__@@ -297,13 +277,13 @@ def _issue_exception_side_effect(# was raised.key += f":{traceback.tb_lasti}"# NB. This is on a cell level.- ctx.cell_lifecycle_registry.add(SideEffect(key))+ runtime_ctx.cell_lifecycle_registry.add(SideEffect(key))@kernel_tracer.start_as_current_span("broadcast_outputs")def _broadcast_outputs(cell: CellImpl,- runner: cell_runner.Runner,+ ctx: PostExecutionHookContext,run_result: cell_runner.RunResult,) -> None:# TODO: clean this logic up ...@@ -328,12 +308,12 @@ def _broadcast_outputs(formatted_output = formatting.try_format(run_result.output, include_opinionated=False)- # For ImportError and ModuleNotFoundError, store the exception in the runner- # so it can be reported by the missing_packages_hook.+ # For ImportError and ModuleNotFoundError, store the exception in the+ # context so it can be reported by the missing_packages_hook.if isinstance(formatted_output.exception, (ImportError, ModuleNotFoundError)):- runner.exceptions[cell.cell_id] = formatted_output.exception+ ctx.exceptions[cell.cell_id] = formatted_output.exceptionif formatted_output.traceback is not None:write_traceback(formatted_output.traceback)@@ -402,13 +382,13 @@ def _broadcast_outputs(@kernel_tracer.start_as_current_span("render_toplevel_defs")def render_toplevel_defs(cell: CellImpl,- runner: cell_runner.Runner,+ ctx: PostExecutionHookContext,run_result: cell_runner.RunResult,) -> None:del run_resultvariable = cell.toplevel_variableif variable is not None:- extractor = TopLevelExtraction.from_graph(runner.graph, cell=cell)+ extractor = TopLevelExtraction.from_graph(ctx.graph, cell=cell)serialization = list(iter(extractor))[-1]CellNotificationUtils.broadcast_serialization(serialization=serialization,@@ -419,7 +399,7 @@ def render_toplevel_defs(@kernel_tracer.start_as_current_span("run_pytest")def attempt_pytest(cell: CellImpl,- runner: cell_runner.Runner,+ ctx: PostExecutionHookContext,run_result: cell_runner.RunResult,) -> None:del run_result@@ -427,9 +407,9 @@ def attempt_pytest(try:import marimo._runtime.pytest as marimo_pytest- if runner.execution_context is not None:- with runner.execution_context(cell.cell_id):- result = marimo_pytest.run_pytest(cell.defs, runner.glbls)+ if ctx.execution_context is not None:+ with ctx.execution_context(cell.cell_id):+ result = marimo_pytest.run_pytest(cell.defs, ctx.glbls)if result.output:sys.stdout.write(result.output)except ImportError:@@ -439,17 +419,17 @@ def attempt_pytest(@kernel_tracer.start_as_current_span("reset_matplotlib_context")def _reset_matplotlib_context(cell: CellImpl,- runner: cell_runner.Runner,+ ctx: PostExecutionHookContext,run_result: cell_runner.RunResult,) -> None:del celldel run_resultif get_global_context().mpl_installed:# ensures that every cell gets a fresh axis.- exec("__marimo__._output.mpl.close_figures()", runner.glbls)+ exec("__marimo__._output.mpl.close_figures()", ctx.glbls)-POST_EXECUTION_HOOKS: list[PostExecutionHookType] = [+POST_EXECUTION_HOOKS: list[PostExecutionHook] = [_set_imported_defs,_set_run_result_status,_store_reference_to_output,diff --git a/marimo/_runtime/runner/hooks_pre_execution.py b/marimo/_runtime/runner/hooks_pre_execution.pyindex 97f92babe7..8fa3c251b7 100644--- a/marimo/_runtime/runner/hooks_pre_execution.py+++ b/marimo/_runtime/runner/hooks_pre_execution.py@@ -1,23 +1,20 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations-from typing import Callable-from marimo._ast.cell import CellImpl-from marimo._runtime.runner import cell_runner+from marimo._runtime.runner.hook_context import PreExecutionHookContext+from marimo._runtime.runner.hooks import PreExecutionHookfrom marimo._tracer import kernel_tracer-PreExecutionHookType = Callable[[CellImpl, cell_runner.Runner], None]-@kernel_tracer.start_as_current_span("set_staleness")def _set_staleness(cell: CellImpl,- runner: cell_runner.Runner,+ ctx: PreExecutionHookContext,) -> None:- graph = runner.graph+ graph = ctx.graph- if runner.execution_mode == "lazy" and not graph.is_any_ancestor_stale(+ if ctx.execution_mode == "lazy" and not graph.is_any_ancestor_stale(cell.cell_id):# TODO: The above check could be omitted as an optimization as long as@@ -30,13 +27,13 @@ def _set_staleness(@kernel_tracer.start_as_current_span("set_status_to_running")def _set_status_to_running(cell: CellImpl,- runner: cell_runner.Runner,+ ctx: PreExecutionHookContext,) -> None:- del runner+ del ctxcell.set_runtime_state("running")-PRE_EXECUTION_HOOKS: list[PreExecutionHookType] = [+PRE_EXECUTION_HOOKS: list[PreExecutionHook] = [_set_staleness,_set_status_to_running,]diff --git a/marimo/_runtime/runner/hooks_preparation.py b/marimo/_runtime/runner/hooks_preparation.pyindex 0087cff524..7f1617f12f 100644--- a/marimo/_runtime/runner/hooks_preparation.py+++ b/marimo/_runtime/runner/hooks_preparation.py@@ -1,29 +1,26 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations-from typing import Callable-from marimo._runtime import dataflow-from marimo._runtime.runner import cell_runner+from marimo._runtime.runner.hook_context import PreparationHookContext+from marimo._runtime.runner.hooks import PreparationHookfrom marimo._tracer import kernel_tracer-PreparationHookType = Callable[[cell_runner.Runner], None]-@kernel_tracer.start_as_current_span("update_stale_statuses")-def _update_stale_statuses(runner: cell_runner.Runner) -> None:- graph = runner.graph+def _update_stale_statuses(ctx: PreparationHookContext) -> None:+ graph = ctx.graph- if runner.execution_mode == "lazy":+ if ctx.execution_mode == "lazy":for cid in dataflow.transitive_closure(graph,- set(runner.cells_to_run),+ set(ctx.cells_to_run),inclusive=False,relatives=dataflow.get_import_block_relatives(graph),):graph.cells[cid].set_stale(stale=True)- for cid in runner.cells_to_run:+ for cid in ctx.cells_to_run:if graph.is_disabled(cid):graph.cells[cid].set_stale(stale=True)else:@@ -32,4 +29,4 @@ def _update_stale_statuses(runner: cell_runner.Runner) -> None:graph.cells[cid].set_stale(stale=False)-PREPARATION_HOOKS: list[PreparationHookType] = [_update_stale_statuses]+PREPARATION_HOOKS: list[PreparationHook] = [_update_stale_statuses]diff --git a/marimo/_runtime/runtime.py b/marimo/_runtime/runtime.pyindex 181bb94be4..ffae2b047b 100644--- a/marimo/_runtime/runtime.py+++ b/marimo/_runtime/runtime.py@@ -163,7 +163,7 @@ from marimo._runtime.params import CLIArgs, QueryParamsfrom marimo._runtime.redirect_streams import redirect_streamsfrom marimo._runtime.reload.autoreload import ModuleReloaderfrom marimo._runtime.reload.module_watcher import ModuleWatcher-from marimo._runtime.runner import cell_runner+from marimo._runtime.runner import cell_runner, hook_contextfrom marimo._runtime.runner.hooks import (NotebookCellHooks,Priority,@@ -1369,9 +1369,9 @@ class Kernel:def _propagate_kernel_errors(self,- runner: cell_runner.Runner,+ ctx: hook_context.OnFinishHookContext,) -> None:- for cell_id, error in runner.exceptions.items():+ for cell_id, error in ctx.exceptions.items():if isinstance(error, MarimoStrictExecutionError):self.errors[cell_id] = (error,)@@ -1388,17 +1388,17 @@ class Kernel:# descendants (cancelled == cells that raise exceptions), whereas# eager kernels do (since we clear all state ahead of time, and# have the closure of the roots in cells to run)- def invalidate_state(runner: cell_runner.Runner) -> None:- for cid in runner.cells_to_run:+ def invalidate_state(ctx: hook_context.PreparationHookContext) -> None:+ for cid in ctx.cells_to_run:self._invalidate_cell_state(cid)def note_time_of_interruption(cell_impl: CellImpl,- runner: cell_runner.Runner,+ ctx: hook_context.PostExecutionHookContext,run_result: cell_runner.RunResult,) -> None:del cell_impl- del runner+ del ctxif isinstance(run_result.exception, MarimoInterrupt):self.last_interrupt_timestamp = time.time()@@ -2785,10 +2785,12 @@ class PackagesCallbacks:),)- def missing_packages_hook(self, runner: cell_runner.Runner) -> None:+ def missing_packages_hook(+ self, ctx: hook_context.OnFinishHookContext+ ) -> None:module_not_found_errors = [e- for e in runner.exceptions.values()+ for e in ctx.exceptions.values()if isinstance(e, (ImportError, ManyModulesNotFoundError))]diff --git a/marimo/_runtime/state.py b/marimo/_runtime/state.pyindex f77a968d1c..861afd68db 100644--- a/marimo/_runtime/state.py+++ b/marimo/_runtime/state.py@@ -4,7 +4,7 @@ from __future__ import annotationsimport typesimport weakreffrom dataclasses import dataclass-from typing import Any, Callable, Generic, Optional, TypeVar+from typing import TYPE_CHECKING, Any, Callable, Generic, Optional, TypeVarfrom uuid import uuid4from marimo._output.rich_help import mddoc@@ -13,6 +13,9 @@ from marimo._runtime.context import ContextNotInitializedError, get_contextT = TypeVar("T")Id = int+if TYPE_CHECKING:+ from collections.abc import Mapping+@dataclassclass StateItem(Generic[T]):@@ -72,7 +75,7 @@ class StateRegistry:finalizer.atexit = Falsedef register_scope(- self, glbls: dict[str, Any], defs: Optional[set[str]] = None+ self, glbls: Mapping[str, Any], defs: Optional[set[str]] = None) -> None:"""Finds instances of state and scope, and adds them to registry if notalready present."""