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
fix: increased cache robustness for wire level cell resolution (#10109)
Dylan Madisettib8b4ebbaefcc
diff --git a/marimo/_runtime/callbacks/__init__.py b/marimo/_runtime/callbacks/__init__.pyindex 95b8ffe7be..d8c14b9c32 100644--- a/marimo/_runtime/callbacks/__init__.py+++ b/marimo/_runtime/callbacks/__init__.py@@ -7,7 +7,10 @@ from marimo._runtime.callbacks.external_storage import (ExternalStorageCallbacks,)from marimo._runtime.callbacks.packages import PackagesCallbacks-from marimo._runtime.callbacks.protocol import KernelCallback+from marimo._runtime.callbacks.protocol import (+ KernelCallback,+ SupportsTeardown,+)from marimo._runtime.callbacks.secrets import SecretsCallbacksfrom marimo._runtime.callbacks.sql import SqlCallbacks@@ -19,4 +22,5 @@ __all__ = ["PackagesCallbacks","SecretsCallbacks","SqlCallbacks",+ "SupportsTeardown",]diff --git a/marimo/_runtime/callbacks/cache.py b/marimo/_runtime/callbacks/cache.pyindex 081391344c..3037082a6a 100644--- a/marimo/_runtime/callbacks/cache.py+++ b/marimo/_runtime/callbacks/cache.py@@ -23,6 +23,13 @@ class CacheCallbacks:router.register(ClearCacheCommand, self.clear_cache)router.register(GetCacheInfoCommand, self.get_cache_info)+ def teardown(self) -> None:+ """Flush pending cache writes so blobs are durable before teardown."""+ from marimo._save.loaders import flush_active_caches++ # NB. loaders dispatch blob writes to background threads; join them.+ flush_active_caches()+async def clear_cache(self, request: ClearCacheCommand) -> None:del requestfrom marimo._save.cache import CacheContextdiff --git a/marimo/_runtime/callbacks/protocol.py b/marimo/_runtime/callbacks/protocol.pyindex 71f74583c4..cfea21fc9e 100644--- a/marimo/_runtime/callbacks/protocol.py+++ b/marimo/_runtime/callbacks/protocol.py@@ -16,6 +16,13 @@ class KernelCallback(Protocol):def register(self, router: RequestRouter) -> None: ...+@runtime_checkable+class SupportsTeardown(Protocol):+ """A callback that releases resources when the kernel tears down."""++ def teardown(self) -> None: ...++class GlobalsView(Protocol):"""A view onto user-defined variables (kernel globals)."""diff --git a/marimo/_runtime/executor/lifecycles/cached.py b/marimo/_runtime/executor/lifecycles/cached.pyindex 114da078e9..b02c679170 100644--- a/marimo/_runtime/executor/lifecycles/cached.py+++ b/marimo/_runtime/executor/lifecycles/cached.py@@ -153,6 +153,13 @@ class CachedLifecycle:pin_modules=self._pin_modules,)self._attempts[cell_id] = attempt+ LOGGER.debug(+ "Cache %s for %s (key=%s_%s)",+ "hit" if attempt.hit else "miss",+ cell_id,+ attempt.cache_type,+ attempt.hash,+ )restored = Falseif attempt.hit:@@ -168,7 +175,8 @@ class CachedLifecycle:# 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):+ ui_live = self._restored_ui_defs(attempt, glbls)+ if not ui_live:self._restored_keys[cell_id] = str(self._loader.build_path(attempt.key))@@ -220,10 +228,7 @@ class CachedLifecycle:try:attempt.update({**glbls},- meta={- "return": run_result.output,- "runtime": runtime,- },+ meta={"return": run_result.output, "runtime": runtime},preserve_pointers=False,)saved = self._loader.save_cache(attempt)@@ -243,20 +248,25 @@ class CachedLifecycle:@staticmethoddef _restored_ui_defs(attempt: Cache, glbls: MutableGlobals) -> bool:- """True if any def restored from the cache is a live UIElement."""+ """True if the cell *defines* a live UIElement.++ `stateful_refs` are excluded — UI the cell only *reads*, whose values a+ hit's cached output already reflects. Only freshly-defined UI needs a+ live run, to re-register under session-specific UIDs.+ """from marimo._plugins.ui._core.ui_element import UIElementreturn any(- isinstance(glbls.get(name), UIElement) for name in attempt.defs+ isinstance(glbls.get(name), UIElement)+ for name in attempt.defs+ if name not in attempt.stateful_refs)def _preflight_refs(self, cell: CellImpl, glbls: MutableGlobals) -> None:- """Detect UnhashableStub residues in refs and requeue producers.+ """Requeue producers of any ref that restored as an `UnhashableStub`.- 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.+ Invalidates each producer's manifest, drops this cell's attempt (so+ teardown no-ops), and raises `MarimoRescheduleError`."""cell_id = cell.cell_idstub_vars: list[str] = []@@ -306,7 +316,7 @@ class CachedLifecycle: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+ Cells marked invalidated are skipped in future pre-flight checksto force reruns and prevent recursive deadlocks."""key = self._restored_keys.pop(cell_id, None)@@ -314,7 +324,8 @@ class CachedLifecycle:if key is None:returntry:- self._loader.store.clear(key)+ # NB. mark stale, never clear: the entry isn't corrupt, only+ # missing a dep here; it restores cleanly where the dep is present.self._loader.mark_stale(key)except Exception as e:LOGGER.warning("Manifest invalidate failed for %s: %s", key, e)diff --git a/marimo/_runtime/kernel_lifecycle.py b/marimo/_runtime/kernel_lifecycle.pyindex 7bdb941857..9adf98399e 100644--- a/marimo/_runtime/kernel_lifecycle.py+++ b/marimo/_runtime/kernel_lifecycle.py@@ -245,5 +245,7 @@ def teardown_kernel(kernel: Kernel, ctx: KernelRuntimeContext) -> None:# destruction from cleaning them up.ctx.virtual_file_registry.shutdown()ctx.app_kernel_runner_registry.shutdown()+ # NB. must run before teardown_context() unsets the context below.+ kernel.teardown_callbacks()teardown_context()kernel.teardown()diff --git a/marimo/_runtime/runtime.py b/marimo/_runtime/runtime.pyindex 5c4e54f7ce..3eb3659e18 100644--- a/marimo/_runtime/runtime.py+++ b/marimo/_runtime/runtime.py@@ -96,6 +96,7 @@ from marimo._runtime.callbacks import (PackagesCallbacks,SecretsCallbacks,SqlCallbacks,+ SupportsTeardown,)from marimo._runtime.commands import (AppMetadata,@@ -620,6 +621,15 @@ class Kernel:def stdin(self) -> Stdin | None:return self._streams.stdin+ def teardown_callbacks(self) -> None:+ """Run callback teardown while the runtime context is still alive."""+ for cb in self._callbacks:+ if isinstance(cb, SupportsTeardown):+ try:+ cb.teardown()+ except Exception:+ LOGGER.warning("Callback teardown failed", exc_info=True)+def teardown(self) -> None:"""Teardown resources owned by the kernel."""if self.stdout is not None:diff --git a/marimo/_save/cache.py b/marimo/_save/cache.pyindex 3289b5ba8e..b29c5ca737 100644--- a/marimo/_save/cache.py+++ b/marimo/_save/cache.py@@ -45,7 +45,7 @@ if TYPE_CHECKING:from marimo._save.stores import Store# NB. Increment on cache breaking changes.-MARIMO_CACHE_VERSION: int = 4+MARIMO_CACHE_VERSION: int = 5CacheType = Literal["ContextExecutionPath",@@ -166,9 +166,25 @@ class Cache:memo: dict[int, Any] = {} # Track processed objects to handle cyclesfor var, lookup in self._restore_order(self.contextual_defs()):value = self.defs.get(var, None)- scope[lookup] = self._restore_from_stub_if_needed(- value, scope, memo- )+ # NB. if a dep already degraded to an `UnhashableStub`, this value+ # can't materialize either; degrade it too rather than hit an opaque+ # pickle error the ModuleNotFoundError handler below wouldn't catch.+ degraded_dep = self._first_degraded_dep(value, scope)+ if degraded_dep is not None:+ scope[lookup] = UnhashableStub(+ var_name=var,+ error_msg=f"depends on unavailable '{degraded_dep}'",+ )+ continue+ try:+ scope[lookup] = self._restore_from_stub_if_needed(+ value, scope, memo+ )+ except ModuleNotFoundError as e:+ # NB. optional dep absent here: degrade to an `UnhashableStub`+ # instead of aborting the whole restore. It reschedules the+ # producer only if a live consumer actually uses the value.+ scope[lookup] = UnhashableStub(var_name=var, error_msg=str(e))for key, value in self.meta.items():self.meta[key] = self._restore_from_stub_if_needed(@@ -200,14 +216,29 @@ class Cache:- A re-exec'd class/function needs the defs it references atdefinition time (bases, decorators, class-body calls).+ - A cached wrapper (`is_cached`) is exempt: its body refs resolve at+ call time, so a degraded one must not block the rebuild.- A pickled instance of a cell-defined class needs that classmaterialized first (tagged via `requires`)."""- if isinstance(value, (ClassStub, FunctionStub)):+ if isinstance(value, ClassStub) or (+ isinstance(value, FunctionStub) and not value.is_cached+ ):return _source_refs(value.code)requires = getattr(value, "requires", "")return {requires} if requires else set()+ def _first_degraded_dep(+ self, value: Any, scope: dict[str, Any]+ ) -> Name | None:+ """Name of the first dependency of *value* that degraded to an+ `UnhashableStub` in *scope*, or `None` if all are available.+ """+ for dep in self._restore_deps(value):+ if isinstance(scope.get(dep), UnhashableStub):+ return dep+ return None+def _restore_order(self, contextual_defs: dict[tuple[Name, Name], Any]) -> list[tuple[Name, Name]]:@@ -394,6 +425,19 @@ class Cache:if inspect.ismodule(value):result = ModuleStub(value)+ elif (+ isinstance(value, CacheContext)+ and inspect.isfunction(+ wrapped := getattr(value, "__wrapped__", None)+ )+ and wrapped.__name__ != "<lambda>"+ and getattr(wrapped, "__module__", "__main__") == "__main__"+ and not getattr(value, "_bound", None)+ ):+ # A `@mo.cache` / `@mo.persistent_cache` wrapper: capture its+ # decorated source so restore rebuilds a working wrapper rather than+ # an `UnhashableStub`. Lambdas/bound copies can't round-trip source.+ result = FunctionStub(value, is_cached=True)elif (inspect.isfunction(value)and value.__name__ != "<lambda>"diff --git a/marimo/_save/hash.py b/marimo/_save/hash.pyindex 8dd54a8a13..370b9eae41 100644--- a/marimo/_save/hash.py+++ b/marimo/_save/hash.py@@ -754,6 +754,44 @@ class BlockHasher:serial_value = hash_wrapped_functions(value, self.hash_alg.name)+ # A restored stub — a placeholder left in scope for a value we+ # could not materialize here (e.g. a tensor whose optional dep is+ # absent in this environment). The `__marimo_unhashable__` protocol+ # marker avoids importing the stub class into the hasher.+ elif getattr(type(value), "__marimo_unhashable__", False):+ digest = getattr(value, "content_hash", "")+ type_name = getattr(value, "type_name", "") or ""+ stub_module = (+ type_name.rsplit(".", 1)[0] if "." in type_name else ""+ )+ is_marimo_stub = stub_module.startswith("marimo")+ if digest:+ # The stub carries the value's persisted content digest;+ # replay it so the key matches the native content hash+ # without recomputing `data_to_buffer(value)`.+ content_serialization[ref] = bytes.fromhex(digest)+ elif is_marimo_stub:+ # No digest, but the stub stands in for a marimo-owned value+ # (e.g. a `persistent_cache` wrapper `_cache_call`). Native+ # dequeues those with zero contribution: the external-module+ # guard below is False for marimo modules (`not+ # __module__.startswith("marimo")`), so on the real value it+ # falls through to `refs.remove`. Mirror that here so a+ # restored marimo stub does not flip the consumer's key from+ # content- to execution-addressed.+ pass+ elif local_ref in self.graph.definitions:+ # No digest: the stub stands in for a graph-defined+ # function/class/lambda, which the native run routes+ # through the execution path (via the `__main__` branch+ # below on the real value). Route by graph provenance so+ # this environment reproduces the same key.+ continue+ # A digest-less stub that is neither marimo-owned nor+ # graph-defined is dequeued with no content, matching native's+ # fall-through behaviour.+ refs.remove(local_ref)+ continue# An external module variable is assumed to be pure, with module# pinning being the mechanism for invalidation.elif getattr(value, "__module__", "__main__") == "__main__":diff --git a/marimo/_save/loaders/__init__.py b/marimo/_save/loaders/__init__.pyindex c603b7488e..2e2de7af7a 100644--- a/marimo/_save/loaders/__init__.py+++ b/marimo/_save/loaders/__init__.py@@ -5,7 +5,11 @@ from dataclasses import dataclassfrom typing import Literalfrom marimo._save.loaders.json import JsonLoader-from marimo._save.loaders.lazy import LazyLoader, WasmLazyLoader+from marimo._save.loaders.lazy import (+ LazyLoader,+ WasmLazyLoader,+ flush_active_caches,+)from marimo._save.loaders.loader import (BasePersistenceLoader,Loader,@@ -59,5 +63,6 @@ __all__ = ["MemoryLoader","PickleLoader","WasmLazyLoader",+ "flush_active_caches","resolve_loader",]diff --git a/marimo/_save/loaders/lazy.py b/marimo/_save/loaders/lazy.pyindex 467a8d3af3..48fbdd1163 100644--- a/marimo/_save/loaders/lazy.py+++ b/marimo/_save/loaders/lazy.py@@ -1,6 +1,7 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations+import hashlibimport importlibimport inspectimport pickle@@ -14,12 +15,18 @@ import msgspecfrom marimo import _loggersfrom marimo._runtime.context import safe_get_context+from marimo._runtime.primitives import (+ is_data_primitive,+ is_data_primitive_container,+ is_primitive,+)from marimo._save.cache import (MARIMO_CACHE_VERSION,Cache,CacheState,)-from marimo._save.hash import HashKey+from marimo._save.encode import common_container_to_bytes, data_to_buffer+from marimo._save.hash import DEFAULT_HASH, HashKeyfrom marimo._save.loaders.loader import BasePersistenceLoaderfrom marimo._save.stores import DEFAULT_STORE, FileStore, Store@@ -53,6 +60,27 @@ class _BlobStatus(Enum):MISSING = auto()+def _module_available(type_hint: str | None) -> bool:+ """True if the root module of `type_hint` can be imported here.++ Lets the caller skip fetching a blob whose deserializer needs an absent+ module (e.g. `torch` in a torch-free browser). Empty hint or `__main__` is+ treated as available (resolved elsewhere), so we never skip a fetch we+ can't reason about.+ """+ if not type_hint:+ return True+ root = type_hint.split(".", 1)[0]+ if root == "__main__":+ return True+ import importlib.util++ try:+ return importlib.util.find_spec(root) is not None+ except (ImportError, ValueError):+ return False++def maybe_update_lazy_stub(value: Any) -> str:value_type = type(value)# MRO not that expensive, type hashable for functools lookup.@@ -61,6 +89,24 @@ def maybe_update_lazy_stub(value: Any) -> str:return loader+def _maybe_content_digest(value: Any, hash_type: str = DEFAULT_HASH) -> str:+ """Hex content digest for an array-like data primitive, else `""`.++ Mirrors the hasher's content serialization (`data_to_buffer` /+ `common_container_to_bytes`). Plain primitives are excluded: they restore+ inline, so a consumer content-hashes the real value directly.+ """+ if is_primitive(value):+ return ""+ if is_data_primitive(value):+ serial = data_to_buffer(value)+ elif is_data_primitive_container(value):+ serial = common_container_to_bytes(value)+ else:+ return ""+ return hashlib.new(hash_type, serial, usedforsecurity=False).digest().hex()++def _maybe_import_ref(value: Any) -> tuple[str, str] | None:"""Return `(module, qualname)` if *value* is re-importable by name,else `None`.@@ -141,10 +187,12 @@ def to_item(def from_item(item: Item, var_name: str = "") -> Any:if item.unserializable_type is not None:- # No blob was written for this def — rebuild the tripwire in-memory- # from the manifest marker.+ # No blob written — rebuild the `UnhashableStub` from the marker. NB.+ # carry any persisted digest so a consumer reproduces its key from it.return UnhashableStub(- var_name=var_name, type_name=item.unserializable_type+ var_name=var_name,+ type_name=item.unserializable_type,+ content_hash=item.hash or "",)if item.reference is not None:return ImmediateReferenceStub(@@ -162,9 +210,7 @@ def from_item(item: Item, var_name: str = "") -> Any:obj = getattr(obj, part)return objif item.function is not None:- fn_stub = FunctionStub.__new__(FunctionStub)- fn_stub.code, fn_stub.filename, fn_stub.lineno = item.function- return fn_stub+ return FunctionStub.from_dump(item.function)if item.class_def is not None:return ClassStub.from_dump(item.class_def)if item.primitive is not None:@@ -199,6 +245,11 @@ def _get_wasm_dict_store() -> Store:return cache_state.wasm_dict_store+def flush_active_caches() -> None:+ """Drain pending writes for every active loader (durability on exit)."""+ LazyLoader.flush_all()++class LazyStore(Store):"""Native store for `LazyLoader`.@@ -370,7 +421,7 @@ class LazyLoader(BasePersistenceLoader):@classmethoddef flush_all(cls) -> None:- """Flush all active LazyLoader instances."""+ """Drain pending background writes for every active loader."""for loader in cls.active_loaders():loader.flush()@@ -421,6 +472,10 @@ class LazyLoader(BasePersistenceLoader):# Instances of cell-defined (__main__) classes are deferred: their# class must be re-exec'd into __main__ before the blob can unpickle.deferred: dict[str, tuple[str, str]] = {}+ # Defs whose blob we skip fetching because the value can't be+ # materialized here anyway (its module is absent). Maps to the+ # type_hint so the `UnhashableStub` can name what it stood in for.+ unresolvable: dict[str, str | None] = {}for var_name, item in cache_data.defs.items():if var_name in cache_data.ui_defs:ref_vars[var_name] = (base / "ui.pickle").as_posix()@@ -430,6 +485,8 @@ class LazyLoader(BasePersistenceLoader):item.reference,item.type_hint.rsplit(".", 1)[-1],)+ elif not _module_available(item.type_hint):+ unresolvable[var_name] = item.type_hintelse:ref_vars[var_name] = item.referenceref_type_hints[item.reference] = item.type_hint@@ -456,7 +513,16 @@ class LazyLoader(BasePersistenceLoader):# Distribute to defsdefs: dict[str, Any] = {}for var_name, item in cache_data.defs.items():- if var_name in deferred:+ if var_name in unresolvable:+ # Module absent, blob never fetched — stand in an+ # `UnhashableStub` carrying the persisted digest so a consumer+ # reproduces its key.+ defs[var_name] = UnhashableStub(+ var_name=var_name,+ type_name=unresolvable[var_name],+ content_hash=variable_hashes.get(var_name, ""),+ )+ elif var_name in deferred:ref, requires = deferred[var_name]# Read the bytes now (via this loader's store); defer only# the unpickle until Cache.restore has materialized the class.@@ -475,11 +541,13 @@ class LazyLoader(BasePersistenceLoader):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.+ # NB. carry the persisted digest so a consumer reproduces+ # its key without the value.defs[var_name] = UnhashableStub(var_name=var_name,type_name=val.type_name,error_msg=val.error_msg,+ content_hash=variable_hashes.get(var_name, ""),)else:defs[var_name] = val@@ -587,7 +655,8 @@ class LazyLoader(BasePersistenceLoader):_cache_state().stale_keys.discard(str(self.build_path(cache.key)))path = Path(self.name) / cache.hash- variable_hashes = cache.meta.get("variable_hashes", {})+ # Copy so per-def digests below don't mutate the cache's meta.+ variable_hashes = dict(cache.meta.get("variable_hashes", {}))return_item = to_item(path, cache.meta.get("return", None), var_name="return")@@ -608,6 +677,12 @@ class LazyLoader(BasePersistenceLoader):ui_defs_list: list[str] = []for var, obj in cache.defs.items():+ if var not in variable_hashes:+ # NB. persist a digest for data primitives so a consumer+ # reproduces its key without the value.+ digest = _maybe_content_digest(obj)+ if digest:+ variable_hashes[var] = digestloader = maybe_update_lazy_stub(obj)item = to_item(path,@@ -683,7 +758,8 @@ class LazyLoader(BasePersistenceLoader):for item in items:type_name = item.type_hint or fallbackitem.reference = None- item.hash = None+ # NB. keep item.hash — the content digest stays valid even+ # when the value blob can't be pickled.item.type_hint = Noneitem.unserializable_type = type_namereturn Falsediff --git a/marimo/_save/loaders/loader.py b/marimo/_save/loaders/loader.pyindex ae66ca5695..fad69b607e 100644--- a/marimo/_save/loaders/loader.py+++ b/marimo/_save/loaders/loader.py@@ -117,6 +117,14 @@ class Loader(ABC):prefix = CACHE_PREFIX.get(key.cache_type, "U_")return Path(f"{prefix}{key.hash}")+ def flush(self) -> None:+ """Drain any pending asynchronous writes so results are durable.++ No-op by default; backends that dispatch writes to background threads+ (e.g. the lazy loader) override this to join them before shutdown.+ """+ return+def cache_attempt(self,defs: set[Name],diff --git a/marimo/_save/stubs/function_stub.py b/marimo/_save/stubs/function_stub.pyindex 8f0a820751..46f5c3b4c3 100644--- a/marimo/_save/stubs/function_stub.py+++ b/marimo/_save/stubs/function_stub.py@@ -10,12 +10,24 @@ __all__ = ["FunctionStub"]class FunctionStub:- """Stub for function objects, storing the source code."""+ """Stub for function objects, storing the source code.- def __init__(self, function: Any) -> None:+ `@mo.cache` / `@mo.persistent_cache` wrappers are special-cased and recorded+ in `is_cached`, which allows lazier restoration of the wrapper.+ """++ def __init__(self, function: Any, is_cached: bool = False) -> None:+ self.is_cached = is_cached+ if is_cached:+ # Capture the wrapped body's source (incl. the decorator line).+ function = function.__wrapped__self.code = textwrap.dedent(inspect.getsource(function))self.filename = f"<{function.__name__}>"self.lineno = 1+ if is_cached:+ # NB. keep the synthetic filename: the wrapper re-hashes its own+ # source per call, and the real path is absent on restore.+ returntry:self.filename = inspect.getfile(function)@@ -39,6 +51,16 @@ class FunctionStub:for value in lcls.values():return value- def dump(self) -> tuple[str, str, int]:+ def dump(self) -> tuple[str, str, int, bool]:"""Dump stored source code and metadata for lazy serialization."""- return self.code, self.filename, self.lineno+ return self.code, self.filename, self.lineno, self.is_cached++ @classmethod+ def from_dump(cls, data: tuple[str, str, int, bool]) -> FunctionStub:+ """Reconstruct a `FunctionStub` from a `dump()` tuple.++ Skips `__init__` (which requires a live function to introspect).+ """+ stub = cls.__new__(cls)+ stub.code, stub.filename, stub.lineno, stub.is_cached = data+ return stubdiff --git a/marimo/_save/stubs/lazy_stub.py b/marimo/_save/stubs/lazy_stub.pyindex 5d8363bef1..0a3e947645 100644--- a/marimo/_save/stubs/lazy_stub.py+++ b/marimo/_save/stubs/lazy_stub.py@@ -42,8 +42,9 @@ class Item(msgspec.Struct):# `from typing import Optional` or `from os.path import join`. Stored# inline so trivial imported references never get their own blob on disk.import_ref: tuple[str, str] | None = None- # (code, filename, linenumber)- function: tuple[str, str, int] | None = None+ # (code, filename, lineno, is_cached); is_cached marks an @mo.cache /+ # @mo.persistent_cache wrapper (see `FunctionStub`).+ function: tuple[str, str, int, bool] | None = None# (code, qualname) — cell-defined class source. Materialized into the# cell namespace (and __main__) before pickle blobs deserialize, so# __main__-qualified instances can resolve their type.@@ -333,7 +334,7 @@ class UnhashableStub(CustomStub):__marimo_unhashable__ = True- __slots__ = ("error_msg", "type_name", "var_name")+ __slots__ = ("content_hash", "error_msg", "type_name", "var_name")def __init__(self,@@ -341,8 +342,13 @@ class UnhashableStub(CustomStub):var_name: str = "",error_msg: str = "",type_name: str | None = None,+ content_hash: str = "",) -> None:self.var_name = var_name+ # Hex content digest, persisted for data primitives. Lets a consumer+ # reproduce its cache key without materializing the value — the hasher+ # replays it. Empty for non-data defs, which route by graph provenance.+ self.content_hash = content_hashif type_name is not None:# Explicit fq name — used when rebuilding from a manifest marker,# where the original value object is no longer available.@@ -391,7 +397,8 @@ class UnhashableStub(CustomStub):def __repr__(self) -> str:return (f"<UnhashableStub var_name={self.var_name!r} "- f"type={self.type_name!r}>"+ f"type={self.type_name!r} "+ f"content_hash={self.content_hash!r}>")@staticmethoddiff --git a/marimo/_save/stubs/module_stub.py b/marimo/_save/stubs/module_stub.pyindex 74fbc6afa7..8de0d09ec6 100644--- a/marimo/_save/stubs/module_stub.py+++ b/marimo/_save/stubs/module_stub.py@@ -2,6 +2,7 @@from __future__ import annotationsimport importlib+import sysfrom types import ModuleTypefrom typing import Any@@ -49,7 +50,17 @@ class ModuleStub: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 "")+ version = str(version or getattr(module, "__version__", "") or "")+ if not version:+ # Submodule aliases (`import torch.nn as nn`) usually carry no own+ # `__version__`; the pinned hash falls back to the root package's+ # version, so capture that here too or the replayed placeholder+ # version won't reproduce the hash on restore.+ root = self.name.split(".", 1)[0]+ version = str(+ getattr(sys.modules.get(root), "__version__", "") or ""+ )+ self.version = versiondef load(self) -> Any:"""Reload the module by name.diff --git a/tests/_runtime/test_cached_stage.py b/tests/_runtime/test_cached_stage.pyindex e29afccab8..bdcb69a992 100644--- a/tests/_runtime/test_cached_stage.py+++ b/tests/_runtime/test_cached_stage.py@@ -127,10 +127,15 @@ class TestCachedLifecyclePreflight: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+ scope, pre-flight marks the producer stale (so it re-runs live rather+ than re-hitting the same unusable value) and raisesMarimoRescheduleError with cells_to_rerun populated, so run_all canrequeue the producer (plus this cell).++ Invalidation marks the manifest stale but must NOT destroy it: the+ producer's entry is not corrupt, it merely restored as a stub in this+ environment (e.g. an optional dep is absent). Destroying it would lose a+ recoverable hit if the producer's live rerun also fails."""from unittest.mock import MagicMock@@ -141,9 +146,6 @@ class TestCachedLifecyclePreflight: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(@@ -162,7 +164,9 @@ class TestCachedLifecyclePreflight:life._preflight_refs(cell, glbls) # type: ignore[arg-type]assert stale_calls == [producer_manifest]- assert clear_calls == [producer_manifest]+ # The producer's cache entry is preserved (not cleared) so a rerun that+ # itself fails leaves the recoverable hit intact.+ assert clear_calls == []assert {"producer", "consumer"} <= ei.value.cells_to_rerundef test_persistent_stub_producer_not_requeued_twice(self) -> None:@@ -366,6 +370,14 @@ class TestCachedLifecycleIntegration:differs and misses, B's pre-flight sees the stub in its refs →invalidates A and requeues. A re-runs with the real lambda; Bretries; `g == 15`.++ A bare lambda is `__main__`/`builtins.function` — not a marimo-owned+ stub — so the consumer routes it through the execution path and cannot+ reproduce the producer's key from the stub alone. Reschedule-recovery+ is the correct outcome here (the lambda is reconstructable by re-running+ A). The marimo-owned unpicklable case (a `persistent_cache` wrapper) is+ instead dequeued to zero contribution in `hash.py`, so its consumers+ stay content-addressed and hit without a reschedule."""k = caching_kernel.kproducer = exec_req.get(code="f = lambda x: x + 10")@@ -387,6 +399,49 @@ class TestCachedLifecycleIntegration:assert not isinstance(k.globals["f"], UnhashableStub)assert not isinstance(k.globals["g"], UnhashableStub)+ @requires_stub_loader+ async def test_serializable_sibling_ref_does_not_drag_producer_live(+ self,+ caching_kernel: MockedKernel,+ exec_req: ExecReqProvider,+ tracked_loaders: list[LazyLoader],+ ) -> None:+ """A producer defines a serializable value alongside an unpicklable one;+ a consumer that references ONLY the serializable value must not force the+ producer to re-run live.++ This is the invariant behind the KANNS export fix: split the UI labels+ (serializable strings) out from the callables (lambdas) so the UI cell+ references the labels. On restore the labels come back as a real value —+ no stub in the consumer's refs — so pre-flight never reschedules the+ producer, and its unpicklable def stays an inert stub. Proof that the+ producer was NOT dragged live: `fns` remains an UnhashableStub.+ """+ k = caching_kernel.k+ producer = exec_req.get(+ code="labels = ['a', 'b']; fns = [lambda: 1, lambda: 2]"+ )+ consumer = exec_req.get(code="n = len(labels)")++ await k.run([producer, consumer])+ assert k.globals["n"] == 2++ for loader in tracked_loaders:+ loader.flush()++ # Simulate fresh session.+ k.globals.pop("labels", None)+ k.globals.pop("fns", None)+ k.globals.pop("n", None)++ await k.run([producer, consumer])+ # Consumer still resolves from the serializable sibling.+ assert k.globals["n"] == 2+ # Producer was skipped (hit) and NOT rescheduled live: its unpicklable+ # def is still the inert stub, and its serializable def is a real list.+ assert isinstance(k.globals.get("fns"), UnhashableStub)+ assert k.globals.get("labels") == ["a", "b"]+# ---------------------------------------------------------------------------# Helpersdiff --git a/tests/_save/loaders/test_loader.py b/tests/_save/loaders/test_loader.pyindex 95d2f92219..37c71c04d4 100644--- a/tests/_save/loaders/test_loader.py+++ b/tests/_save/loaders/test_loader.py@@ -332,6 +332,53 @@ class TestLazyLoader(ABCTestLoader):assert isinstance(loaded.defs["f"], UnhashableStub)assert loaded.defs["f"].var_name == "f"+ def test_absent_module_blob_not_fetched(self) -> None:+ """A def blob whose type's root module can't be imported here is+ never fetched: restore stands in an `UnhashableStub` carrying the+ persisted content digest so a downstream consumer still reproduces+ its key without the (unmaterializable) value."""+ loader = self.instance()+ base = Path("test") / "absent_hash"+ # Reference a blob intentionally NOT written to the store — if the+ # gate fetched it, restore would miss on the absent blob.+ ref = (base / "t.pt").as_posix()+ manifest = msgspec.json.encode(+ CacheSchema(+ hash="absent_hash",+ cache_type=CacheType("Pure"),+ defs={+ "t": Item(+ reference=ref,+ type_hint="faketorch.Tensor",+ hash="deadbeef",+ )+ },+ stateful_refs=[],+ meta=Meta(version=MARIMO_CACHE_VERSION),+ )+ )+ cache_path = loader.build_path(key("absent_hash", "Pure"))+ self.store.put(str(cache_path), manifest)++ requested: list[str] = []+ original_get = self.store.get++ def spy(k: str):+ requested.append(k)+ return original_get(k)++ self.store.get = spy # type: ignore[method-assign]++ loaded = loader.load_cache(key("absent_hash", "Pure"))+ assert loaded is not None+ stub = loaded.defs["t"]+ assert isinstance(stub, UnhashableStub)+ assert stub.var_name == "t"+ assert stub.type_name == "faketorch.Tensor"+ assert stub.content_hash == "deadbeef"+ # The blob was skipped — only the manifest was fetched.+ assert ref not in requested+def test_unserializable_ui_clears_ui_defs_and_stale_blob(self) -> None:"""A UI def that can't be pickled must not leave `ui_defs` pointingat `ui.pickle`: restore loads UI defs via `ui_defs`, bypassing thediff --git a/tests/_save/stubs/test_cache_function_stub.py b/tests/_save/stubs/test_cache_function_stub.pynew file mode 100644index 0000000000..af2a671691--- /dev/null+++ b/tests/_save/stubs/test_cache_function_stub.py@@ -0,0 +1,163 @@+# Copyright 2026 Marimo. All rights reserved.+"""A `@mo.cache` / `@mo.persistent_cache` wrapper survives a cache save/restore+cycle as a *working* wrapper (not an inert tripwire), captured by `FunctionStub`+with `is_cached=True`.++On a cache hit the restored wrapper serves the wrapper's own persistent-cache+entries without re-importing the body's heavy dependencies (the motivating case+is a torch notebook exported to WASM). Only a genuine miss reaches the body.+"""++from __future__ import annotations++import ast+from pathlib import Path+from typing import Any++import marimo as mo+from marimo._ast.transformers import get_hashable_ast+from marimo._save.cache import Cache+from marimo._save.loaders.lazy import from_item, to_item+from marimo._save.stubs import FunctionStub+from marimo._save.stubs.lazy_stub import UnhashableStub++SKIP = {"cache", "persistent_cache"}+++def _cache() -> Cache:+ return Cache(+ defs={},+ hash="h",+ cache_type="Pure",+ stateful_refs=set(),+ hit=False,+ meta={},+ )+++def _as_notebook(wrapper: Any) -> Any:+ """Cell code runs as `__main__`; mimic that so the convert guard fires."""+ wrapper.__wrapped__.__module__ = "__main__"+ return wrapper+++def test_cache_call_converts_to_cached_stub() -> None:+ @mo.cache+ def add(a, b):+ return a + b++ stub = _cache()._convert_to_stub_if_needed(_as_notebook(add))+ assert isinstance(stub, FunctionStub)+ assert stub.is_cached+ assert stub.filename == "<add>"+ # The decorator line is captured so re-exec re-applies it.+ assert "@mo.cache" in stub.code+ assert "def add" in stub.code+++def test_async_cache_call_converts_to_cached_stub() -> None:+ @mo.cache+ async def afetch(a):+ return a++ stub = _cache()._convert_to_stub_if_needed(_as_notebook(afetch))+ assert isinstance(stub, FunctionStub)+ assert stub.is_cached+ assert "async def afetch" in stub.code+++def test_lambda_wrapper_not_converted() -> None:+ wrapper = _as_notebook(mo.cache(lambda x: x + 1))+ result = _cache()._convert_to_stub_if_needed(wrapper)+ assert not (isinstance(result, FunctionStub) and result.is_cached)+++def test_library_module_function_not_converted() -> None:+ # __module__ is the test module (not "__main__"): a library-owned cache+ # wrapper must not be captured as notebook source.+ @mo.cache+ def add(a, b):+ return a + b++ result = _cache()._convert_to_stub_if_needed(add)+ assert not (isinstance(result, FunctionStub) and result.is_cached)+++def test_manifest_round_trip() -> None:+ @mo.cache+ def add(a, b):+ return a + b++ stub = _cache()._convert_to_stub_if_needed(_as_notebook(add))+ item = to_item(Path("cache/add"), stub, var_name="add")+ # Inlined in the function field, carrying the is_cached flag.+ assert item.function == (stub.code, stub.filename, stub.lineno, True)+ assert item.reference is None++ back = from_item(item, "add")+ assert isinstance(back, FunctionStub)+ assert back.is_cached+ assert back.code == stub.code+ assert back.filename == "<add>"+++def test_load_rebuilds_working_wrapper() -> None:+ @mo.cache+ def add(a, b):+ return a + b++ stub = _cache()._convert_to_stub_if_needed(_as_notebook(add))+ rebuilt = stub.load({"mo": mo})++ # A live cache wrapper, not the stub.+ assert type(rebuilt).__name__ == "_cache_call"+ assert rebuilt(2, 3) == 5+ # Second identical call is served from the wrapper's own cache.+ assert rebuilt(2, 3) == 5+ assert rebuilt.cache_info().hits >= 1+++def test_restored_wrapper_hashes_to_same_ast() -> None:+ # The wrapper's own AST is re-hashed after restore to derive per-call keys.+ # The synthetic `<name>` filename + linecache registration must reproduce+ # the native hashable AST even though this function is not at line 1 of the+ # source file (a naive real-filename re-hash would read the wrong lines).+ @mo.persistent_cache(method="lazy")+ def compute(a, b):+ return a + b++ orig_ast = ast.dump(+ get_hashable_ast(compute.__wrapped__, skip_decorators=SKIP)+ )++ stub = FunctionStub(compute, is_cached=True)+ rebuilt = stub.load({"mo": mo})+ restored_ast = ast.dump(+ get_hashable_ast(rebuilt.__wrapped__, skip_decorators=SKIP)+ )++ assert restored_ast == orig_ast+++def test_body_ref_degraded_does_not_gate_rebuild() -> None:+ # The regression this design fixes: a cache wrapper resolves its body refs+ # at call time, so a degraded (unavailable) body ref must NOT block the+ # rebuild the way it (correctly) does for a plain function / class. The+ # is_cached flag keeps `_restore_deps` empty for the wrapper, so the+ # degraded-dep gate never fires.+ def heavy(a): # stands in for a torch-backed helper+ return a * 100++ @mo.cache+ def needy(a):+ return heavy(a)++ cache = _cache()+ stub = cache._convert_to_stub_if_needed(_as_notebook(needy))+ assert isinstance(stub, FunctionStub)+ assert stub.is_cached++ # No cross-def dependency gating for the wrapper.+ assert cache._restore_deps(stub) == set()+ scope = {"heavy": UnhashableStub(var_name="heavy")}+ assert cache._first_degraded_dep(stub, scope) is Nonediff --git a/tests/_save/stubs/test_module_stub.py b/tests/_save/stubs/test_module_stub.pyindex 0c6862794f..78d7aeefba 100644--- a/tests/_save/stubs/test_module_stub.py+++ b/tests/_save/stubs/test_module_stub.py@@ -14,6 +14,34 @@ if TYPE_CHECKING:from pathlib import Path+class TestModuleStubVersion:+ @staticmethod+ def test_submodule_alias_captures_root_version(+ monkeypatch: pytest.MonkeyPatch,+ ) -> None:+ """A submodule with no own `__version__` pins the root package's,+ so a version-pinned cache reproduces its hash on restore even when+ the package is absent (e.g. `import torch.nn as nn` in WASM)."""+ import types++ root = types.ModuleType("_marimo_pkg_ver_test")+ root.__version__ = "9.9.9"+ sub = types.ModuleType("_marimo_pkg_ver_test.sub") # no __version__+ monkeypatch.setitem(sys.modules, root.__name__, root)+ monkeypatch.setitem(sys.modules, sub.__name__, sub)++ assert ModuleStub(sub).version == "9.9.9"+ # An explicit version still wins over the fallback.+ assert ModuleStub(sub, version="1.2.3").version == "1.2.3"++ @staticmethod+ def test_no_version_anywhere_is_empty() -> None:+ import types++ mod = types.ModuleType("_marimo_no_ver_test")+ assert ModuleStub(mod).version == ""++class TestModuleStubLoad:@staticmethoddef test_load_existing_module() -> None: