Skip to content

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.

feat(runtime): cell-level cached execution lifecycle (#9895)

Dylan Madisettif7e14225280f
diff --git a/marimo/_runtime/exceptions.py b/marimo/_runtime/exceptions.py
index 833b9e0cd2..11c8c6af6e 100644
--- a/marimo/_runtime/exceptions.py
+++ b/marimo/_runtime/exceptions.py
@@ -27,8 +27,11 @@ class MarimoMissingRefError(BaseException):
self.name_error = name_error
-class MarimoCancelCellError(BaseException):
- """Soft-cancel signal raised by a lifecycle.
+class MarimoRescheduleError(BaseException):
+ """Reschedule signal raised by a lifecycle.
+
+ Cancels the current cell's execution and requeues the cells in
+ `cells_to_rerun` so the cell can run again once they have.
Subclasses BaseException (not Exception) so user-code `except Exception`
blocks don't swallow the control-flow signal.
@@ -45,7 +48,7 @@ class MarimoCancelCellError(BaseException):
self.cells_to_rerun = cells_to_rerun or set()
-class MarimoUnhashableCacheError(MarimoCancelCellError):
+class MarimoUnhashableCacheError(MarimoRescheduleError):
"""Raised when cell-level caching encounters a value that cannot be
hashed/serialized for cache restoration."""
diff --git a/marimo/_runtime/executor/lifecycles/cached.py b/marimo/_runtime/executor/lifecycles/cached.py
new file mode 100644
index 0000000000..114da078e9
--- /dev/null
+++ b/marimo/_runtime/executor/lifecycles/cached.py
@@ -0,0 +1,320 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""CachedLifecycle for cell-level caching.
+
+Cached Execution is a lifecycle that attempts to skip and stub cell execution
+if results have already been computed.
+
+In the "setup" of a cached execution, a cell hash and look up is attempted.
+The "teardown" of a cached execution records timing and results to the cache if
+the cell ran live.
+There are 4 potential outcomes from attempted restoration:
+
+1. Cache hit
+ In this case, cache can be successfully loaded from disk, allowing the body
+ to skip execution. Resortation populate defs into globals and returns the
+ associated value.
+2. Stale cache
+ In this case, a "UnhashableStub" requirement or cache mechanism failure
+ indicates that the cell must rerun live, and may have ancestors that require
+ a re-run as well. In this case, the cell raises a MarimoRescheduleError with
+ the set of cells to requeue.
+3. Cache miss
+ Cache was not found, ancestors do not require re-run, so the cell can run as
+ normal with its results saved to cache on teardown.
+4. Non-cache related exception
+ During a "Cache Miss" execution, the cell body may raise an exception. In
+ this case, the exception is propagated to the caller, and the cache is not
+ saved.
+
+At the moment, a special carve out for UI elements is made, since UI hydration
+requires consistent ID lookup.
+
+The full flow from mermaid ascii demonstrated below:
+
++---------------+
+| cell enters |
+| lifecycle |
++---------------+
+ |
+ v
++---------------+
+| hash cell |
++---------------+
+ |
+ v
++---------------+
+| cache hit? |----miss----+
++---------------+ |
+ | |
+ hit |
+ v v
++---------------+ +----------------+
+| restore defs | | refs have |
+| to globals |-fail->| stub? |------+
++---------------+ +----------------+ |
+ | ^ |
+ ok +------->stub |
+ v | v v
++---------------+ | +--------------+ +-------------+
+| defs are | | | are cells | | body runs |
+| live UI? |-+ | stale? |-no->| |
++---------------+ +--------------+ +-------------+
+ | | |
+ no yes |
+ v v v
++---------------+ +----------------+ +-------------+
+| skip body, | | | | |
+| record key | | raise Cancel | | raised? |---yes-----+
++---------------+ +----------------+ +-------------+ |
+ | | | |
+ | | no |
+ v | v v
++---------------+ +--------------+ +-------------+ +--------------+
+| teardown: | | teardown: | | teardown: | | teardown: |
+| no-op | | no-op | | save defs + | | drop attempt |
+| | | | | return | | |
++---------------+ +--------------+ +-------------+ +--------------+
+ | | | |
+ v v v v
++---------------+ +----------------+ +-------------+ +--------------+
+| 1. return | | 2. scheduler | | 3. return | | 4. propagate |
+| cached val | | handles | | real val | | exception |
+| | | requeues | | | | |
++---------------+ +----------------+ +-------------+ +--------------+
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, cast
+
+from marimo import _loggers
+from marimo._runtime.exceptions import MarimoRescheduleError
+from marimo._runtime.executor.lifecycles import Skip
+from marimo._runtime.runner.result import RunResult
+from marimo._save.cache import Cache, CacheException
+from marimo._save.hash import cache_attempt_from_hash
+from marimo._save.loaders import (
+ PERSISTENT_LOADERS,
+ BasePersistenceLoader,
+ LoaderKey,
+ resolve_loader,
+)
+
+if TYPE_CHECKING:
+ from marimo._ast.cell import CellImpl
+ from marimo._runtime.dataflow import DirectedGraph
+ from marimo._types.globals import MutableGlobals
+ from marimo._types.ids import CellId_t
+
+LOGGER = _loggers.marimo_logger()
+
+
+def _is_unhashable_stub(value: object) -> bool:
+ return getattr(type(value), "__marimo_unhashable__", False) is True
+
+
+class CachedLifecycle:
+ """Skip cell exec on cache hit, populates definitions on cache hit."""
+
+ name = "cached"
+
+ def __init__(
+ self,
+ graph: DirectedGraph,
+ pin_modules: bool = True,
+ loader: LoaderKey = "lazy",
+ ) -> None:
+ self._graph = graph
+ self._pin_modules = pin_modules
+ # BasePersistenceLoader is the base class for all persistent loaders.
+ self._loader = cast(
+ BasePersistenceLoader,
+ resolve_loader(PERSISTENT_LOADERS[loader])(name="cell_cache"),
+ )
+ # Per-cell state — populated in setup, consumed in teardown.
+ self._attempts: dict[CellId_t, Cache] = {}
+ self._exec_starts: dict[CellId_t, float] = {}
+ # Per-cell keylookup path, recorded on hit/save.
+ self._restored_keys: dict[CellId_t, str] = {}
+ # Cells that failed to rehydrate on pre-flight, so we don't requeue
+ # them again and again.
+ self._invalidated: set[CellId_t] = set()
+
+ def setup(self, cell: CellImpl, glbls: MutableGlobals) -> Skip | None:
+ cell_id = cell.cell_id
+
+ attempt = cache_attempt_from_hash(
+ cell.mod,
+ self._graph,
+ cell_id,
+ glbls,
+ loader=self._loader,
+ pin_modules=self._pin_modules,
+ )
+ self._attempts[cell_id] = attempt
+
+ restored = False
+ if attempt.hit:
+ try:
+ attempt.restore(glbls)
+ restored = True
+ except (Exception, CacheException) as e:
+ LOGGER.warning("Cache restore failed for %s: %s", cell_id, e)
+ self._attempts.pop(cell_id, None)
+ # Fall through to miss-path execution.
+
+ if restored:
+ # Defer loading if restored and not a UI element.
+ # TODO(dmadisetti): Attempt to restore UI elements as well.
+ # Currently the UIElement class has UIDs that are session-specific.
+ if not self._restored_ui_defs(attempt, glbls):
+ self._restored_keys[cell_id] = str(
+ self._loader.build_path(attempt.key)
+ )
+ return Skip(
+ result=RunResult(
+ output=attempt.meta.get("return"), exception=None
+ )
+ )
+
+ LOGGER.debug(
+ "Cache hit for %s defines UI elements; running "
+ "live to register them with this session",
+ cell_id,
+ )
+ self._attempts.pop(cell_id, None)
+ # Fall through to miss-path execution.
+
+ # Raises MarimoRescheduleError if any ref requires rehydration.
+ self._preflight_refs(cell, glbls)
+
+ self._exec_starts[cell_id] = time.time()
+ return None
+
+ def teardown(
+ self,
+ cell: CellImpl,
+ glbls: MutableGlobals,
+ run_result: RunResult,
+ ) -> None:
+ cell_id = cell.cell_id
+ # A cell that does have an exception, nor a stub defined in its globals,
+ # is considered a successful run and can be totally cached.
+ # As a result, it is also removed from the "invalid" set, which can
+ # potentially be triggered in a re-run of its ancestors.
+ if run_result.exception is None and not self._defines_stub(
+ cell, glbls
+ ):
+ self._invalidated.discard(cell_id)
+ attempt = self._attempts.pop(cell_id, None)
+ exec_start = self._exec_starts.pop(cell_id, None)
+
+ # Teardown is a no-op a exception or cache hit occurs.
+ if attempt is None or run_result.exception is not None:
+ return
+ if attempt.hit:
+ return
+
+ runtime = (time.time() - exec_start) if exec_start else 0.0
+ try:
+ attempt.update(
+ {**glbls},
+ meta={
+ "return": run_result.output,
+ "runtime": runtime,
+ },
+ preserve_pointers=False,
+ )
+ saved = self._loader.save_cache(attempt)
+ if saved:
+ self._restored_keys[cell_id] = str(
+ self._loader.build_path(attempt.key)
+ )
+ except BaseException as e:
+ # Best-effort: save failures (incl. CacheException, which
+ # extends BaseException) must never break the teardown chain.
+ LOGGER.warning("Cache save failed for %s: %s", cell_id, e)
+
+ @staticmethod
+ def _defines_stub(cell: CellImpl, glbls: MutableGlobals) -> bool:
+ """True if any name the cell defines is still an UnhashableStub."""
+ return any(_is_unhashable_stub(glbls.get(name)) for name in cell.defs)
+
+ @staticmethod
+ def _restored_ui_defs(attempt: Cache, glbls: MutableGlobals) -> bool:
+ """True if any def restored from the cache is a live UIElement."""
+ from marimo._plugins.ui._core.ui_element import UIElement
+
+ return any(
+ isinstance(glbls.get(name), UIElement) for name in attempt.defs
+ )
+
+ def _preflight_refs(self, cell: CellImpl, glbls: MutableGlobals) -> None:
+ """Detect UnhashableStub residues in refs and requeue producers.
+
+ Walks `cell.refs` and checks each name in `glbls` for an
+ `UnhashableStub` instance. If any are found, invalidates each producer's
+ recorded manifest, drops this cell's attempt so teardown will no-op, and
+ raises `MarimoRescheduleError` with `cells_to_rerun` populated.
+ """
+ cell_id = cell.cell_id
+ stub_vars: list[str] = []
+ for ref in cell.refs:
+ value = glbls.get(ref) if ref in glbls else None
+ if _is_unhashable_stub(value):
+ stub_vars.append(ref)
+
+ if not stub_vars:
+ return
+
+ producers: set[CellId_t] = set()
+ for var_name in stub_vars:
+ try:
+ producers.update(self._graph.get_defining_cells(var_name))
+ except KeyError:
+ pass
+ producers.discard(cell_id)
+
+ # Get the cells we have not previously marked as invalidated.
+ fresh = {p for p in producers if p not in self._invalidated}
+ if not fresh:
+ LOGGER.warning(
+ "Unsatisfiable reschedule for %s: stub refs %s persist after "
+ "rerun; not requeuing",
+ cell_id,
+ stub_vars,
+ )
+ return
+
+ for producer_id in fresh:
+ self._invalidate(producer_id)
+
+ # Drop our own attempt — body is being skipped this turn, so
+ # teardown must not restore defs from the partial scope.
+ self._attempts.pop(cell_id, None)
+ self._exec_starts.pop(cell_id, None)
+
+ LOGGER.info(
+ "Rescheduling for %s: stub refs %s; Cell Ids %s",
+ cell_id,
+ stub_vars,
+ fresh,
+ )
+ raise MarimoRescheduleError(cells_to_rerun={cell_id} | fresh)
+
+ def _invalidate(self, cell_id: CellId_t) -> None:
+ """Invalidate `cell_id`'s manifest so it re-runs live.
+
+ Cells marked invalidated are skipped in future pre-flight check
+ to force reruns and prevent recursive deadlocks.
+ """
+ key = self._restored_keys.pop(cell_id, None)
+ self._invalidated.add(cell_id)
+ if key is None:
+ return
+ try:
+ self._loader.store.clear(key)
+ self._loader.mark_stale(key)
+ except Exception as e:
+ LOGGER.warning("Manifest invalidate failed for %s: %s", key, e)
diff --git a/marimo/_runtime/runner/cell_runner.py b/marimo/_runtime/runner/cell_runner.py
index 129669a1e5..b735d4c1f9 100644
--- a/marimo/_runtime/runner/cell_runner.py
+++ b/marimo/_runtime/runner/cell_runner.py
@@ -24,6 +24,7 @@ from marimo._runtime.context.types import safe_get_context
from marimo._runtime.control_flow import MarimoInterrupt, MarimoStopError
from marimo._runtime.exceptions import (
MarimoMissingRefError,
+ MarimoRescheduleError,
MarimoRuntimeException,
unwrap_user_exception,
)
@@ -157,6 +158,23 @@ class Runner:
lifecycles: list[ExecutionLifecycle] = []
if execution_type == "strict":
lifecycles.append(StrictLifecycle(self.graph))
+ if user_config is not None and user_config.get("runtime", {}).get(
+ "cache_cells", False
+ ):
+ from marimo._runtime.executor.lifecycles.cached import (
+ CachedLifecycle,
+ )
+
+ lifecycles.append(
+ CachedLifecycle(
+ self.graph,
+ # Default pin_modules to True for a stronger backwards compatibility
+ # guarantee.
+ pin_modules=bool(
+ user_config.get("runtime", {}).get("pin_modules", True)
+ ),
+ )
+ )
self._evaluator = Evaluator(
executor=resolve_executor(), lifecycles=lifecycles
)
@@ -428,28 +446,38 @@ class Runner:
# The Evaluator captures all body/lifecycle exceptions into the
# returned RunResult; cell_id-specific classification + side
# effects are applied below in `_finalize_run_result`.
+ unexpected_failure: BaseException | None = None
try:
raw_result = await self.evaluate_interruptible(cell)
+ except BaseException as exc:
+ unexpected_failure = exc
+ raw_result = RunResult(output=None, exception=None)
+
+ if isinstance(raw_result.exception, MarimoRescheduleError):
+ raise raw_result.exception
+
+ try:
run_result = self._finalize_run_result(raw_result, cell_id)
- except BaseException:
- # Defensive: an unexpected escape from the Evaluator or a bug
- # in `_finalize_run_result` would otherwise tear down the
- # runner loop. Degrade gracefully with an empty RunResult.
+ except BaseException as exc:
+ unexpected_failure = exc
+ run_result = RunResult(output=None, exception=None)
+
+ if unexpected_failure is not None:
LOGGER.error(
"""marimo encountered an internal error.
+ marimo finished executing a cell, but did not produce
+ a run result.
- marimo finished executing a cell, but did not produce
- a run result.
+ Please copy this message and paste it in a GitHub issue:
- Please copy this message and paste it in a GitHub issue:
-
- https://github.com/marimo-team/marimo/issues
+ https://github.com/marimo-team/marimo/issues
- Any additional context of what caused this error, such
- as sample code to reproduce, will help us debug.
- """
+ Any additional context of what caused this error, such
+ as sample code to reproduce, will help us debug.
+ %s
+ """,
+ str(unexpected_failure),
)
- run_result = RunResult(output=None, exception=None)
# Mark as interrupted if the cell raised a MarimoInterrupt
# Set here since failed async can also trigger an Interrupt.
@@ -807,4 +835,17 @@ class Runner:
cell.set_run_result_status("cancelled")
cell.set_runtime_state("idle")
continue
- await self._run_one(cell_id, pre_exec_ctx, post_exec_ctx)
+ try:
+ await self._run_one(cell_id, pre_exec_ctx, post_exec_ctx)
+ except MarimoRescheduleError as e:
+ LOGGER.debug(
+ "Reschedule for %s; requeuing %s",
+ cell_id,
+ e.cells_to_rerun,
+ )
+ # Reschedule control signal from a lifecycle.
+ # Move the cell back to queued state, and reschedule for
+ # rerun after the relevant cells have been run.
+ for rerun_id in e.cells_to_rerun:
+ self.graph.cells[rerun_id].set_runtime_state("queued")
+ self._scheduler.requeue_for_rerun(e.cells_to_rerun)
diff --git a/marimo/_runtime/runner/hook_context.py b/marimo/_runtime/runner/hook_context.py
index 9d51c5da88..0b7d19be59 100644
--- a/marimo/_runtime/runner/hook_context.py
+++ b/marimo/_runtime/runner/hook_context.py
@@ -42,6 +42,26 @@ class CancelledCells:
self._by_raising_cell[raising_cell] = descendants
self._all.update(descendants)
+ def discard(self, cell_id: CellId_t) -> None:
+ """Un-cancel a cell
+
+ That is remove it from the cancelled set and any descendant sets."""
+ self._by_raising_cell.pop(cell_id, None)
+ for raising_cell in list(self._by_raising_cell):
+ descendants = self._by_raising_cell[raising_cell]
+ descendants.discard(cell_id)
+ # A raiser with no cancelled descendants left is no longer a
+ # cancellation record.
+ if not descendants:
+ del self._by_raising_cell[raising_cell]
+ # Rebuild the flat view from what remains; otherwise popping a raiser
+ # above strands its descendants in _all, breaking the union invariant.
+ self._all = (
+ set().union(*self._by_raising_cell.values())
+ if self._by_raising_cell
+ else set()
+ )
+
def __contains__(self, cell_id: object) -> bool:
"""O(1) check if a cell has been cancelled."""
return cell_id in self._all
diff --git a/marimo/_runtime/runner/scheduler.py b/marimo/_runtime/runner/scheduler.py
index 053e505dcb..d882c369b4 100644
--- a/marimo/_runtime/runner/scheduler.py
+++ b/marimo/_runtime/runner/scheduler.py
@@ -59,6 +59,7 @@ class Scheduler(Protocol):
self, cell_ids: Iterable[CellId_t] | None = ...
) -> Iterator[Iterable[CellId_t]]: ...
def requeue(self, cell_ids: Iterable[CellId_t]) -> None: ...
+ def requeue_for_rerun(self, cells: set[CellId_t]) -> None: ...
def start_task(
self,
@@ -117,6 +118,23 @@ class SequentialScheduler:
self._cells_to_run.clear()
self._cells_to_run.extend(cell_ids)
+ def requeue_for_rerun(self, cells: set[CellId_t]) -> None:
+ """Reschedules by putting `cells` back at the head of the queue.
+
+ Un-cancels each cell and prepends them in **topological order**
+ so the next `batch()` yields producers first.
+ """
+ ordered = dataflow.topological_sort(self._graph, cells)
+ # appendleft reverses, so iterate back-to-front to land the
+ # topologically-first cell at the head of the queue.
+ for cid in reversed(ordered):
+ self._cancelled.discard(cid)
+ # remove() is a no-op-safe O(n) scan. This also prevents the cell
+ # appearing twice in the queue.
+ if cid in self._cells_to_run:
+ self._cells_to_run.remove(cid)
+ self._cells_to_run.appendleft(cid)
+
def cancel(self, cell_id: CellId_t) -> None:
"""Mark a cell and its descendants as cancelled."""
descendants = {
diff --git a/marimo/_save/cache.py b/marimo/_save/cache.py
index 91444a2110..3289b5ba8e 100644
--- a/marimo/_save/cache.py
+++ b/marimo/_save/cache.py
@@ -80,6 +80,8 @@ class CacheState:
# Lazy-store session state; see `loaders/lazy.py:_cache_state`.
active_lazy_loaders: dict[str, LazyLoader] = field(default_factory=dict)
poisoned_keys: set[str] = field(default_factory=set)
+ # Manifest keys invalidated this session for re-execution.
+ stale_keys: set[str] = field(default_factory=set)
wasm_dict_store: Store | None = None
def is_memoizable(self, value: Any) -> bool:
@@ -301,6 +303,9 @@ class Cache:
# CustomStub is a placeholder for a custom type, which cannot be
# restored directly.
result = value.load(scope)
+ # Account for nested stubs via recursive restore.
+ if isinstance(result, CustomStub) and result is not value:
+ result = self._restore_from_stub_if_needed(result, scope, memo)
else:
result = value
diff --git a/marimo/_save/hash.py b/marimo/_save/hash.py
index 68cfd625ff..8dd54a8a13 100644
--- a/marimo/_save/hash.py
+++ b/marimo/_save/hash.py
@@ -705,12 +705,17 @@ class BlockHasher:
version = ""
module = None
if self.pin_modules:
- # `.get`: a cached module def restored as a missing-
- # module placeholder is in scope but not sys.modules.
- module = sys.modules.get(imports[ref].module)
+ # Fall back to the in-scope value (which may be a module
+ # stub) so its replayed `__version__` reproduces the pinned
+ # hash.
+ module = sys.modules.get(imports[ref].module) or scope.get(
+ local_ref
+ )
version = getattr(module, "__version__", "") or ""
if not version:
- module = sys.modules.get(imports[ref].namespace)
+ module = sys.modules.get(
+ imports[ref].namespace
+ ) or scope.get(imports[ref].namespace)
version = getattr(module, "__version__", "") or ""
content_serialization[ref] = type_sign(
diff --git a/marimo/_save/loaders/lazy.py b/marimo/_save/loaders/lazy.py
index aad98fc758..467a8d3af3 100644
--- a/marimo/_save/loaders/lazy.py
+++ b/marimo/_save/loaders/lazy.py
@@ -31,7 +31,6 @@ from marimo._save.stubs import (
ModuleStub,
)
from marimo._save.stubs.lazy_stub import (
- _LAZY_STUB_CACHE,
BLOB_DESERIALIZERS,
BLOB_SERIALIZERS,
LAZY_STUB_LOOKUP,
@@ -55,18 +54,10 @@ class _BlobStatus(Enum):
def maybe_update_lazy_stub(value: Any) -> str:
- """Return the loader strategy string for *value*, caching the result.
-
- Walks the MRO of `type(value)` against `LAZY_STUB_LOOKUP` (a
- fq-class-name -> loader-string registry). Falls back to `"pickle"`
- when no match is found.
- """
value_type = type(value)
- if value_type in _LAZY_STUB_CACHE:
- return _LAZY_STUB_CACHE[value_type]
+ # MRO not that expensive, type hashable for functools lookup.
result = mro_lookup(value_type, LAZY_STUB_LOOKUP)
loader = result[1] if result else "pickle"
- _LAZY_STUB_CACHE[value_type] = loader
return loader
@@ -134,7 +125,10 @@ def to_item(
if isinstance(value, ClassStub):
return Item(class_def=value.dump())
if isinstance(value, ModuleStub):
- return Item(module=value.name)
+ return Item(
+ module=value.name,
+ module_version=value.version or None,
+ )
if isinstance(value, (int, str, float, bool, bytes, type(None))):
return Item(primitive=value)
@@ -159,6 +153,7 @@ def from_item(item: Item, var_name: str = "") -> Any:
if item.module is not None:
mod_stub = ModuleStub.__new__(ModuleStub)
mod_stub.name = item.module
+ mod_stub.version = item.module_version or ""
return mod_stub
if item.import_ref is not None:
module, qualname = item.import_ref
@@ -384,15 +379,23 @@ class LazyLoader(BasePersistenceLoader):
"""Loaders the current session has created (for flush/export)."""
return list(_cache_state().active_lazy_loaders.values())
+ def mark_stale(self, manifest_key: str) -> None:
+ """Force this manifest to miss for the rest of the session."""
+ _cache_state().stale_keys.add(manifest_key)
+
def load_cache(
self,
key: HashKey,
glbls: dict[str, Any] | None = None,
) -> Cache | None:
del glbls
+ manifest_key = str(self.build_path(key))
+ # Invalidated for re-execution this session.
+ if manifest_key in _cache_state().stale_keys:
+ return None
blob: bytes | None = None
try:
- blob = self.store.get(str(self.build_path(key)))
+ blob = self.store.get(manifest_key)
if not blob:
return None
return self.restore_cache(key, blob)
@@ -471,6 +474,13 @@ class LazyLoader(BasePersistenceLoader):
val = unpickled.get(ref_key)
if var_name in cache_data.ui_defs and isinstance(val, dict):
defs[var_name] = val[var_name]
+ elif isinstance(val, UnhashableStub):
+ # Fall through stub.
+ defs[var_name] = UnhashableStub(
+ var_name=var_name,
+ type_name=val.type_name,
+ error_msg=val.error_msg,
+ )
else:
defs[var_name] = val
else:
@@ -511,7 +521,13 @@ class LazyLoader(BasePersistenceLoader):
type_hint = ref_type_hints.get(key) or (
return_type_hint if key == return_ref else None
)
- return deserialize(data, type_hint)
+ try:
+ return deserialize(data, type_hint)
+ except ModuleNotFoundError as e:
+ # Raise if we need something for return, otherwise defer to a stub.
+ if key == return_ref:
+ raise
+ return UnhashableStub(error_msg=str(e), type_name=type_hint)
def _read_blobs(
self,
@@ -567,6 +583,9 @@ class LazyLoader(BasePersistenceLoader):
# Reap completed threads
self._pending = [t for t in self._pending if t.is_alive()]
+ # Fresh load, so invalidate the "stale" marker.
+ _cache_state().stale_keys.discard(str(self.build_path(cache.key)))
+
path = Path(self.name) / cache.hash
variable_hashes = cache.meta.get("variable_hashes", {})
return_item = to_item(
diff --git a/marimo/_save/loaders/loader.py b/marimo/_save/loaders/loader.py
index 79fad423ec..ae66ca5695 100644
--- a/marimo/_save/loaders/loader.py
+++ b/marimo/_save/loaders/loader.py
@@ -230,6 +230,13 @@ class BasePersistenceLoader(Loader):
def cache_hit(self, key: HashKey) -> bool:
return self.store.hit(str(self.build_path(key)))
+ def mark_stale(self, manifest_key: str) -> None:
+ """Force a manifest to miss for the rest of the session.
+
+ No-op by default; loaders with a session-scoped store override this to
+ record the key as stale.
+ """
+
def save_cache(self, cache: Cache) -> bool:
blob = self.to_blob(cache)
if blob is None:
diff --git a/marimo/_save/stubs/lazy_stub.py b/marimo/_save/stubs/lazy_stub.py
index 368e241c2a..5d8363bef1 100644
--- a/marimo/_save/stubs/lazy_stub.py
+++ b/marimo/_save/stubs/lazy_stub.py
@@ -57,6 +57,8 @@ class Item(msgspec.Struct):
# tripwire from this marker (see `from_item`), so a missing-blob load never
# masquerades as a clean cache hit.
unserializable_type: str | None = None
+ # Pinned version of a `module` def, captured at cache time.
+ module_version: str | None = None
def __post_init__(self) -> None:
fields_set = sum(
@@ -133,13 +135,6 @@ LAZY_STUB_LOOKUP: dict[str, str] = {
"torch.Tensor": "pt",
}
-# Runtime cache: type → loader string, populated by maybe_update_lazy_stub().
-_LAZY_STUB_CACHE: dict[type, str] = {}
-
-# ---------------------------------------------------------------------------
-# Deserializers — keyed by file extension
-# ---------------------------------------------------------------------------
-
def _npy_load(data: bytes, type_hint: str | None = None) -> Any:
DependencyManager.numpy.require("to load cached numpy arrays.")
diff --git a/marimo/_save/stubs/module_stub.py b/marimo/_save/stubs/module_stub.py
index a58bf6ddd9..74fbc6afa7 100644
--- a/marimo/_save/stubs/module_stub.py
+++ b/marimo/_save/stubs/module_stub.py
@@ -14,9 +14,14 @@ class MissingModule(ModuleType):
Enables loading a cache lazily until a module is actually needed.
"""
- def __init__(self, name: str) -> None:
+ def __init__(self, name: str, version: str = "") -> None:
super().__init__(name)
self.__missing__ = True
+ # Replay the pinned version captured at cache time so a version-pinned
+ # content hash reproduces here even though the real module is absent.
+ # Set as a concrete attribute so it resolves without hitting the
+ # `__getattr__` fallback below (which rejects dunder probes).
+ self.__version__ = version
def __getattr__(self, attr: str) -> Any:
if attr.startswith("__") and attr.endswith("__"):
@@ -34,9 +39,17 @@ class MissingModule(ModuleType):
class ModuleStub:
"""Stub for module objects, storing only the module name."""
- def __init__(self, module: Any, hash: str = "") -> None: # noqa: A002
+ def __init__(
+ self,
+ module: Any,
+ hash: str = "", # noqa: A002
+ version: str = "",
+ ) -> None:
self.name = module.__name__
self.hash = hash
+ # `str(...)`: some packages expose a non-str `__version__` (e.g.
+ # torch's `TorchVersion`) that the manifest codec can't encode.
+ self.version = str(version or getattr(module, "__version__", "") or "")
def load(self) -> Any:
"""Reload the module by name.
@@ -56,5 +69,5 @@ class ModuleStub:
or missing == self.name
or self.name.startswith(f"{missing}.")
):
- return MissingModule(self.name)
+ return MissingModule(self.name, self.version)
raise
diff --git a/tests/_runtime/runner/test_cancelled_cells.py b/tests/_runtime/runner/test_cancelled_cells.py
index 5398a470c7..d84ddc8c0e 100644
--- a/tests/_runtime/runner/test_cancelled_cells.py
+++ b/tests/_runtime/runner/test_cancelled_cells.py
@@ -79,3 +79,62 @@ class TestCancelledCells:
assert CellId_t("x") not in cc
cc.add(CellId_t("r"), {CellId_t("x")})
assert CellId_t("x") in cc
+
+ def test_discard_descendant(self) -> None:
+ """Discarding a descendant removes only it; siblings stay cancelled."""
+ cc = CancelledCells()
+ cc.add(CellId_t("r"), {CellId_t("d1"), CellId_t("d2")})
+ cc.discard(CellId_t("d1"))
+ assert CellId_t("d1") not in cc
+ assert CellId_t("d2") in cc
+ assert cc[CellId_t("r")] == {CellId_t("d2")}
+
+ def test_discard_raising_cell_clears_its_descendants(self) -> None:
+ """Discarding a raising cell drops its entry and the flat view with it.
+
+ Regression: popping the raiser must not strand its descendants in the
+ flat set, since nothing references them anymore.
+ """
+ cc = CancelledCells()
+ cc.add(CellId_t("r"), {CellId_t("d1"), CellId_t("d2")})
+ cc.discard(CellId_t("r"))
+ assert CellId_t("r") not in cc
+ assert CellId_t("d1") not in cc
+ assert CellId_t("d2") not in cc
+ assert not cc
+ assert list(cc) == []
+
+ def test_discard_last_descendant_prunes_empty_raiser(self) -> None:
+ """A raiser with no cancelled descendants left is dropped entirely, so
+ `bool()` and iteration don't report a phantom cancellation."""
+ cc = CancelledCells()
+ cc.add(CellId_t("r"), {CellId_t("d")})
+ cc.discard(CellId_t("d"))
+ assert CellId_t("d") not in cc
+ assert not cc
+ assert list(cc) == []
+
+ def test_discard_shared_descendant_kept_by_other_raiser(self) -> None:
+ """A descendant cancelled by two raisers survives discarding one raiser."""
+ cc = CancelledCells()
+ cc.add(CellId_t("a"), {CellId_t("b")})
+ cc.add(CellId_t("x"), {CellId_t("b")})
+ cc.discard(CellId_t("a"))
+ # b is still cancelled by x.
+ assert CellId_t("b") in cc
+ assert set(cc) == {CellId_t("x")}
+
+ def test_discard_cell_that_is_both_raiser_and_descendant(self) -> None:
+ """A cell cancelled as a descendant that also raised its own cascade:
+ discarding it clears it and the cells it raised, but leaves siblings."""
+ cc = CancelledCells()
+ # A cancelled {B, C}; B in turn cancelled D.
+ cc.add(CellId_t("a"), {CellId_t("b"), CellId_t("c")})
+ cc.add(CellId_t("b"), {CellId_t("d")})
+ cc.discard(CellId_t("b"))
+ assert CellId_t("b") not in cc
+ assert CellId_t("d") not in cc
+ # C was A's other descendant and is untouched.
+ assert CellId_t("c") in cc
+ assert set(cc) == {CellId_t("a")}
+ assert cc[CellId_t("a")] == {CellId_t("c")}
diff --git a/tests/_runtime/test_cached_stage.py b/tests/_runtime/test_cached_stage.py
new file mode 100644
index 0000000000..e29afccab8
--- /dev/null
+++ b/tests/_runtime/test_cached_stage.py
@@ -0,0 +1,401 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Tests for CachedLifecycle — cell-level caching as a per-cell lifecycle.
+
+Ported from the original cell-caching test suite and adapted to the
+integrated `executor/lifecycles` framework (the source branch's
+`CachedStage`/`wrappers` names were abandoned intermediate renames).
+UnhashableStub tripwire assertions follow the shipped design: `__call__`
+is the only tripwire; other accesses fall through to Python defaults.
+"""
+
+from __future__ import annotations
+
+import copy
+import dataclasses
+from typing import TYPE_CHECKING
+
+import pytest
+
+from marimo._runtime.exceptions import (
+ MarimoRescheduleError,
+)
+from marimo._runtime.executor.lifecycles.cached import CachedLifecycle
+from marimo._save.loaders.lazy import LazyLoader
+
+try:
+ # Ships with the stub serialization toolkit; the lifecycle detects
+ # stubs through the __marimo_unhashable__ protocol attribute and has
+ # no hard dependency on the class.
+ from marimo._save.stubs.lazy_stub import UnhashableStub
+except ImportError: # pragma: no cover
+ UnhashableStub = None # type: ignore[assignment]
+
+# The end-to-end tripwire tests additionally need the lazy loader that
+# *produces* UnhashableStub on serialization failure.
+try:
+ from marimo._save.loaders.lazy import LazyStore as _LazyStore
+except ImportError: # pragma: no cover
+ _LazyStore = None # type: ignore[assignment]
+
+requires_stub_loader = pytest.mark.skipif(
+ UnhashableStub is None or _LazyStore is None,
+ reason="needs the stub toolkit + per-def lazy store",
+)
+
+
+class _MarkerStub:
+ """Minimal stand-in carrying the unhashable-stub protocol marker."""
+
+ # Class-level protocol marker (no annotation → not a dataclass field).
+ __marimo_unhashable__ = True
+
+ var_name: str
+
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+ from tests.conftest import ExecReqProvider, MockedKernel
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+def cache_dir(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+ """Redirect FileStore's default save path to a tmp dir for the test."""
+ cache_path = tmp_path / "cache"
+ cache_path.mkdir()
+
+ def _default_save_path(_self: object) -> Path:
+ return cache_path
+
+ monkeypatch.setattr(
+ "marimo._save.stores.file.FileStore._default_save_path",
+ _default_save_path,
+ )
+ return cache_path
+
+
+def tracked_loaders(monkeypatch: pytest.MonkeyPatch) -> list[LazyLoader]:
+ """Capture every LazyLoader instance constructed during the test.
+
+ Lifecycles live on each Runner instance and are GC'd between runs, so
+ there's no kernel-level handle on the loader. Tracking via __init__
+ lets tests call .flush() on every loader to drain background save
+ threads deterministically (instead of sleeping).
+ """
+ instances: list[LazyLoader] = []
+ original_init = LazyLoader.__init__
+
+ def _tracking_init(
+ self: LazyLoader,
+ *args: object,
+ **kwargs: object,
+ ) -> None:
+ original_init(self, *args, **kwargs) # type: ignore[arg-type]
+ instances.append(self)
+
+ monkeypatch.setattr(LazyLoader, "__init__", _tracking_init)
+ return instances
+
+
+def caching_kernel(
+ mocked_kernel: MockedKernel,
+ cache_dir: Path, # noqa: ARG001 — needed for side effect
+ tracked_loaders: list[LazyLoader], # noqa: ARG001 — needed for side effect
+) -> MockedKernel:
+ """A kernel with cache_cells enabled and a tmp cache dir."""
+ # Deep-copy so we don't mutate the shared DEFAULT_CONFIG dict.
+ mocked_kernel.k.user_config = copy.deepcopy(mocked_kernel.k.user_config)
+ mocked_kernel.k.user_config["runtime"]["cache_cells"] = True
+ return mocked_kernel
+
+
+# ---------------------------------------------------------------------------
+# CachedLifecycle._preflight_refs — stub-ref detection routes to requeue
+# ---------------------------------------------------------------------------
+
+
+class TestCachedLifecyclePreflight:
+ def test_stub_ref_invalidates_producer_and_raises(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """When a consumer's transitive ref resolves to an UnhashableStub in
+ scope, pre-flight marks the producers as stale (so it re-runs live
+ rather than re-hitting the same unusable value) and raises
+ MarimoRescheduleError with cells_to_rerun populated, so run_all can
+ requeue the producer (plus this cell).
+ """
+ from unittest.mock import MagicMock
+
+ graph = MagicMock()
+ graph.get_defining_cells.return_value = {"producer"}
+
+ life = CachedLifecycle(graph)
+ producer_manifest = "lazy/E_producer.jsonl"
+ life._restored_keys["producer"] = producer_manifest
+
+ # Invalidation both clears the store entry (for on-disk/in-memory
+ # stores) and marks it stale (so the lazy WASM store can't re-fetch
+ # and re-hit the same value over HTTP).
+ stale_calls: list[str] = []
+ clear_calls: list[str] = []
+ monkeypatch.setattr(
+ life._loader, "mark_stale", lambda key: stale_calls.append(key)
+ )
+ monkeypatch.setattr(
+ life._loader.store,
+ "clear",
+ lambda key: bool(clear_calls.append(key)),
+ )
+
+ cell = _FakeCell("consumer", refs={"f"})
+ glbls = {"f": _MarkerStub("f")}
+
+ with pytest.raises(MarimoRescheduleError) as ei:
+ life._preflight_refs(cell, glbls) # type: ignore[arg-type]
+
+ assert stale_calls == [producer_manifest]
+ assert clear_calls == [producer_manifest]
+ assert {"producer", "consumer"} <= ei.value.cells_to_rerun
+
+ def test_persistent_stub_producer_not_requeued_twice(self) -> None:
+ """A producer already invalidated once that still hands back a stub
+ is not requeued again: pre-flight returns cleanly so the body runs
+ and the tripwire raises on access, rather than looping forever.
+ """
+ from unittest.mock import MagicMock
+
+ graph = MagicMock()
+ graph.get_defining_cells.return_value = {"producer"}
+
+ life = CachedLifecycle(graph)
+ # Producer already had its rerun and still yields a stub.
+ life._invalidated.add("producer")
+
+ cell = _FakeCell("consumer", refs={"f"})
+ glbls = {"f": _MarkerStub("f")}
+ # No MarimoRescheduleError — falls through to run the body.
+ life._preflight_refs(cell, glbls) # type: ignore[arg-type]
+
+ def test_invalidated_guard_resets_on_clean_rerun(self) -> None:
+ """A producer guarded after invalidation is released once it runs
+ cleanly, so a later pre-flight can requeue it again. Only a cell that
+ keeps erroring stays guarded — that is the loop the bound stops.
+ """
+ from unittest.mock import MagicMock
+
+ from marimo._runtime.runner.result import RunResult
+
+ life = CachedLifecycle(MagicMock())
+ producer = _FakeCell("producer")
+ producer.defs = {"g"}
+
+ # A clean run that replaced the stub releases the guard.
+ life._invalidated.add("producer")
+ life.teardown(
+ producer, # type: ignore[arg-type]
+ {"g": 123},
+ RunResult(output=None, exception=None),
+ )
+ assert "producer" not in life._invalidated
+
+ # A clean run that still PROPAGATES a stub stays guarded (e.g. `g = f`
+ # where f is a stub) — otherwise the consumer requeues it forever.
+ life._invalidated.add("producer")
+ life.teardown(
+ producer, # type: ignore[arg-type]
+ {"g": _MarkerStub("g")},
+ RunResult(output=None, exception=None),
+ )
+ assert "producer" in life._invalidated
+
+ # An erroring run keeps it guarded (so it can't loop).
+ life._invalidated.add("producer")
+ life.teardown(
+ producer, # type: ignore[arg-type]
+ {},
+ RunResult(output=None, exception=ValueError("boom")),
+ )
+ assert "producer" in life._invalidated
+
+ def test_no_stub_refs_is_noop(self) -> None:
+ """Pre-flight returns cleanly when no ref is an UnhashableStub."""
+ from unittest.mock import MagicMock
+
+ life = CachedLifecycle(MagicMock())
+ cell = _FakeCell("consumer", refs={"x"})
+ # No exception expected.
+ life._preflight_refs(cell, {"x": 123}) # type: ignore[arg-type]
+
+ def test_restore_cache_exception_falls_through_to_miss(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """`Cache.restore` can raise `CacheException`, which subclasses
+ `BaseException` (not `Exception`). Setup must catch it explicitly
+ so a corrupt-cache hit falls through to miss-path execution rather
+ than escaping as a hard cell error.
+ """
+ from unittest.mock import MagicMock
+
+ import marimo._runtime.executor.lifecycles.cached as cached_mod
+ from marimo._save.cache import CacheException
+
+ life = CachedLifecycle(MagicMock())
+
+ attempt = MagicMock()
+ attempt.hit = True
+ attempt.restore.side_effect = CacheException("corrupt blob")
+ monkeypatch.setattr(
+ cached_mod, "cache_attempt_from_hash", lambda *_a, **_k: attempt
+ )
+
+ cell = _FakeCell("consumer", refs=set())
+ # Must not raise; returns None (miss path) and drops the attempt.
+ assert life.setup(cell, {}) is None # type: ignore[arg-type]
+ assert "consumer" not in life._attempts
+ attempt.restore.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# Integration tests — full kernel with cache_cells enabled
+# ---------------------------------------------------------------------------
+
+
+class TestCachedLifecycleIntegration:
+ async def test_basic_hit_miss_cycle(
+ self,
+ caching_kernel: MockedKernel,
+ exec_req: ExecReqProvider,
+ tracked_loaders: list[LazyLoader],
+ ) -> None:
+ """First run misses + executes; second run with same code hits."""
+ k = caching_kernel.k
+ er = exec_req.get(code="x = 1 + 2")
+
+ await k.run([er])
+ assert k.globals["x"] == 3
+
+ for loader in tracked_loaders:
+ loader.flush()
+
+ loaders_before_second = list(tracked_loaders)
+ await k.run([er])
+ assert k.globals["x"] == 3
+
+ new_loaders = [
+ ld for ld in tracked_loaders if ld not in loaders_before_second
+ ]
+ assert new_loaders, "Expected a fresh LazyLoader for the second run"
+ assert any(ld.hits > 0 for ld in new_loaders), (
+ "Expected the second run's LazyLoader to record a cache hit"
+ )
+
+ @requires_stub_loader
+ async def test_unhashable_own_def_does_not_auto_rerun(
+ self,
+ caching_kernel: MockedKernel,
+ exec_req: ExecReqProvider,
+ tracked_loaders: list[LazyLoader],
+ ) -> None:
+ """Cell whose own def is a lambda: cache hit on next session,
+ body skipped, marker in scope. Not auto-rerun (that would defeat
+ caching for cells where downstream never needs the real value).
+ """
+ k = caching_kernel.k
+ er = exec_req.get(code="f = lambda x: x + 1")
+
+ await k.run([er])
+ assert callable(k.globals["f"])
+ assert k.globals["f"](2) == 3
+
+ for loader in tracked_loaders:
+ loader.flush()
+
+ # Simulate fresh session.
+ k.globals.pop("f", None)
+
+ loaders_before_second = list(tracked_loaders)
+ await k.run([er])
+ new_loaders = [
+ ld for ld in tracked_loaders if ld not in loaders_before_second
+ ]
+
+ # Body skipped — `f` in scope is the UnhashableStub marker.
+ assert isinstance(k.globals.get("f"), UnhashableStub)
+ assert any(ld.hits > 0 for ld in new_loaders)
+
+ async def test_failed_run_not_cached(
+ self,
+ caching_kernel: MockedKernel,
+ exec_req: ExecReqProvider,
+ tracked_loaders: list[LazyLoader],
+ ) -> None:
+ k = caching_kernel.k
+ er = exec_req.get(code="raise RuntimeError('boom')")
+
+ await k.run([er])
+
+ for loader in tracked_loaders:
+ loader.flush()
+
+ loaders_before_second = list(tracked_loaders)
+ await k.run([er])
+
+ new_loaders = [
+ ld for ld in tracked_loaders if ld not in loaders_before_second
+ ]
+ assert new_loaders
+ assert all(ld.hits == 0 for ld in new_loaders)
+
+ @requires_stub_loader
+ async def test_consumer_calling_lambda_recovers(
+ self,
+ caching_kernel: MockedKernel,
+ exec_req: ExecReqProvider,
+ tracked_loaders: list[LazyLoader],
+ ) -> None:
+ """Producer A defines a lambda; consumer B references it directly.
+ After fresh-kernel reset, A hits cache (stub in scope), B's hash
+ differs and misses, B's pre-flight sees the stub in its refs →
+ invalidates A and requeues. A re-runs with the real lambda; B
+ retries; `g == 15`.
+ """
+ k = caching_kernel.k
+ producer = exec_req.get(code="f = lambda x: x + 10")
+ consumer = exec_req.get(code="g = f(5)")
+
+ await k.run([producer, consumer])
+ assert k.globals["g"] == 15
+
+ for loader in tracked_loaders:
+ loader.flush()
+
+ # Simulate fresh session.
+ k.globals.pop("f", None)
+ k.globals.pop("g", None)
+
+ await k.run([producer, consumer])
+ assert k.globals["g"] == 15
+ assert callable(k.globals["f"])
+ assert not isinstance(k.globals["f"], UnhashableStub)
+ assert not isinstance(k.globals["g"], UnhashableStub)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+class _FakeCell:
+ def __init__(self, cell_id: str, refs: set[str] | None = None) -> None:
+ self.cell_id = cell_id
+ self.refs = refs or set()
+ self.defs: set[str] = set()
+ self.mod = None
diff --git a/tests/_runtime/test_scheduler.py b/tests/_runtime/test_scheduler.py
index f6b52ad056..136ff77131 100644
--- a/tests/_runtime/test_scheduler.py
+++ b/tests/_runtime/test_scheduler.py
@@ -64,6 +64,78 @@ def test_cancel_marks_cancelled(
cell_mock.set_run_result_status.assert_called_with("cancelled")
+def test_requeue_for_rerun_moves_producer_ahead_of_queued_consumer(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """A producer already queued *behind* the consumer is moved to the head
+ so it runs before the consumer's retry — not left stranded behind it
+ (which would re-trip on the stale value forever)."""
+ p, c, y = CellId_t("P"), CellId_t("C"), CellId_t("Y")
+
+ def fake_topo(graph: object, cells: set[CellId_t]) -> list[CellId_t]:
+ del graph
+ return [cid for cid in (p, c) if cid in cells] # producer first
+
+ monkeypatch.setattr("marimo._runtime.dataflow.topological_sort", fake_topo)
+ # Consumer C is the current (popped) cell, not in the queue; producer P
+ # is already queued, behind Y.
+ sched = SequentialScheduler([y, p], graph=_empty_graph())
+ sched.requeue_for_rerun({p, c})
+ assert list(sched.cells_to_run) == [p, c, y]
+
+
+def test_requeue_for_rerun_no_duplicate(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """A requeued cell already in the queue is moved, not duplicated."""
+ p, c = CellId_t("P"), CellId_t("C")
+
+ def fake_topo(graph: object, cells: set[CellId_t]) -> list[CellId_t]:
+ del graph
+ return [cid for cid in (p, c) if cid in cells]
+
+ monkeypatch.setattr("marimo._runtime.dataflow.topological_sort", fake_topo)
+ sched = SequentialScheduler([c], graph=_empty_graph())
+ sched.requeue_for_rerun({p, c})
+ queued = list(sched.cells_to_run)
+ assert queued == [p, c]
+ assert queued.count(c) == 1
+
+
+def test_requeue_for_rerun_uncancels_stranded_descendants(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Requeuing a raiser (without its descendants in the rerun set, as
+ `cells_to_rerun = self | producers` does) must not leave the descendants
+ it previously cancelled stuck in the cancelled set."""
+ r, d = CellId_t("R"), CellId_t("D")
+ g = MagicMock()
+ g.cells = {r: MagicMock(), d: MagicMock()}
+
+ def fake_closure(graph: object, roots: set[CellId_t]) -> set[CellId_t]:
+ del graph, roots
+ return {r, d} # cancelling R also cancels descendant D
+
+ def fake_topo(graph: object, cells: set[CellId_t]) -> list[CellId_t]:
+ del graph
+ return [cid for cid in (r, d) if cid in cells]
+
+ monkeypatch.setattr(
+ "marimo._runtime.dataflow.transitive_closure", fake_closure
+ )
+ monkeypatch.setattr("marimo._runtime.dataflow.topological_sort", fake_topo)
+
+ sched = SequentialScheduler([r, d], graph=g)
+ sched.cancel(r)
+ assert sched.cancelled(r) is True
+ assert sched.cancelled(d) is True
+
+ # Rerun set contains only the raiser, not descendant D.
+ sched.requeue_for_rerun({r})
+ assert sched.cancelled(r) is False
+ assert sched.cancelled(d) is False
+
+
def test_batch_yields_singletons() -> None:
sched = SequentialScheduler([], graph=_empty_graph())
cells = [CellId_t("a"), CellId_t("b"), CellId_t("c")]
diff --git a/tests/_save/loaders/test_lazy_wasm.py b/tests/_save/loaders/test_lazy_wasm.py
index 4d9261d344..50c1bf495a 100644
--- a/tests/_save/loaders/test_lazy_wasm.py
+++ b/tests/_save/loaders/test_lazy_wasm.py
@@ -286,6 +286,379 @@ class TestLazyLoaderBatchPath:
assert loaded.defs["y"] == "hello"
+class TestRestoreTripwire:
+ """A cached def whose codec needs an absent package binds as a use-site
+ tripwire instead of aborting the whole restore. The return value is
+ excluded so a stubbed return never becomes the cell's output."""
+
+ @pytest.fixture(autouse=True)
+ def _isolate_poisoned_keys(self) -> Iterator[None]:
+ # A restore failure (e.g. the WASM return-value test) poisons keys on
+ # the shared process-local CacheState; snapshot/restore so it doesn't
+ # leak into other classes' exact-poison-set assertions.
+ poisoned = _cache_state().poisoned_keys
+ snapshot = set(poisoned)
+ yield
+ poisoned.clear()
+ poisoned.update(snapshot)
+
+ @staticmethod
+ def _patch_failing_codec(monkeypatch: pytest.MonkeyPatch) -> None:
+ # A `.faildep` codec that always raises ModuleNotFoundError, standing
+ # in for e.g. a torch tensor restored where torch is not installed.
+ from marimo._save.loaders import lazy as lazy_mod
+
+ def _boom(_data: bytes, _type_hint: str | None = None) -> object:
+ raise ModuleNotFoundError("No module named 'torch'")
+
+ monkeypatch.setitem(lazy_mod.BLOB_DESERIALIZERS, ".faildep", _boom)
+
+ @staticmethod
+ def _patch_failing_pickle(monkeypatch: pytest.MonkeyPatch) -> None:
+ # Fail `.pickle` deserialization only for a sentinel payload, so a
+ # single blob (e.g. shared `ui.pickle`) can be made undeserializable
+ # while other pickled blobs still load normally.
+ from marimo._save.loaders import lazy as lazy_mod
+
+ real = lazy_mod.BLOB_DESERIALIZERS[".pickle"]
+
+ def _maybe_boom(data: bytes, type_hint: str | None = None) -> object:
+ if data == b"__FAIL__":
+ raise ModuleNotFoundError("No module named 'torch'")
+ return real(data, type_hint)
+
+ monkeypatch.setitem(
+ lazy_mod.BLOB_DESERIALIZERS, ".pickle", _maybe_boom
+ )
+
+ @staticmethod
+ def _seed(
+ store: Store,
+ loader: LazyLoader,
+ defs: dict,
+ meta: Meta,
+ ui_defs: list[str] | None = None,
+ ) -> None:
+ from marimo._save.hash import HashKey
+
+ manifest = msgspec.json.encode(
+ CacheSchema(
+ hash="h",
+ cache_type=CacheType("Pure"),
+ defs=defs,
+ stateful_refs=[],
+ meta=meta,
+ ui_defs=ui_defs or [],
+ )
+ )
+ key = HashKey(hash="h", cache_type="Pure")
+ store.put(str(loader.build_path(key)), manifest)
+
+ def _assert_tripwire(self, loader: LazyLoader) -> None:
+ from marimo._runtime.exceptions import MarimoUnhashableCacheError
+ from marimo._save.hash import HashKey
+
+ loaded = loader.load_cache(HashKey(hash="h", cache_type="Pure"))
+ assert loaded is not None
+ assert loaded.hit is True
+ # The healthy def restored normally.
+ assert loaded.defs["good"] == "ok"
+ # The missing-dep def is a use-site tripwire naming itself.
+ stub = loaded.defs["bad"]
+ assert getattr(type(stub), "__marimo_unhashable__", False) is True
+ assert stub.var_name == "bad"
+ assert stub.type_name == "torch.Tensor"
+ # Inert until touched; a real access raises a clear unhydratable error.
+ with pytest.raises(MarimoUnhashableCacheError):
+ stub()
+
+ def test_def_blob_missing_dep_binds_tripwire_native(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ self._patch_failing_codec(monkeypatch)
+ store = LazyStore(inner=DictStore())
+ loader = LazyLoader("trip_native", store=store)
+
+ base = Path("trip_native") / "h"
+ good_ref = (base / "good.pickle").as_posix()
+ bad_ref = (base / "bad.faildep").as_posix()
+ store.put(good_ref, pickle.dumps("ok"))
+ store.put(bad_ref, b"unused")
+ self._seed(
+ store,
+ loader,
+ {
+ "good": Item(reference=good_ref),
+ "bad": Item(reference=bad_ref, type_hint="torch.Tensor"),
+ },
+ Meta(version=MARIMO_CACHE_VERSION),
+ )
+ self._assert_tripwire(loader)
+
+ def test_def_blob_missing_dep_binds_tripwire_wasm(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ # Exercises the WASM `_read_blobs` variant (get_batch, no threads).
+ self._patch_failing_codec(monkeypatch)
+ store = WasmLazyStore(inner=DictStore())
+ loader = WasmLazyLoader("trip_wasm", store=store)
+
+ base = Path("trip_wasm") / "h"
+ good_ref = (base / "good.pickle").as_posix()
+ bad_ref = (base / "bad.faildep").as_posix()
+ store.put(good_ref, pickle.dumps("ok"))
+ store.put(bad_ref, b"unused")
+ self._seed(
+ store,
+ loader,
+ {
+ "good": Item(reference=good_ref),
+ "bad": Item(reference=bad_ref, type_hint="torch.Tensor"),
+ },
+ Meta(version=MARIMO_CACHE_VERSION),
+ )
+ self._assert_tripwire(loader)
+
+ def test_return_blob_missing_dep_is_not_stubbed(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ # A return value that can't deserialize must NOT become a stubbed
+ # output; the restore fails cleanly (miss) instead.
+ self._patch_failing_codec(monkeypatch)
+ from marimo._save.hash import HashKey
+
+ store = LazyStore(inner=DictStore())
+ loader = LazyLoader("trip_return", store=store)
+
+ base = Path("trip_return") / "h"
+ good_ref = (base / "good.pickle").as_posix()
+ ret_ref = (base / "return.faildep").as_posix()
+ store.put(good_ref, pickle.dumps("ok"))
+ store.put(ret_ref, b"unused")
+ self._seed(
+ store,
+ loader,
+ {"good": Item(reference=good_ref)},
+ Meta(
+ version=MARIMO_CACHE_VERSION,
+ return_value=Item(reference=ret_ref, type_hint="torch.Tensor"),
+ ),
+ )
+ # Clean miss — no stub leaks out as the cell output.
+ assert loader.load_cache(HashKey(hash="h", cache_type="Pure")) is None
+
+ def test_return_blob_missing_dep_is_not_stubbed_wasm(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ # Same exclusion on the WASM restore path (get_batch): the re-raised
+ # ModuleNotFoundError bubbles to load_cache, which returns None.
+ self._patch_failing_codec(monkeypatch)
+ from marimo._save.hash import HashKey
+
+ store = WasmLazyStore(inner=DictStore())
+ loader = WasmLazyLoader("trip_return_wasm", store=store)
+
+ base = Path("trip_return_wasm") / "h"
+ good_ref = (base / "good.pickle").as_posix()
+ ret_ref = (base / "return.faildep").as_posix()
+ store.put(good_ref, pickle.dumps("ok"))
+ store.put(ret_ref, b"unused")
+ self._seed(
+ store,
+ loader,
+ {"good": Item(reference=good_ref)},
+ Meta(
+ version=MARIMO_CACHE_VERSION,
+ return_value=Item(reference=ret_ref, type_hint="torch.Tensor"),
+ ),
+ )
+ assert loader.load_cache(HashKey(hash="h", cache_type="Pure")) is None
+
+ def test_shared_ui_blob_labels_each_def(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ # All UI vars share one `ui.pickle` blob. When it can't deserialize,
+ # each UI def must become its OWN tripwire naming itself — not one
+ # shared stub reporting an arbitrary sibling's name.
+ self._patch_failing_pickle(monkeypatch)
+ from marimo._runtime.exceptions import MarimoUnhashableCacheError
+ from marimo._save.hash import HashKey
+
+ store = LazyStore(inner=DictStore())
+ loader = LazyLoader("trip_ui", store=store)
+
+ ui_ref = (Path("trip_ui") / "h" / "ui.pickle").as_posix()
+ store.put(ui_ref, b"__FAIL__")
+ self._seed(
+ store,
+ loader,
+ {
+ "ui_a": Item(reference=ui_ref),
+ "ui_b": Item(reference=ui_ref),
+ },
+ Meta(version=MARIMO_CACHE_VERSION),
+ ui_defs=["ui_a", "ui_b"],
+ )
+
+ loaded = loader.load_cache(HashKey(hash="h", cache_type="Pure"))
+ assert loaded is not None
+ assert loaded.hit is True
+ stub_a, stub_b = loaded.defs["ui_a"], loaded.defs["ui_b"]
+ # Distinct stubs, each naming the def it backs.
+ assert stub_a is not stub_b
+ assert stub_a.var_name == "ui_a"
+ assert stub_b.var_name == "ui_b"
+ for stub in (stub_a, stub_b):
+ with pytest.raises(MarimoUnhashableCacheError):
+ stub()
+
+ def test_import_error_is_not_downgraded(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ # The catch is narrow: only ModuleNotFoundError becomes a tripwire.
+ # A plain ImportError is a genuine failure — it must abort the restore
+ # (clean miss), not silently bind a stub.
+ from marimo._save.hash import HashKey
+ from marimo._save.loaders import lazy as lazy_mod
+
+ def _import_error(
+ _data: bytes, _type_hint: str | None = None
+ ) -> object:
+ raise ImportError("cannot import name 'X'")
+
+ monkeypatch.setitem(
+ lazy_mod.BLOB_DESERIALIZERS, ".faildep", _import_error
+ )
+
+ store = LazyStore(inner=DictStore())
+ loader = LazyLoader("trip_import", store=store)
+ bad_ref = (Path("trip_import") / "h" / "bad.faildep").as_posix()
+ store.put(bad_ref, b"unused")
+ self._seed(
+ store,
+ loader,
+ {"bad": Item(reference=bad_ref)},
+ Meta(version=MARIMO_CACHE_VERSION),
+ )
+ assert loader.load_cache(HashKey(hash="h", cache_type="Pure")) is None
+
+
+class TestModuleVersionPin:
+ """A module def restored where the module is absent must replay its
+ pinned version onto the `MissingModule` placeholder, so a version-pinned
+ content hash reproduces instead of collapsing to an empty version (which
+ would miss against a natively-exported cache)."""
+
+ def test_module_version_round_trips_through_manifest(self) -> None:
+ from types import ModuleType
+
+ from marimo._save.loaders.lazy import from_item, to_item
+ from marimo._save.stubs.module_stub import MissingModule, ModuleStub
+
+ fake = ModuleType("torch")
+ fake.__version__ = "2.9.1"
+
+ # Capture at cache time.
+ stub = ModuleStub(fake)
+ assert stub.version == "2.9.1"
+
+ # Persist through the manifest.
+ item = to_item(Path("base"), stub, var_name="torch", loader="inline")
+ assert item.module == "torch"
+ assert item.module_version == "2.9.1"
+
+ # Restore the stub with its version intact.
+ restored = from_item(item, "torch")
+ assert isinstance(restored, ModuleStub)
+ assert restored.version == "2.9.1"
+
+ # With the real module absent, load() yields a MissingModule that
+ # still reports the pinned version, so `getattr(mod, "__version__")`
+ # reproduces the pinned hash rather than an empty string.
+ restored.name = "definitely_not_a_real_module_xyz"
+ missing = restored.load()
+ assert isinstance(missing, MissingModule)
+ assert missing.__version__ == "2.9.1"
+
+ def test_missing_module_absent_version_is_empty(self) -> None:
+ # No pinned version (e.g. a submodule with no __version__) degrades to
+ # an empty string, not an error, mirroring the pre-existing behavior.
+ from marimo._save.stubs.module_stub import MissingModule
+
+ missing = MissingModule("torch.nn")
+ assert missing.__version__ == ""
+
+
+class TestStaleKeys:
+ """A manifest marked stale misses without being served or re-fetched, so
+ the producing cell re-runs live instead of restoring the same value."""
+
+ def test_mark_stale_forces_miss_without_fetch(self) -> None:
+ from marimo._save.hash import HashKey
+ from marimo._save.loaders.lazy import _cache_state
+
+ store = LazyStore(inner=DictStore())
+ loader = LazyLoader("stale_test", store=store)
+
+ base = Path("stale_test") / "h"
+ var_ref = (base / "v.pickle").as_posix()
+ store.put(var_ref, pickle.dumps("value"))
+ manifest = msgspec.json.encode(
+ CacheSchema(
+ hash="h",
+ cache_type=CacheType("Pure"),
+ defs={"v": Item(reference=var_ref)},
+ stateful_refs=[],
+ meta=Meta(version=MARIMO_CACHE_VERSION),
+ )
+ )
+ key = HashKey(hash="h", cache_type="Pure")
+ manifest_key = str(loader.build_path(key))
+ store.put(manifest_key, manifest)
+
+ # Hits before marking stale.
+ assert loader.load_cache(key) is not None
+
+ # Marking stale forces a miss even though the manifest is present.
+ stale = _cache_state().stale_keys
+ try:
+ loader.mark_stale(manifest_key)
+ assert loader.load_cache(key) is None
+ finally:
+ stale.discard(manifest_key)
+
+ def test_save_cache_clears_stale_mark(self) -> None:
+ # stale_keys is session-scoped, so a recovered cell must un-stale its
+ # own manifest on save or it would re-run live every round forever.
+ from marimo._save.hash import HashKey
+ from marimo._save.loaders.lazy import _cache_state
+
+ store = LazyStore(inner=DictStore())
+ loader = LazyLoader("stale_save", store=store)
+ key = HashKey(hash="h", cache_type="Pure")
+ manifest_key = str(loader.build_path(key))
+
+ stale = _cache_state().stale_keys
+ try:
+ loader.mark_stale(manifest_key)
+ assert manifest_key in stale
+ # Saving a fresh manifest for that key clears the stale mark.
+ loader.save_cache(
+ Cache(
+ defs={"v": 1},
+ hash="h",
+ cache_type="Pure",
+ stateful_refs=set(),
+ hit=False,
+ meta={"version": MARIMO_CACHE_VERSION},
+ )
+ )
+ assert manifest_key not in stale
+ finally:
+ stale.discard(manifest_key)
+ loader.flush()
+
+
class TestFlushAll:
def test_flush_all_flushes_active_loaders(self) -> None:
inner = DictStore()
diff --git a/tests/_save/stubs/test_module_stub.py b/tests/_save/stubs/test_module_stub.py
index 423c4b9ac6..0c6862794f 100644
--- a/tests/_save/stubs/test_module_stub.py
+++ b/tests/_save/stubs/test_module_stub.py
@@ -30,6 +30,7 @@ class TestModuleStubLoad:
stub = ModuleStub.__new__(ModuleStub)
stub.name = "marimo_definitely_not_a_real_module_xyz"
stub.hash = ""
+ stub.version = ""
result = stub.load()
assert isinstance(result, MissingModule)
assert result.__missing__ is True
@@ -54,6 +55,7 @@ class TestModuleStubLoad:
stub = ModuleStub.__new__(ModuleStub)
stub.name = mod_name
stub.hash = ""
+ stub.version = ""
with pytest.raises(ModuleNotFoundError) as exc_info:
stub.load()
# The error is about the transitive dep, not our module.
diff --git a/tests/_save/stubs/test_unhashable_stub.py b/tests/_save/stubs/test_unhashable_stub.py
index c1e65eecd7..9a28308e8a 100644
--- a/tests/_save/stubs/test_unhashable_stub.py
+++ b/tests/_save/stubs/test_unhashable_stub.py
@@ -12,7 +12,7 @@ import pickle
import pytest
from marimo._runtime.exceptions import (
- MarimoCancelCellError,
+ MarimoRescheduleError,
MarimoUnhashableCacheError,
)
from marimo._save.cache import Cache
@@ -46,7 +46,7 @@ class TestUnhashableStub:
err = MarimoUnhashableCacheError(
cells_to_rerun=set(), variables=[], error_details=""
)
- assert isinstance(err, MarimoCancelCellError)
+ assert isinstance(err, MarimoRescheduleError)
def test_pickle_roundtrip(self) -> None:
original = UnhashableStub(None, var_name="f", error_msg="oops")