Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

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__.py
index 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 SecretsCallbacks
from 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.py
index 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 request
from marimo._save.cache import CacheContext
diff --git a/marimo/_runtime/callbacks/protocol.py b/marimo/_runtime/callbacks/protocol.py
index 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.py
index 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 = False
if 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:
@staticmethod
def _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 UIElement
return 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_id
stub_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 checks
to force reruns and prevent recursive deadlocks.
"""
key = self._restored_keys.pop(cell_id, None)
@@ -314,7 +324,8 @@ class CachedLifecycle:
if key is None:
return
try:
- 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.py
index 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.py
index 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.py
index 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 = 5
CacheType = Literal[
"ContextExecutionPath",
@@ -166,9 +166,25 @@ class Cache:
memo: dict[int, Any] = {} # Track processed objects to handle cycles
for 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 at
definition 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 class
materialized 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.py
index 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__.py
index c603b7488e..2e2de7af7a 100644
--- a/marimo/_save/loaders/__init__.py
+++ b/marimo/_save/loaders/__init__.py
@@ -5,7 +5,11 @@ from dataclasses import dataclass
from typing import Literal
from 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.py
index 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 hashlib
import importlib
import inspect
import pickle
@@ -14,12 +15,18 @@ import msgspec
from marimo import _loggers
from 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, HashKey
from marimo._save.loaders.loader import BasePersistenceLoader
from 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 obj
if 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):
@classmethod
def 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_hint
else:
ref_vars[var_name] = item.reference
ref_type_hints[item.reference] = item.type_hint
@@ -456,7 +513,16 @@ class LazyLoader(BasePersistenceLoader):
# Distribute to defs
defs: 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] = digest
loader = 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 fallback
item.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 = None
item.unserializable_type = type_name
return False
diff --git a/marimo/_save/loaders/loader.py b/marimo/_save/loaders/loader.py
index 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.py
index 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.
+ return
try:
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 stub
diff --git a/marimo/_save/stubs/lazy_stub.py b/marimo/_save/stubs/lazy_stub.py
index 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_hash
if 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}>"
)
@staticmethod
diff --git a/marimo/_save/stubs/module_stub.py b/marimo/_save/stubs/module_stub.py
index 74fbc6afa7..8de0d09ec6 100644
--- a/marimo/_save/stubs/module_stub.py
+++ b/marimo/_save/stubs/module_stub.py
@@ -2,6 +2,7 @@
from __future__ import annotations
import importlib
+import sys
from types import ModuleType
from 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 = version
def load(self) -> Any:
"""Reload the module by name.
diff --git a/tests/_runtime/test_cached_stage.py b/tests/_runtime/test_cached_stage.py
index 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 raises
MarimoRescheduleError with cells_to_rerun populated, so run_all can
requeue 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_rerun
def 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; B
retries; `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.k
producer = 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"]
+
# ---------------------------------------------------------------------------
# Helpers
diff --git a/tests/_save/loaders/test_loader.py b/tests/_save/loaders/test_loader.py
index 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` pointing
at `ui.pickle`: restore loads UI defs via `ui_defs`, bypassing the
diff --git a/tests/_save/stubs/test_cache_function_stub.py b/tests/_save/stubs/test_cache_function_stub.py
new file mode 100644
index 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 None
diff --git a/tests/_save/stubs/test_module_stub.py b/tests/_save/stubs/test_module_stub.py
index 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:
@staticmethod
def test_load_existing_module() -> None: