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(save): stub serialization toolkit (class/lazy/module stubs) (#9896)
Dylan Madisetti6c7da04ddbb1
diff --git a/marimo/_runtime/exceptions.py b/marimo/_runtime/exceptions.pyindex fcb51f4cea..833b9e0cd2 100644--- a/marimo/_runtime/exceptions.py+++ b/marimo/_runtime/exceptions.py@@ -5,6 +5,7 @@ from typing import TYPE_CHECKINGif TYPE_CHECKING:from marimo._runtime.dataflow import DirectedGraph+ from marimo._types.ids import CellId_tclass MarimoRuntimeException(BaseException):@@ -26,6 +27,39 @@ class MarimoMissingRefError(BaseException):self.name_error = name_error+class MarimoCancelCellError(BaseException):+ """Soft-cancel signal raised by a lifecycle.++ Subclasses BaseException (not Exception) so user-code `except Exception`+ blocks don't swallow the control-flow signal.+ """++ cells_to_rerun: set[CellId_t]++ def __init__(+ self,+ *args: object,+ cells_to_rerun: set[CellId_t] | None = None,+ ) -> None:+ super().__init__(*args)+ self.cells_to_rerun = cells_to_rerun or set()+++class MarimoUnhashableCacheError(MarimoCancelCellError):+ """Raised when cell-level caching encounters a value that cannot be+ hashed/serialized for cache restoration."""++ def __init__(+ self,+ cells_to_rerun: set[CellId_t],+ variables: list[str],+ error_details: str,+ ) -> None:+ super().__init__(error_details, cells_to_rerun=cells_to_rerun)+ self.variables = variables+ self.error_details = error_details++def unwrap_user_exception(exc: MarimoRuntimeException,graph: DirectedGraph | None = None,diff --git a/marimo/_save/cache.py b/marimo/_save/cache.pyindex 26ceb8c12f..c07159bcfe 100644--- a/marimo/_save/cache.py+++ b/marimo/_save/cache.py@@ -4,6 +4,7 @@ from __future__ import annotationsimport abcimport inspectimport re+import textwrapfrom collections import namedtuplefrom dataclasses import dataclass, fieldfrom typing import TYPE_CHECKING, Any, Literal, get_args@@ -14,6 +15,7 @@ from marimo._runtime.context import ContextNotInitializedError, get_contextfrom marimo._runtime.state import SetFunctorfrom marimo._save.stubs import (CUSTOM_STUBS,+ ClassStub,CustomStub,FunctionStub,ModuleStub,@@ -21,6 +23,7 @@ from marimo._save.stubs import (UIElementStub,maybe_register_stub,)+from marimo._save.stubs.lazy_stub import UnhashableStub# Many assertions are for typing and should always pass. This message is a# catch all to motive users to report if something does fail.@@ -114,6 +117,24 @@ CacheInfo = namedtuple()+def _source_refs(code: str) -> set[Name]:+ """Free references of a captured class/function source block.++ Reuses the cell `ScopedVisitor` so the notion of "what this def needs"+ matches marimo's dataflow rather than a bespoke parser.+ """+ from marimo._ast.parse import ast_parse+ from marimo._ast.visitor import ScopedVisitor++ try:+ tree = ast_parse(textwrap.dedent(code))+ except SyntaxError:+ return set()+ visitor = ScopedVisitor("cache_restore")+ visitor.visit(tree)+ return set(visitor.refs)++# BaseException because "raise _ as e" is utilized.class CacheException(BaseException):pass@@ -136,7 +157,7 @@ class Cache:def restore(self, scope: dict[str, Any]) -> None:"""Restores values from cache, into scope."""memo: dict[int, Any] = {} # Track processed objects to handle cycles- for var, lookup in self.contextual_defs():+ 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@@ -167,6 +188,44 @@ class Cache:f"({type(ref)}:{ref}).")+ def _restore_deps(self, value: Any) -> set[Name]:+ """Cross-def names *value* needs before it can be restored.++ - A re-exec'd class/function needs the defs it references at+ definition time (bases, decorators, class-body calls).+ - A pickled instance of a cell-defined class needs that class+ materialized first (tagged via `requires`).+ """+ if isinstance(value, (ClassStub, FunctionStub)):+ return _source_refs(value.code)+ requires = getattr(value, "requires", "")+ return {requires} if requires else set()++ def _restore_order(+ self, contextual_defs: dict[tuple[Name, Name], Any]+ ) -> list[tuple[Name, Name]]:+ """Order `(var, lookup)` pairs so each def's cross-def dependencies+ restore first (depth-first; tolerant of cycles via `seen`)."""+ lookups = {var: lookup for var, lookup in contextual_defs}+ deps = {+ var: self._restore_deps(self.defs.get(var)) & lookups.keys()+ for var in lookups+ }+ order: list[tuple[Name, Name]] = []+ seen: set[Name] = set()++ def visit(var: Name) -> None:+ if var in seen:+ return+ seen.add(var)+ for dep in deps[var]:+ visit(dep)+ order.append((var, lookups[var]))++ for var in lookups:+ visit(var)+ return order+def _restore_from_stub_if_needed(self,value: Any,@@ -223,6 +282,16 @@ class Cache:result = valueelif isinstance(value, ReferenceStub):result = value.load(scope)+ elif isinstance(value, ClassStub):+ # Re-exec the captured source into the cell namespace so the+ # name rebinds to a live class (not the stub). Must run before+ # any pickle blob referencing the class deserializes, so the+ # class is resolvable as `__main__.<name>` in `scope`.+ result = value.load(scope)+ elif isinstance(value, UnhashableStub):+ # Marker for a def whose value couldn't be serialized. Place it+ # in scope as-is.+ result = valueelif isinstance(value, CustomStub):# CustomStub is a placeholder for a custom type, which cannot be# restored directly.@@ -315,8 +384,28 @@ class Cache:if inspect.ismodule(value):result = ModuleStub(value)- elif inspect.isfunction(value):+ elif (+ inspect.isfunction(value)+ and value.__name__ != "<lambda>"+ and getattr(value, "__module__", "__main__") == "__main__"+ ):+ # NB. Lambdas can't round-trip via FunctionStub: inspect.getsource+ # returns the line *containing* the lambda (e.g. "return model,+ # lambda inp: model(inp)"), which fails to compile as a module.result = FunctionStub(value)+ elif (+ inspect.isclass(value)+ and getattr(value, "__module__", None) == "__main__"+ ):+ # Attempt to capture classes by source so the loader can rebuild+ # them in the cell namespace before pickle blobs that reference them+ # deserialize. Pass the executing cell's source filename as a hint+ # so attribute-only classes (no method code object to read a+ # filename from) still resolve against `linecache`.+ try:+ result = ClassStub(value, filename=self._cell_filename())+ except (TypeError, OSError):+ result = valueelif isinstance(value, UIElement):result = UIElementStub(value)elif isinstance(value, tuple):@@ -397,6 +486,20 @@ class Cache:return result+ @staticmethod+ def _cell_filename() -> str | None:+ """Source filename of the executing cell, for sourcing classes that+ lack a method code object. `None` when there is no runtime context+ (e.g. script-mode / direct API use)."""+ try:+ from marimo._ast.compiler import get_filename++ context = get_context().execution_context+ assert context is not None+ return get_filename(context.cell_id)+ except (ContextNotInitializedError, AssertionError):+ return None+def contextual_defs(self) -> dict[tuple[Name, Name], Any]:"""Uses context to resolve private variable names."""try:diff --git a/marimo/_save/hash.py b/marimo/_save/hash.pyindex c657b0583b..68cfd625ff 100644--- a/marimo/_save/hash.py+++ b/marimo/_save/hash.py@@ -705,11 +705,13 @@ class BlockHasher:version = ""module = Noneif self.pin_modules:- module = sys.modules[imports[ref].module]- version = getattr(module, "__version__", "")+ # `.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)+ version = getattr(module, "__version__", "") or ""if not version:- module = sys.modules[imports[ref].namespace]- version = getattr(module, "__version__", "")+ module = sys.modules.get(imports[ref].namespace)+ version = getattr(module, "__version__", "") or ""content_serialization[ref] = type_sign(bytes(f"module:{ref}:{version}", "utf-8"), "module"@@ -1078,6 +1080,7 @@ def cache_attempt_from_hash(hasher.defs,hasher.key,hasher.stateful_refs,+ glbls=scope,)@@ -1166,4 +1169,5 @@ def content_cache_attempt_from_base(hasher.defs,hasher.key,stateful_refs,+ glbls=scope,)diff --git a/marimo/_save/loaders/lazy.py b/marimo/_save/loaders/lazy.pyindex 2a917118c2..0e2824f5d0 100644--- a/marimo/_save/loaders/lazy.py+++ b/marimo/_save/loaders/lazy.py@@ -1,6 +1,8 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations+import importlib+import inspectimport pickleimport queueimport threading@@ -19,6 +21,7 @@ from marimo._save.hash import HashKeyfrom marimo._save.loaders.loader import BasePersistenceLoaderfrom marimo._save.stores import FileStore, Storefrom marimo._save.stubs import (+ ClassStub,FunctionStub,ModuleStub,)@@ -61,6 +64,33 @@ def maybe_update_lazy_stub(value: Any) -> str:return loader+def _maybe_import_ref(value: Any) -> tuple[str, str] | None:+ """Return `(module, qualname)` if *value* is re-importable by name,+ else `None`.+ """+ if not (+ inspect.isclass(value)+ or inspect.isroutine(value)+ or type(value).__module__ == "typing"+ ):+ return None+ module = getattr(value, "__module__", None)+ qualname = (+ getattr(value, "__qualname__", None)+ or getattr(value, "__name__", None)+ or getattr(value, "_name", None)+ )+ if not module or module == "__main__" or not qualname:+ return None+ try:+ obj: Any = importlib.import_module(module)+ for part in qualname.split("."):+ obj = getattr(obj, part)+ except (ImportError, AttributeError):+ return None+ return (module, qualname) if obj is value else None++def to_item(path: Path,value: Any | None,@@ -77,20 +107,17 @@ def to_item(type_hint = f"{type(value).__module__}.{type(value).__name__}"if loader == "pickle":+ # A re-importable reference is stored inline rather than as a blob.+ ref = _maybe_import_ref(value)+ if ref is not None:+ return Item(import_ref=ref)+ if loader in ("pickle", "npy", "arrow", "pt"):+ # Blob strategies: the file extension is the loader name, matching+ # the path `save_cache` writes (`{var}.{loader}`). Listing them+ # together keeps a new format (e.g. `pt`) from silently falling+ # through to the `.pickle` fallback and mismatching its blob.return Item(- reference=(path / f"{var_name}.pickle").as_posix(),- hash=hash,- type_hint=type_hint,- )- if loader == "npy":- return Item(- reference=(path / f"{var_name}.npy").as_posix(),- hash=hash,- type_hint=type_hint,- )- if loader == "arrow":- return Item(- reference=(path / f"{var_name}.arrow").as_posix(),+ reference=(path / f"{var_name}.{loader}").as_posix(),hash=hash,type_hint=type_hint,)@@ -98,6 +125,8 @@ def to_item(return Item(reference=(path / "ui.pickle").as_posix())if isinstance(value, FunctionStub):return Item(function=value.dump())+ if isinstance(value, ClassStub):+ return Item(class_def=value.dump())if isinstance(value, ModuleStub):return Item(module=value.name)if isinstance(value, (int, str, float, bool, bytes, type(None))):@@ -119,10 +148,18 @@ def from_item(item: Item) -> Any:mod_stub = ModuleStub.__new__(ModuleStub)mod_stub.name = item.modulereturn mod_stub+ if item.import_ref is not None:+ module, qualname = item.import_ref+ obj: Any = importlib.import_module(module)+ for part in qualname.split("."):+ 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.functionreturn fn_stub+ if item.class_def is not None:+ return ClassStub.from_dump(item.class_def)if item.primitive is not None:return item.primitivereturn None@@ -148,7 +185,12 @@ class LazyLoader(BasePersistenceLoader):t.join()self._pending.clear()- def load_cache(self, key: HashKey) -> Cache | None:+ def load_cache(+ self,+ key: HashKey,+ glbls: dict[str, Any] | None = None,+ ) -> Cache | None:+ del glblstry:blob: bytes | None = self.store.get(str(self.build_path(key)))if not blob:@@ -166,12 +208,22 @@ class LazyLoader(BasePersistenceLoader):ref_vars: dict[str, str] = {}ref_type_hints: dict[str, str | None] = {}variable_hashes: dict[str, str] = {}+ # Instances of cell-defined (__main__) classes are deferred: their+ # class must be re-exec'd into __main__ before the blob can unpickle.+ # Cache.restore orders these after their class via `requires`.+ deferred: dict[str, tuple[str, str]] = {}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()elif item.reference is not None:- ref_vars[var_name] = item.reference- ref_type_hints[item.reference] = item.type_hint+ if item.type_hint and item.type_hint.startswith("__main__."):+ deferred[var_name] = (+ item.reference,+ item.type_hint.rsplit(".", 1)[-1],+ )+ else:+ ref_vars[var_name] = item.reference+ ref_type_hints[item.reference] = item.type_hintif item.hash:variable_hashes[var_name] = item.hash@@ -234,7 +286,20 @@ class LazyLoader(BasePersistenceLoader):# Distribute to defsdefs: dict[str, Any] = {}for var_name, item in cache_data.defs.items():- if var_name in ref_vars:+ if 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.+ raw = self.store.get(ref)+ if not raw:+ raise FileNotFoundError("Incomplete cache: missing blobs")+ stub = ImmediateReferenceStub(+ ReferenceStub(ref, hash_value=item.hash or "", blob=raw)+ )+ # Tag the cell class this instance needs materialized first.+ stub.requires = requires+ defs[var_name] = stub+ elif var_name in ref_vars:ref_key = ref_vars[var_name]val = unpickled.get(ref_key)if var_name in cache_data.ui_defs and isinstance(val, dict):@@ -291,18 +356,23 @@ class LazyLoader(BasePersistenceLoader):for var, obj in cache.defs.items():loader = maybe_update_lazy_stub(obj)- if loader == "ui":- ui_vars[var] = obj- ui_defs_list.append(var)- elif loader not in ("inline",):- format_vars.setdefault(loader, {})[var] = obj- defs_dict[var] = to_item(+ item = to_item(path,obj,var_name=var,loader=loader,hash=variable_hashes.get(var, ""),)+ defs_dict[var] = item+ if item.import_ref is not None:+ # Re-importable reference: lives inline in the manifest,+ # no blob to write.+ continue+ if loader == "ui":+ ui_vars[var] = obj+ ui_defs_list.append(var)+ elif loader not in ("inline",):+ format_vars.setdefault(loader, {})[var] = objmanifest = msgspec.json.encode(CacheSchema(diff --git a/marimo/_save/loaders/loader.py b/marimo/_save/loaders/loader.pyindex f323123039..79fad423ec 100644--- a/marimo/_save/loaders/loader.py+++ b/marimo/_save/loaders/loader.py@@ -122,9 +122,10 @@ class Loader(ABC):defs: set[Name],key: HashKey,stateful_refs: set[Name],+ glbls: dict[str, Any] | None = None,) -> Cache:start_time = time.time()- loaded = self.load_cache(key)+ loaded = self.load_cache(key, glbls=glbls)if not loaded:return Cache.empty(defs=defs, key=key, stateful_refs=stateful_refs)load_time = time.time() - start_time@@ -180,8 +181,14 @@ class Loader(ABC):"""@abstractmethod- def load_cache(self, key: HashKey) -> Cache | None:- """Load Cache"""+ def load_cache(+ self,+ key: HashKey,+ glbls: dict[str, Any] | None = None,+ ) -> Cache | None:+ """Load Cache. `glbls` is an optional cell namespace used by+ loaders (e.g. `LazyLoader`) that need to resolve+ `__main__`-qualified pickle refs against the live cell scope."""@abstractmethoddef save_cache(self, cache: Cache) -> bool:@@ -229,7 +236,12 @@ class BasePersistenceLoader(Loader):return Falsereturn self.store.put(str(self.build_path(cache.key)), blob)- def load_cache(self, key: HashKey) -> Cache | None:+ def load_cache(+ self,+ key: HashKey,+ glbls: dict[str, Any] | None = None,+ ) -> Cache | None:+ del glbls # Base persistence loader doesn't need a cell namespace.try:blob: bytes | None = self.store.get(str(self.build_path(key)))if not blob:diff --git a/marimo/_save/loaders/memory.py b/marimo/_save/loaders/memory.pyindex dd704a7c77..e38934ec8e 100644--- a/marimo/_save/loaders/memory.py+++ b/marimo/_save/loaders/memory.py@@ -56,7 +56,12 @@ class MemoryLoader(Loader):path = self.build_path(key)return self._maybe_lock(lambda: path in self._cache)- def load_cache(self, key: HashKey) -> Cache | None:+ def load_cache(+ self,+ key: HashKey,+ glbls: dict[str, Any] | None = None,+ ) -> Cache | None:+ del glbls # Memory loader doesn't need a cell namespace.if not self.cache_hit(key):return Nonepath = self.build_path(key)diff --git a/marimo/_save/stubs/__init__.py b/marimo/_save/stubs/__init__.pyindex d8b759b83b..6776bba76c 100644--- a/marimo/_save/stubs/__init__.py+++ b/marimo/_save/stubs/__init__.py@@ -5,6 +5,7 @@ from __future__ import annotationsfrom typing import TYPE_CHECKING, Any+from marimo._save.stubs.class_stub import ClassStubfrom marimo._save.stubs.function_stub import FunctionStubfrom marimo._save.stubs.lazy_stub import LAZY_STUB_LOOKUP, ReferenceStubfrom marimo._save.stubs.module_stub import ModuleStub@@ -77,6 +78,7 @@ def maybe_get_custom_stub(value: Any) -> CustomStub | None:__all__ = ["CUSTOM_STUBS","LAZY_STUB_LOOKUP",+ "ClassStub","CustomStub","FunctionStub","ModuleStub",diff --git a/marimo/_save/stubs/class_stub.py b/marimo/_save/stubs/class_stub.pynew file mode 100644index 0000000000..e1f0ecbbea--- /dev/null+++ b/marimo/_save/stubs/class_stub.py@@ -0,0 +1,147 @@+# Copyright 2026 Marimo. All rights reserved.+"""ClassStub — source-based serialization for cell-defined classes.++Pickle stores a class reference as `(__module__, __qualname__)`. For+classes defined inside marimo cells the module is `"__main__"`, and dynamicall+patched into the runtime.+"""++from __future__ import annotations++import inspect+import linecache+import textwrap+from typing import Any++__all__ = ["ClassStub"]+++class ClassStub:+ """Stub for class objects, storing the source code."""++ def __init__(self, cls: Any, filename: str | None = None) -> None:+ self.qualname = cls.__qualname__+ # Classes don't have their own `__code__`/`co_filename` like+ # functions do — they rely on `__module__` to find the source+ # file.+ method_code = self._find_code(target=cls)+ if method_code is None and filename is None:+ # Fallback: trust inspect.getsource. Raises if unsourcable.+ self.code = textwrap.dedent(inspect.getsource(cls))+ return++ filename = (+ method_code.co_filename if method_code is not None else filename+ )+ if filename is None:+ raise ValueError("No filename, invalid load")++ lines = linecache.getlines(filename)+ if not lines:+ raise OSError(+ f"No source available for {cls.__name__} in {filename!r}"+ )+ lineno = vars(cls).get("__firstlineno__")+ if lineno is None and method_code is not None:+ # Older Python (no `__firstlineno__`): anchor on the class's own+ # method, scanning upward from its line to the nearest enclosing+ # `class <name>` statement. Tying the lineno to a real code object+ # of *this* class avoids matching a same-named earlier (redefined)+ # class higher in the file.+ for idx in range(+ min(method_code.co_firstlineno, len(lines)) - 1, -1, -1+ ):+ if lines[idx].lstrip().startswith(f"class {cls.__name__}"):+ lineno = idx + 1+ break+ if lineno is None:+ # Last resort (no method code object): forward scan by name.+ for idx, line in enumerate(lines):+ if line.lstrip().startswith(f"class {cls.__name__}"):+ lineno = idx + 1+ break+ if lineno is None:+ raise OSError(+ f"Could not locate class {cls.__name__} in {filename!r}"+ )+ block = inspect.getblock(lines[lineno - 1 :])+ self.code = textwrap.dedent("".join(block))++ @staticmethod+ def _find_code(target: Any) -> Any:+ """Return a `__code__` object from a callable defined on *target*,+ or `None` if none is found (e.g. `type(...)`-built or attribute-only+ classes). Unwraps descriptor-wrapped callables — `staticmethod`,+ `classmethod`, and `property` — which don't expose `__code__`+ directly, so classes defining only those still resolve a filename."""+ for attr in vars(target).values():+ code = getattr(attr, "__code__", None)+ if code is None:+ func = getattr(attr, "__func__", None) or getattr(+ attr, "fget", None+ )+ code = getattr(func, "__code__", None)+ if code is not None:+ return code+ return None++ def load(self, glbls: dict[str, Any]) -> Any:+ """Reconstruct the class by executing its source in *glbls*.++ The filename is derived from the loading cell (see+ `_load_filename`); `linecache` is seeded under that class-specific+ key so tracebacks render the source without clobbering the cell's+ own entry.+ """+ bare_name = self.qualname.rsplit(".", 1)[-1]+ filename = self._load_filename(bare_name)+ linecache.cache[filename] = (+ len(self.code),+ None,+ [line + "\n" for line in self.code.splitlines()],+ filename,+ )+ # Exec into glbls directly so the class lands in the cell namespace+ # under its bare name. (No lcls dict — top-level class statements+ # must execute against glbls for cross-cell references to bind.)+ #+ # On a cache hit glbls is the cell namespace, i.e.+ # `sys.modules["__main__"].__dict__`, so this also registers the+ # class as `__main__.<name>` — which is exactly what `pickle.loads`+ # uses to resolve instances of it (no custom unpickler needed).+ exec(compile(self.code, filename, "exec"), glbls)+ return glbls.get(bare_name)++ @staticmethod+ def _load_filename(bare_name: str) -> str:+ """Filename for compiling the class source: the *loading* cell's+ file when a kernel context exists, else a synthetic name. Suffixed+ by the class name so seeding `linecache` does not overwrite the+ cell's own source entry."""+ try:+ from marimo._ast.compiler import get_filename+ from marimo._runtime.context import (+ ContextNotInitializedError,+ get_context,+ )++ ctx = get_context().execution_context+ if ctx is not None:+ return get_filename(ctx.cell_id, suffix=bare_name)+ except (ContextNotInitializedError, AssertionError):+ pass+ return f"<{bare_name}>"++ def dump(self) -> tuple[str, str]:+ """Dump source + qualname for lazy serialization."""+ return self.code, self.qualname++ @classmethod+ def from_dump(cls, dump: tuple[str, str]) -> ClassStub:+ """Reconstruct a `ClassStub` from a `dump()` tuple.++ Skips `__init__` (which requires a live class to introspect).+ """+ stub = cls.__new__(cls)+ stub.code, stub.qualname = dump+ return stubdiff --git a/marimo/_save/stubs/lazy_stub.py b/marimo/_save/stubs/lazy_stub.pyindex c64b2d3974..a6f3348ac2 100644--- a/marimo/_save/stubs/lazy_stub.py+++ b/marimo/_save/stubs/lazy_stub.py@@ -17,6 +17,8 @@ from marimo._save.stubs.stubs import CustomStubif TYPE_CHECKING:from collections.abc import Callable+ from marimo._runtime.exceptions import MarimoUnhashableCacheError+class CacheType(Enum):CONTEXT_EXECUTION_PATH = "ContextExecutionPath"@@ -36,8 +38,16 @@ class Item(msgspec.Struct):primitive: Any | None = Nonereference: str | None = Nonemodule: str | None = None+ # (module, qualname) of a value re-importable by name — e.g.+ # `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, qualname) — cell-defined class source. Materialized into the+ # cell namespace (and __main__) before pickle blobs deserialize, so+ # __main__-qualified instances can resolve their type.+ class_def: tuple[str, str] | None = Nonehash: str | None = None# Fully-qualified class name of the original value — used by format-aware# deserializers (e.g. to distinguish pandas from polars Arrow blobs).@@ -50,7 +60,9 @@ class Item(msgspec.Struct):self.primitive,self.reference,self.module,+ self.import_ref,self.function,+ self.class_def,]if field is not None)@@ -87,14 +99,18 @@ class Cache(msgspec.Struct):# "pickle" — per-variable .pickle blob (default fallback)# "npy" — numpy .npy blob# "arrow" — Arrow IPC .arrow blob (polars and pandas)+# "pt" — torch .pt blob (torch.save / torch.load)LAZY_STUB_LOOKUP: dict[str, str] = {"builtins.int": "inline","builtins.str": "inline","builtins.float": "inline","builtins.bool": "inline",- "builtins.bytes": "inline",+ # bytes can't round-trip through JSON (msgspec encodes as base64+ # but decodes back as str with Any type). Use pickle instead.+ "builtins.bytes": "pickle","builtins.NoneType": "inline","marimo._save.stubs.function_stub.FunctionStub": "inline",+ "marimo._save.stubs.class_stub.ClassStub": "inline","marimo._save.stubs.module_stub.ModuleStub": "inline","marimo._save.stubs.ui_element_stub.UIElementStub": "ui",# Optional third-party types — imported lazily only when encountered:@@ -106,6 +122,9 @@ LAZY_STUB_LOOKUP: dict[str, str] = {"pandas.core.frame.DataFrame": "arrow","pandas.Series": "arrow","pandas.core.series.Series": "arrow",+ # Subclasses (e.g. torch.nn.Parameter) resolve here through the MRO+ # walk in maybe_update_lazy_stub; torch.save round-trips them intact.+ "torch.Tensor": "pt",}# Runtime cache: type → loader string, populated by maybe_update_lazy_stub().@@ -150,6 +169,17 @@ def _arrow_load(data: bytes, type_hint: str | None = None) -> Any:return result+def _pt_load(data: bytes, type_hint: str | None = None) -> Any:+ DependencyManager.torch.require("to load cached torch tensors.")+ import torch # type: ignore[import-not-found]++ del type_hint+ # weights_only restricts unpickling to tensor payloads; a tensor saved+ # on an unavailable device fails loudly here, and the cache falls back+ # to recomputation rather than silently relocating the value.+ return torch.load(io.BytesIO(data), weights_only=True)++def _pickle_load(data: bytes, type_hint: str | None = None) -> Any:del type_hintreturn pickle.loads(data)@@ -159,6 +189,7 @@ BLOB_DESERIALIZERS: dict[str, Callable[[bytes, str | None], Any]] = {".pickle": _pickle_load,".npy": _npy_load,".arrow": _arrow_load,+ ".pt": _pt_load,}# ---------------------------------------------------------------------------@@ -198,10 +229,20 @@ def _arrow_dump(obj: Any) -> bytes:return buf.getvalue()+def _pt_dump(obj: Any) -> bytes:+ DependencyManager.torch.require("to dump torch tensors.")+ import torch # type: ignore[import-not-found]++ buf = io.BytesIO()+ torch.save(obj, buf)+ return buf.getvalue()++BLOB_SERIALIZERS: dict[str, Callable[[Any], bytes]] = {"pickle": pickle.dumps,"npy": _npy_dump,"arrow": _arrow_dump,+ "pt": _pt_dump,}# ---------------------------------------------------------------------------@@ -213,11 +254,19 @@ class ReferenceStub:"""Deferred blob reference — loads from store on access."""def __init__(- self, name: str, loader: str | None = None, hash_value: str = ""+ self,+ name: str,+ loader: str | None = None,+ hash_value: str = "",+ blob: bytes | None = None,) -> None:self.name = nameself.loader = loaderself.hash = hash_value+ # Preloaded bytes — set when the caller has already read the blob+ # (e.g. the lazy loader, which uses its own store) and only the+ # deserialization is being deferred.+ self._blob = blobdef load(self, glbls: dict[str, Any]) -> Any:del glbls@@ -227,6 +276,8 @@ class ReferenceStub:return pickle.loads(blob)def to_bytes(self) -> bytes:+ if self._blob is not None:+ return self._blobmaybe_bytes = get_store().get(self.name)return maybe_bytes if maybe_bytes else b""@@ -236,6 +287,10 @@ class ImmediateReferenceStub(CustomStub):def __init__(self, reference: ReferenceStub) -> None:self.reference = reference+ # Name of a cell-defined class this value's type needs materialized+ # before it can unpickle; empty when there's no such dependency.+ # Consumed by `Cache.restore` for dependency ordering.+ self.requires: str = ""def load(self, glbls: dict[str, Any]) -> Any:return self.reference.load(glbls)@@ -246,3 +301,99 @@ class ImmediateReferenceStub(CustomStub):def to_bytes(self) -> bytes:return self.reference.to_bytes()+++class UnhashableStub(CustomStub):+ """Marker + tripwire for a def that could not be serialized for caching.++ Written to the cache as a placeholder when per-def pickling fails (e.g.+ a lambda, a closure over an unpicklable object). The marker is placed+ in scope as-is by `Cache.restore` (no `.load()` call). It is+ harmless when the consumer cell never touches it; any meaningful access+ (call) raises `MarimoUnhashableCacheError` carrying+ `variables=[var_name]` so the runner can identify the defining cell,+ invalidate its manifest, and re-queue.++ Detection happens at use-site, not at pre-execution. Bodies that don't+ touch the stub run normally; closure-captured stubs surface through+ whichever access the user code performs.++ UnhashableStub is created on-demand by the loader and is not+ registered in CUSTOM_STUBS — `get_type()` raises since no specific+ value type maps to it.++ `__marimo_unhashable__` is a class-level protocol marker: runtime+ consumers (e.g. a cached-execution pre-flight) detect stubs through+ the attribute rather than importing this class, keeping the runtime+ and serialization layers independently mergeable.+ """++ __marimo_unhashable__ = True++ __slots__ = ("error_msg", "type_name", "var_name")++ def __init__(+ self,+ _obj: Any = None,+ var_name: str = "",+ error_msg: str = "",+ ) -> None:+ self.var_name = var_name+ if _obj is not None:+ value_type = type(_obj)+ self.type_name = (+ f"{getattr(value_type, '__module__', '<unknown>')}."+ f"{getattr(value_type, '__name__', '<unknown>')}"+ )+ else:+ self.type_name = "<unknown>"+ self.error_msg = error_msg or "value could not be pickled for cache"++ def _trip(self) -> MarimoUnhashableCacheError:+ from marimo._runtime.exceptions import MarimoUnhashableCacheError++ return MarimoUnhashableCacheError(+ cells_to_rerun=set(),+ variables=[self.var_name] if self.var_name else [],+ error_details=(+ f"{self.var_name} ({self.type_name}): {self.error_msg}"+ if self.var_name+ else f"({self.type_name}): {self.error_msg}"+ ),+ )++ def load(self, glbls: dict[str, Any]) -> Any:+ del glbls+ raise self._trip()++ # __call__ is the only tripwire: it covers the canonical user-code+ # use pattern (`classic(x)`, `foo()` where foo's closure captures+ # the stub) that produces `'UnhashableStub' object is not callable`.+ # Other dunders (__getattr__, __getitem__, __iter__, __len__, …)+ # deliberately fall through to Python defaults so framework probes+ # (`getattr(value, "_repr_mimebundle_", None)`, isinstance, hasattr,+ # storage-engine introspection, etc.) stay inert. A body that uses+ # the stub through a non-call access raises a generic TypeError+ # instead of the cleaner trip — acceptable trade-off; the alternative+ # over-trips on framework probes and cancels innocent cells.+ def __call__(self, *args: Any, **kwargs: Any) -> Any:+ del args, kwargs+ raise self._trip()++ def __repr__(self) -> str:+ return (+ f"<UnhashableStub var_name={self.var_name!r} "+ f"type={self.type_name!r}>"+ )++ @staticmethod+ def get_type() -> type:+ # UnhashableStub does not correspond to a specific value type — it's+ # written on-demand by the loader when pickling fails. Not registered+ # in CUSTOM_STUBS.+ raise NotImplementedError(+ "UnhashableStub is not registered for a specific type"+ )++ def to_bytes(self) -> bytes:+ return pickle.dumps(self)diff --git a/marimo/_save/stubs/module_stub.py b/marimo/_save/stubs/module_stub.pyindex caa04e34d0..a58bf6ddd9 100644--- a/marimo/_save/stubs/module_stub.py+++ b/marimo/_save/stubs/module_stub.py@@ -2,9 +2,33 @@from __future__ import annotationsimport importlib+from types import ModuleTypefrom typing import Any-__all__ = ["ModuleStub"]+__all__ = ["MissingModule", "ModuleStub"]+++class MissingModule(ModuleType):+ """Placeholder for a cached module def that is unimportable here.++ Enables loading a cache lazily until a module is actually needed.+ """++ def __init__(self, name: str) -> None:+ super().__init__(name)+ self.__missing__ = True++ def __getattr__(self, attr: str) -> Any:+ if attr.startswith("__") and attr.endswith("__"):+ # Dunder probes — pickling machinery, repr, and+ # getattr-with-default version lookups — must fall back+ # rather than propagate an import error.+ raise AttributeError(attr)+ raise ModuleNotFoundError(+ f"No module named {self.__name__!r} in this environment "+ f"(cached def restored lazily; accessing "+ f"{self.__name__}.{attr} requires the real module)"+ )class ModuleStub:@@ -15,5 +39,22 @@ class ModuleStub:self.hash = hashdef load(self) -> Any:- """Reload the module by name."""- return importlib.import_module(self.name)+ """Reload the module by name.++ Falls back to a `MissingModule` placeholder when the module itself+ is absent, so restoration succeeds and the error surfaces only on+ actual use. A `ModuleNotFoundError` for a *different* module — i.e.+ a transitive import the module performs internally — is re-raised+ rather than masked as "this module is missing".+ """+ try:+ return importlib.import_module(self.name)+ except ModuleNotFoundError as e:+ missing = getattr(e, "name", None)+ if (+ missing is None+ or missing == self.name+ or self.name.startswith(f"{missing}.")+ ):+ return MissingModule(self.name)+ raisediff --git a/tests/_save/loaders/mocks.py b/tests/_save/loaders/mocks.pyindex 37a6b6ccf3..895205a322 100644--- a/tests/_save/loaders/mocks.py+++ b/tests/_save/loaders/mocks.py@@ -31,7 +31,8 @@ class MockLoader(Loader):def cache_hit(self, _) -> bool:return self._cache_hit- def load_cache(self, key) -> Cache | None:+ def load_cache(self, key, glbls=None) -> Cache | None:+ del glblsif not self._cache_hit:return Noneself._loaded = Truediff --git a/tests/_save/loaders/test_class_roundtrip.py b/tests/_save/loaders/test_class_roundtrip.pynew file mode 100644index 0000000000..3e047bc8b6--- /dev/null+++ b/tests/_save/loaders/test_class_roundtrip.py@@ -0,0 +1,122 @@+# Copyright 2026 Marimo. All rights reserved.+"""End-to-end: a cell-defined class survives a cache save/restore cycle as+a usable class (not a leftover ClassStub) through both the pickle and lazy+loaders.++This is the behavior behind `with mo.persistent_cache(...): class Foo: ...`+— on a cache hit the second run must restore `Foo` as a real class so+`Foo()` / `isinstance(..., Foo)` work.+"""++from __future__ import annotations++import linecache+from typing import Any++import pytest++from marimo._save.cache import Cache+from marimo._save.loaders import LazyLoader, PickleLoader+from marimo._save.stores.file import FileStore++CELL_FILENAME = "__marimo__cell_RtRt_.py"++# Source for a fake marimo cell defining three flavors of class.+CELL_SRC = (+ "class WithMethod:\n"+ " def __init__(self, v: int = 0) -> None:\n"+ " self.v = v\n"+ "\n"+ " def doubled(self) -> int:\n"+ " return self.v * 2\n"+ "\n"+ "class OnlyStatic:\n"+ " @staticmethod\n"+ " def f() -> int:\n"+ " return 7\n"+ "\n"+ "class JustAttrs:\n"+ " x = 1\n"+)+++def cell_namespace() -> dict[str, Any]:+ linecache.cache[CELL_FILENAME] = (+ len(CELL_SRC),+ None,+ [line + "\n" for line in CELL_SRC.splitlines()],+ CELL_FILENAME,+ )+ glbls: dict[str, Any] = {"__name__": "__main__"}+ exec(compile(CELL_SRC, CELL_FILENAME, "exec"), glbls)+ yield glbls+ linecache.cache.pop(CELL_FILENAME, None)+++def _make_loader(kind: str, save_path: str):+ store = FileStore(save_path=save_path)+ if kind == "pickle":+ return PickleLoader("test", store=store)+ return LazyLoader("test", store=store)+++def _round_trip(loader: Any, cache: Cache) -> Cache:+ """Persist `cache` through `loader` and read it back."""+ if isinstance(loader, PickleLoader):+ blob = loader.to_blob(cache)+ return loader.restore_cache(cache.key, blob)+ # LazyLoader writes blobs on a background thread.+ assert loader.save_cache(cache)+ loader.flush()+ loaded = loader.load_cache(cache.key)+ assert loaded is not None+ return loaded++[email protected]("kind", ["pickle", "lazy"])[email protected]("var", ["WithMethod", "OnlyStatic", "JustAttrs"])+def test_class_round_trip(+ kind: str,+ var: str,+ cell_namespace: dict[str, Any],+ tmp_path: Any,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ cls = cell_namespace[var]+ # Simulate the runtime context's cell filename so attribute-only+ # classes (no method code object) source from linecache.+ monkeypatch.setattr(+ Cache, "_cell_filename", staticmethod(lambda: CELL_FILENAME)+ )++ cache = Cache(+ defs={var: cls},+ hash="classhash",+ cache_type="Pure",+ stateful_refs=set(),+ hit=False,+ meta={},+ )+ cache.update({var: cls})+ # The class was converted to a ClassStub for serialization.+ from marimo._save.stubs import ClassStub++ assert isinstance(cache.defs[var], ClassStub)++ loader = _make_loader(kind, str(tmp_path))+ loaded = _round_trip(loader, cache)++ scope: dict[str, Any] = {"__name__": "__main__"}+ loaded.restore(scope)++ restored = scope[var]+ assert isinstance(restored, type), (+ f"{var} restored as {type(restored)}, expected a class"+ )+ if var == "WithMethod":+ assert restored(5).doubled() == 10+ elif var == "OnlyStatic":+ assert restored.f() == 7+ else:+ assert restored.x == 1diff --git a/tests/_save/loaders/test_loader.py b/tests/_save/loaders/test_loader.pyindex cde916b69e..4310089e97 100644--- a/tests/_save/loaders/test_loader.py+++ b/tests/_save/loaders/test_loader.py@@ -256,6 +256,39 @@ class TestLazyLoader(ABCTestLoader):assert loaded.defs["y"] == "hello"assert loaded.defs["z"] == [1, 2, 3]+ def test_import_reference_stays_inline(self) -> None:+ """Re-importable references (`from typing import Optional`, an+ imported function/class) are stored inline in the manifest, not as+ per-variable blobs, and restore to the original object by identity."""+ from collections import OrderedDict+ from typing import Optional++ loader = self.instance()+ cache = Cache(+ defs={"Optional": Optional, "OrderedDict": OrderedDict},+ hash="import_ref_hash",+ cache_type="Pure",+ stateful_refs=set(),+ hit=False,+ meta={"version": MARIMO_CACHE_VERSION},+ )+ cache.update({"Optional": Optional, "OrderedDict": OrderedDict})+ assert loader.save_cache(cache)+ loader.flush()++ # No blob files — only the manifest is written.+ blobs = [+ p+ for p in Path(self.store.save_path).rglob("*")+ if p.is_file() and p.suffix != ".jsonl"+ ]+ assert not blobs, f"expected no blobs, found {blobs}"++ loaded = loader.load_cache(key("import_ref_hash", "Pure"))+ assert loaded is not None+ assert loaded.defs["Optional"] is Optional+ assert loaded.defs["OrderedDict"] is OrderedDict+def test_corrupt_cache_returns_none(self) -> None:"""Corrupt manifest triggers cache miss, not crash."""loader = self.instance()@@ -339,6 +372,34 @@ class TestLazyLoader(ABCTestLoader):assert loaded is not Nonenp.testing.assert_array_equal(loaded.defs["arr"], arr)+ @pytest.mark.skipif(+ not DependencyManager.has("torch"), reason="torch required"+ )+ def test_torch_round_trip(self) -> None:+ """torch tensors survive save → flush → load via the .pt format —+ the manifest reference must match the blob extension."""+ import torch++ loader = self.instance()+ tensor = torch.tensor([1.0, 2.0, 3.0])+ cache = Cache(+ defs={"t": tensor},+ hash="pt_hash",+ cache_type="Pure",+ stateful_refs=set(),+ hit=False,+ meta={"version": MARIMO_CACHE_VERSION},+ )+ assert loader.save_cache(cache)+ loader.flush()++ assert list(Path(self.store.save_path).rglob("*.pt")), (+ "expected .pt blob, got pickle fallback"+ )+ loaded = loader.load_cache(key("pt_hash", "Pure"))+ assert loaded is not None+ assert torch.equal(loaded.defs["t"], tensor)+@pytest.mark.skipif(not DependencyManager.has("polars"), reason="polars required")diff --git a/tests/_save/stubs/test_class_stub.py b/tests/_save/stubs/test_class_stub.pynew file mode 100644index 0000000000..be123815e5--- /dev/null+++ b/tests/_save/stubs/test_class_stub.py@@ -0,0 +1,203 @@+# Copyright 2026 Marimo. All rights reserved.+"""Tests for ClassStub — source-based serialization of cell-defined classes."""++from __future__ import annotations++import linecache+import sys+import tempfile+import textwrap+from pathlib import Path+from typing import Any++import pytest++from marimo._save.stubs.class_stub import ClassStub+++class TestClassStubBasics:+ @staticmethod+ def test_load_populates_glbls() -> None:+ """ClassStub.load returns the class AND leaves it in glbls+ so subsequent pickle deserialization can find it."""+ # Build a ClassStub by hand from a known dump.+ code = textwrap.dedent(+ """+ class Bar:+ value = 42+ """+ )+ stub = ClassStub.from_dump((code, "Bar"))+ glbls: dict[str, Any] = {"__name__": "__main__"}+ cls = stub.load(glbls)+ assert cls is not None+ assert cls.__name__ == "Bar"+ assert glbls["Bar"] is cls+ assert cls.value == 42++ @staticmethod+ def test_load_seeds_linecache_for_traceback() -> None:+ """Outside a kernel context, load compiles under a synthetic+ per-class filename and seeds linecache so tracebacks render the+ class source."""+ code = textwrap.dedent(+ """+ class Baz:+ def hello(self) -> str:+ return "hi"+ """+ )+ synth_name = "<Baz>"+ linecache.cache.pop(synth_name, None)+ stub = ClassStub.from_dump((code, "Baz"))+ glbls: dict[str, Any] = {"__name__": "__main__"}+ stub.load(glbls)+ assert synth_name in linecache.cache+ assert glbls["Baz"]().hello() == "hi"+++class TestClassStubFromLiveClass:+ @staticmethod+ def test_from_live_class_in_temp_module() -> None:+ """End-to-end: take a live class from a temp module, ClassStub it,+ round-trip through dump/from_dump, and verify the class works."""+ src = textwrap.dedent(+ """+ class Widget:+ def __init__(self, n: int) -> None:+ self.n = n++ def squared(self) -> int:+ return self.n * self.n+ """+ )+ with tempfile.NamedTemporaryFile("w", suffix=".py", delete=False) as f:+ f.write(src)+ tmp_path = f.name+ module_name = "_test_class_stub_live"+ try:+ module = type(sys)(module_name)+ module.__file__ = tmp_path+ sys.modules[module_name] = module+ # Populate linecache so inspect.getsource works.+ linecache.cache[tmp_path] = (+ len(src),+ None,+ [line + "\n" for line in src.splitlines()],+ tmp_path,+ )+ exec(compile(src, tmp_path, "exec"), module.__dict__)+ cls = module.Widget++ stub = ClassStub(cls)+ dump = stub.dump()+ assert "class Widget" in dump[0]++ # Reload in a vacuum.+ fresh_stub = ClassStub.from_dump(dump)+ fresh_glbls: dict[str, Any] = {"__name__": "__main__"}+ fresh_stub.load(fresh_glbls)+ assert fresh_glbls["Widget"](5).squared() == 25+ finally:+ sys.modules.pop(module_name, None)+ linecache.cache.pop(tmp_path, None)+ Path(tmp_path).unlink(missing_ok=True)+++class TestClassStubSourceResolution:+ """Filename/lineno resolution for awkward cell-defined classes."""++ @staticmethod+ def _seed_cell(src: str) -> tuple[str, dict[str, Any]]:+ """Compile `src` under a fake cell filename, registering it in+ linecache the way marimo's compiler does, and return+ (filename, namespace)."""+ filename = "__marimo__cell_TeSt_.py"+ linecache.cache[filename] = (+ len(src),+ None,+ [line + "\n" for line in src.splitlines()],+ filename,+ )+ glbls: dict[str, Any] = {"__name__": "__main__"}+ exec(compile(src, filename, "exec"), glbls)+ return filename, glbls++ def test_redefined_class_captures_live_definition(self) -> None:+ """When a class name is defined twice, the stub must capture the+ live (latest) definition's source, not a stale earlier one."""+ src = textwrap.dedent(+ """+ class Dup:+ def tag(self) -> str:+ return "old"++ class Dup:+ def tag(self) -> str:+ return "new"+ """+ ).strip()+ filename, glbls = self._seed_cell(src)+ try:+ stub = ClassStub(glbls["Dup"], filename=filename)+ assert '"new"' in stub.code+ assert '"old"' not in stub.code+ fresh: dict[str, Any] = {"__name__": "__main__"}+ assert stub.load(fresh)().tag() == "new"+ finally:+ linecache.cache.pop(filename, None)++ def test_staticmethod_only_class_resolves(self) -> None:+ """A class whose only callable is a staticmethod has no plain+ method `__code__`; the stub must unwrap the descriptor to find+ the source filename."""+ src = textwrap.dedent(+ """+ class OnlyStatic:+ @staticmethod+ def f() -> int:+ return 7+ """+ ).strip()+ filename, glbls = self._seed_cell(src)+ try:+ stub = ClassStub(glbls["OnlyStatic"], filename=filename)+ assert "class OnlyStatic" in stub.code+ fresh: dict[str, Any] = {"__name__": "__main__"}+ assert stub.load(fresh).f() == 7+ finally:+ linecache.cache.pop(filename, None)++ def test_attribute_only_class_resolves_with_hint(self) -> None:+ """A body-only class (no callables at all) has no code object to+ read a filename from; the cache layer's filename hint lets it+ source from linecache anyway."""+ src = textwrap.dedent(+ """+ class JustAttrs:+ x = 1+ y = 2+ """+ ).strip()+ filename, glbls = self._seed_cell(src)+ try:+ stub = ClassStub(glbls["JustAttrs"], filename=filename)+ fresh: dict[str, Any] = {"__name__": "__main__"}+ restored = stub.load(fresh)+ assert restored.x == 1+ assert restored.y == 2+ finally:+ linecache.cache.pop(filename, None)+++class TestClassStubFailures:+ @staticmethod+ def test_unsourcable_class_raises_on_init() -> None:+ """A class with no discoverable source (e.g. built via type())+ cannot be ClassStub'd. The error must surface at construction+ time so the save path can fall back to UnhashableStub before+ writing a corrupt blob."""+ # type(...) classes have no source file inspect can find.+ DynCls = type("DynCls", (), {"x": 1})+ with pytest.raises((TypeError, OSError)):+ ClassStub(DynCls)diff --git a/tests/_save/stubs/test_module_stub.py b/tests/_save/stubs/test_module_stub.pynew file mode 100644index 0000000000..423c4b9ac6--- /dev/null+++ b/tests/_save/stubs/test_module_stub.py@@ -0,0 +1,64 @@+# Copyright 2026 Marimo. All rights reserved.+"""Tests for ModuleStub — name-based serialization of module objects."""++from __future__ import annotations++import sys+from typing import TYPE_CHECKING++import pytest++from marimo._save.stubs.module_stub import MissingModule, ModuleStub++if TYPE_CHECKING:+ from pathlib import Path+++class TestModuleStubLoad:+ @staticmethod+ def test_load_existing_module() -> None:+ """An importable module is returned as the real module."""+ import json++ stub = ModuleStub(json)+ assert stub.load() is json++ @staticmethod+ def test_missing_module_returns_placeholder() -> None:+ """A module absent from this environment restores to a+ MissingModule placeholder rather than raising."""+ stub = ModuleStub.__new__(ModuleStub)+ stub.name = "marimo_definitely_not_a_real_module_xyz"+ stub.hash = ""+ result = stub.load()+ assert isinstance(result, MissingModule)+ assert result.__missing__ is True+ # Accessing an attribute surfaces the deferred import error.+ with pytest.raises(ModuleNotFoundError):+ _ = result.some_attr++ @staticmethod+ def test_transitive_import_failure_reraises(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ """A module that *exists* but fails on an internal import of a+ different missing module must NOT be masked as "this module is+ missing" — the real ModuleNotFoundError is re-raised."""+ mod_name = "_marimo_transitive_stub_test"+ (tmp_path / f"{mod_name}.py").write_text(+ "import a_module_that_truly_does_not_exist_zzz\n"+ )+ monkeypatch.syspath_prepend(str(tmp_path))+ sys.modules.pop(mod_name, None)+ try:+ stub = ModuleStub.__new__(ModuleStub)+ stub.name = mod_name+ stub.hash = ""+ with pytest.raises(ModuleNotFoundError) as exc_info:+ stub.load()+ # The error is about the transitive dep, not our module.+ assert (+ exc_info.value.name == "a_module_that_truly_does_not_exist_zzz"+ )+ finally:+ sys.modules.pop(mod_name, None)diff --git a/tests/_save/stubs/test_unhashable_stub.py b/tests/_save/stubs/test_unhashable_stub.pynew file mode 100644index 0000000000..d1df7acb12--- /dev/null+++ b/tests/_save/stubs/test_unhashable_stub.py@@ -0,0 +1,162 @@+# Copyright 2026 Marimo. All rights reserved.+"""UnhashableStub semantics: data, tripwire, and Cache.restore handling.++Split from the cached-lifecycle suite: these tests exercise only the+stub serialization toolkit (no runtime lifecycle involvement).+"""++from __future__ import annotations++import pickle++import pytest++from marimo._runtime.exceptions import (+ MarimoCancelCellError,+ MarimoUnhashableCacheError,+)+from marimo._save.cache import Cache+from marimo._save.stubs.lazy_stub import UnhashableStub++# ---------------------------------------------------------------------------+# UnhashableStub: data + tripwire semantics+# ---------------------------------------------------------------------------+++class TestUnhashableStub:+ def test_init_captures_type_info(self) -> None:+ stub = UnhashableStub(+ lambda x: x, var_name="f", error_msg="lambdas not pickleable"+ )+ assert stub.var_name == "f"+ assert "function" in stub.type_name.lower()+ assert stub.error_msg == "lambdas not pickleable"++ def test_load_raises_unhashable_error(self) -> None:+ stub = UnhashableStub(None, var_name="f", error_msg="cannot pickle")+ with pytest.raises(MarimoUnhashableCacheError) as exc_info:+ stub.load({})+ assert "f" in exc_info.value.variables+ assert "cannot pickle" in exc_info.value.error_details++ def test_inherits_cancel_cell_parent(self) -> None:+ """MarimoUnhashableCacheError funnels through the parent class+ in the runner's classifier."""+ err = MarimoUnhashableCacheError(+ cells_to_rerun=set(), variables=[], error_details=""+ )+ assert isinstance(err, MarimoCancelCellError)++ def test_pickle_roundtrip(self) -> None:+ original = UnhashableStub(None, var_name="f", error_msg="oops")+ original.type_name = "builtins.function"+ round_tripped = pickle.loads(pickle.dumps(original))+ assert round_tripped.var_name == "f"+ assert round_tripped.type_name == "builtins.function"+ assert round_tripped.error_msg == "oops"++ def test_isinstance_works(self) -> None:+ """Tripwires must not interfere with isinstance — the restore+ path uses isinstance to decide whether to install the marker."""+ stub = UnhashableStub(None, var_name="f")+ assert isinstance(stub, UnhashableStub)++ def test_repr_does_not_trip(self) -> None:+ """repr is safe to invoke for debugging / logging."""+ stub = UnhashableStub(None, var_name="f", error_msg="oops")+ stub.type_name = "builtins.function"+ text = repr(stub)+ assert "UnhashableStub" in text+ assert "f" in text+++class TestUnhashableStubTripwire:+ """`__call__` is the only tripwire (see UnhashableStub docstring).++ Other accesses deliberately fall through to Python defaults so+ framework probes (`getattr(value, "_repr_mimebundle_", None)`,+ `isinstance`, `hasattr`, storage-engine introspection, etc.) stay+ inert and don't cancel innocent cells.+ """++ def _stub(self) -> UnhashableStub:+ return UnhashableStub(None, var_name="x", error_msg="cannot pickle")++ def test_call_trips(self) -> None:+ with pytest.raises(MarimoUnhashableCacheError) as ei:+ self._stub()(42)+ assert ei.value.variables == ["x"]++ def test_getattr_does_not_trip(self) -> None:+ # Falls through to Python's default: a missing attribute raises+ # AttributeError, not the cache tripwire.+ with pytest.raises(AttributeError):+ _ = self._stub().some_method++ def test_len_does_not_trip(self) -> None:+ with pytest.raises(TypeError):+ len(self._stub())++ def test_iter_does_not_trip(self) -> None:+ with pytest.raises(TypeError):+ list(self._stub())++ def test_internal_attrs_dont_trip(self) -> None:+ """var_name / type_name / error_msg / load / to_bytes are+ intentionally accessible — pickling and the runner's classifier+ rely on them."""+ s = self._stub()+ assert s.var_name == "x"+ assert s.type_name == "<unknown>"+ assert s.error_msg == "cannot pickle"+ # load() raises (by design); just confirm the method is reachable.+ with pytest.raises(MarimoUnhashableCacheError):+ s.load({})+ # to_bytes() pickles successfully.+ assert s.to_bytes() == pickle.dumps(s)+++# ---------------------------------------------------------------------------+# Cache.restore — total-restore semantics for UnhashableStub+# ---------------------------------------------------------------------------+++class TestRestoreUnhashableMarker:+ def test_top_level_marker_preserved(self) -> None:+ """UnhashableStub at the top level of defs is placed in scope as-is,+ not loaded (which would raise)."""+ stub = UnhashableStub(None, var_name="f", error_msg="cannot pickle")+ cache = Cache(+ defs={"f": stub},+ hash="h",+ cache_type="ExecutionPath",+ stateful_refs=set(),+ hit=True,+ meta={},+ )+ scope: dict[str, object] = {}+ cache.restore(scope)+ assert isinstance(scope["f"], UnhashableStub)++ def test_nested_marker_in_container_preserved(self) -> None:+ """UnhashableStub nested in tuple/list/dict survives the recursive+ restore unchanged — the marker propagates instead of triggering+ `.load()` (which raises)."""+ stub = UnhashableStub(None, var_name="g", error_msg="cannot pickle")+ cache = Cache(+ defs={+ "in_tuple": (1, stub, 3),+ "in_list": [stub, "x"],+ "in_dict": {"k": stub},+ },+ hash="h",+ cache_type="ExecutionPath",+ stateful_refs=set(),+ hit=True,+ meta={},+ )+ scope: dict[str, object] = {}+ cache.restore(scope)+ assert scope["in_tuple"][1] is stub # type: ignore[index]+ assert scope["in_list"][0] is stub # type: ignore[index]+ assert scope["in_dict"]["k"] is stub # type: ignore[index]diff --git a/tests/_save/test_class_dependency_restore.py b/tests/_save/test_class_dependency_restore.pynew file mode 100644index 0000000000..4ea090377c--- /dev/null+++ b/tests/_save/test_class_dependency_restore.py@@ -0,0 +1,139 @@+# Copyright 2026 Marimo. All rights reserved.+"""Dependency-ordered restore for cell-defined classes/functions.++A cached block may define classes and functions that reference each other+(and instances of each other). On a cache hit the block is skipped, so the+loader must reconstruct everything — and it must do so in dependency order,+or exec/unpickle hits a NameError / missing-class error.+"""++from __future__ import annotations++import linecache+import textwrap+from typing import TYPE_CHECKING, Any++if TYPE_CHECKING:+ from pathlib import Path++ import pytest++from marimo._runtime.patches import (+ create_main_module,+ patch_main_module_context,+)+from marimo._save.cache import Cache+from marimo._save.hash import HashKey+from marimo._save.loaders import LazyLoader+from marimo._save.stores.file import FileStore++CELL_FILENAME = "__marimo__cell_dep_.py"+++def _seed_linecache(src: str) -> None:+ linecache.cache[CELL_FILENAME] = (+ len(src),+ None,+ [line + "\n" for line in src.splitlines()],+ CELL_FILENAME,+ )+++def _save_then_restart_restore(+ src: str,+ names: list[str],+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> dict[str, Any]:+ """Run `src` in a fresh kernel main module, cache its `names`, then+ simulate a kernel restart and restore into a brand-new main module.+ Returns the restored namespace.+ """+ monkeypatch.setattr(+ Cache, "_cell_filename", staticmethod(lambda: CELL_FILENAME)+ )+ _seed_linecache(src)++ loader = LazyLoader("t", store=FileStore(save_path=str(tmp_path)))+ key = HashKey(hash="dephash", cache_type="Pure")++ # Original run + save — all under a patched __main__ so instances of+ # cell-defined classes pickle against the right module.+ original = create_main_module(None, None)+ with patch_main_module_context(original):+ exec(compile(src, CELL_FILENAME, "exec"), original.__dict__)+ defs = {name: original.__dict__[name] for name in names}+ cache = Cache(+ defs=dict(defs),+ hash=key.hash,+ cache_type=key.cache_type,+ stateful_refs=set(),+ hit=False,+ meta={},+ )+ cache.update(dict(defs))+ assert loader.save_cache(cache)+ loader.flush()++ # Simulated restart: a fresh main module with none of the cell defs.+ restarted = create_main_module(None, None)+ with patch_main_module_context(restarted):+ loaded = loader.load_cache(key)+ assert loaded is not None, "cache failed to load after restart"+ loaded.restore(restarted.__dict__)+ return dict(restarted.__dict__)+++def test_function_class_ordering(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """`Foo`'s body calls `foo()` at class-definition time, so `foo` must+ be reconstructed before `Foo`."""+ src = textwrap.dedent(+ """+ def foo():+ return 21++ class Foo:+ doubled = foo() * 2+ """+ ).strip()+ scope = _save_then_restart_restore(+ src, ["foo", "Foo"], tmp_path, monkeypatch+ )+ assert scope["foo"]() == 21+ assert scope["Foo"].doubled == 42+++def test_instance_of_cell_class_restores(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """The caveat case: `_baz` is an instance of the cell-defined class+ `Bar`, so `Bar` must be materialized before `_baz` unpickles; `Foo`+ depends on both `Bar` (annotation) and `foo` (called in its body)."""+ src = textwrap.dedent(+ """+ class Bar:+ def __init__(self, x: int):+ self.x = x++ _baz = Bar(7)++ def foo():+ return _baz++ class Foo:+ bar: Bar = foo()+ """+ ).strip()+ scope = _save_then_restart_restore(+ src, ["Bar", "_baz", "foo", "Foo"], tmp_path, monkeypatch+ )++ assert scope["Bar"](7).x == 7+ assert scope["_baz"].x == 7+ assert isinstance(scope["_baz"], scope["Bar"])+ # foo returns the restored module-level _baz+ assert scope["foo"]() is scope["_baz"]+ # Foo.bar was computed as foo() at class-def time+ assert scope["Foo"].bar is scope["_baz"]