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
feat(runtime): cell-level cached execution lifecycle (#9895)
Dylan Madisettif7e14225280f
diff --git a/marimo/_runtime/exceptions.py b/marimo/_runtime/exceptions.pyindex 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 behashed/serialized for cache restoration."""diff --git a/marimo/_runtime/executor/lifecycles/cached.py b/marimo/_runtime/executor/lifecycles/cached.pynew file mode 100644index 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.pyindex 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_contextfrom marimo._runtime.control_flow import MarimoInterrupt, MarimoStopErrorfrom 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 = Nonetry: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.pyindex 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] = descendantsself._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._alldiff --git a/marimo/_runtime/runner/scheduler.py b/marimo/_runtime/runner/scheduler.pyindex 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.pyindex 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 = Nonedef 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 = valuediff --git a/marimo/_save/hash.py b/marimo/_save/hash.pyindex 68cfd625ff..8dd54a8a13 100644--- a/marimo/_save/hash.py+++ b/marimo/_save/hash.py@@ -705,12 +705,17 @@ class BlockHasher:version = ""module = Noneif 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.pyindex 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] = loaderreturn 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_stubif 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 Noneblob: bytes | None = Nonetry:- blob = self.store.get(str(self.build_path(key)))+ blob = self.store.get(manifest_key)if not blob:return Nonereturn 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] = valelse:@@ -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 threadsself._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.hashvariable_hashes = cache.meta.get("variable_hashes", {})return_item = to_item(diff --git a/marimo/_save/loaders/loader.py b/marimo/_save/loaders/loader.pyindex 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.pyindex 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 = Nonedef __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.pyindex 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__ = versiondef __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.nameor self.name.startswith(f"{missing}.")):- return MissingModule(self.name)+ return MissingModule(self.name, self.version)raisediff --git a/tests/_runtime/runner/test_cancelled_cells.py b/tests/_runtime/runner/test_cancelled_cells.pyindex 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 cccc.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.pynew file mode 100644index 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 = Nonediff --git a/tests/_runtime/test_scheduler.py b/tests/_runtime/test_scheduler.pyindex 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.pyindex 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.pyindex 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_namestub.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.pyindex c1e65eecd7..9a28308e8a 100644--- a/tests/_save/stubs/test_unhashable_stub.py+++ b/tests/_save/stubs/test_unhashable_stub.py@@ -12,7 +12,7 @@ import pickleimport pytestfrom 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")