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
Serve a notebook's document from `marimo edit` without a kernel (#11217)
Trevor Manzbced101e3d3e
diff --git a/marimo/_core/__init__.py b/marimo/_core/__init__.pyindex 0c91eb2a3c..41800b052c 100644--- a/marimo/_core/__init__.py+++ b/marimo/_core/__init__.py@@ -1,6 +1,7 @@# Copyright 2026 Marimo. All rights reserved.-"""Types and state for the marimo host protocol.+"""State and commands for marimo hosts.-Hosts track projects and notebooks. Notebooks track runtimes, client-attachments, and runs. State changes are published as events.+A host catalogs notebooks and retains run history. A notebook brings+its document, execution results, and runtime together. State changes+are published as events described in `protocols/host/spec.md`."""diff --git a/marimo/_core/backend.py b/marimo/_core/backend.pyindex 92241ca044..1b90e43c2a 100644--- a/marimo/_core/backend.py+++ b/marimo/_core/backend.py@@ -2,7 +2,7 @@"""Kernel commands and updates for the host API.```python-notebook = host.add_notebook(record, backend)+notebook = Notebook(document, Executions(), backend, sink)runtime, _ = notebook.start() # Calls backend.start(runtime.id).# The backend reports on that runtime through Notebook.observe.@@ -134,7 +134,7 @@ class Produced:@dataclass(frozen=True)class Concluded:- """An execution's current outcome; final once the execution is completed."""+ """An execution outcome, final when the execution completes."""execution_id: protocol.ExecutionIdoutcome: protocol.Outcomediff --git a/marimo/_core/document.py b/marimo/_core/document.pynew file mode 100644index 0000000000..d1c9256333--- /dev/null+++ b/marimo/_core/document.py@@ -0,0 +1,286 @@+# Copyright 2026 Marimo. All rights reserved.+"""Notebook cells, order, configuration, and revisions."""++from __future__ import annotations++import hashlib+import json+from collections.abc import Callable, Mapping+from copy import deepcopy+from dataclasses import dataclass, field+from typing import TYPE_CHECKING, Any, Literal++from msgspec.structs import replace++from marimo._core import protocol++if TYPE_CHECKING:+ from collections.abc import Iterator, Sequence++Analyzer = Callable[[Mapping[str, str]], Mapping[str, protocol.Analysis]]+"""Derives every cell's analysis from the cells' code, keyed by id in document order."""++Policy = Literal["autorun", "lazy"]+++def etag(text: str) -> protocol.Etag:+ """The first 16 hex characters of SHA-256 over the UTF-8 text."""+ return protocol.Etag(hashlib.sha256(text.encode()).hexdigest()[:16])+++def code_hash(code: str) -> protocol.Etag:+ return etag(code)+++def cell_etag(+ code_hash: protocol.Etag, name: str, config: protocol.CellConfig+) -> protocol.Etag:+ """Over the code hash, the name, and the config values as JSON scalars."""+ values = (+ config.column,+ config.disabled,+ config.hide_code,+ config.expand_output,+ )+ return etag("\n".join([code_hash, name, *(json.dumps(v) for v in values)]))+++def order_etag(order: Sequence[str]) -> protocol.Etag:+ return etag(json.dumps(order, separators=(",", ":"), ensure_ascii=False))+++def app_config_etag(app_config: Mapping[str, Any]) -> protocol.Etag:+ """Over the app config as canonical JSON."""+ return etag(+ json.dumps(+ app_config,+ sort_keys=True,+ separators=(",", ":"),+ ensure_ascii=False,+ )+ )+++def document_etag(+ order_etag: protocol.Etag,+ app_config_etag: protocol.Etag,+ cell_etags: Sequence[protocol.Etag],+) -> protocol.Etag:+ return etag("\n".join([order_etag, app_config_etag, *cell_etags]))+++def default_config() -> protocol.CellConfig:+ return protocol.CellConfig(+ column=None, disabled=False, hide_code=False, expand_output=False+ )+++@dataclass(frozen=True)+class CellSource:+ """Cell source and metadata supplied by a file or editor."""++ id: str+ code: str+ name: str = "_"+ config: protocol.CellConfig = field(default_factory=default_config)+++@dataclass(frozen=True)+class Changed:+ """Changed cells, removed cell IDs, and the updated document."""++ cells: list[protocol.Cell]+ """New cells, and cells whose etag or analysis changed."""+ removed: list[str]+ """Ids of cells that no longer exist."""+ document: protocol.Document | None+ """The document, when any of its fields changed."""++ def __bool__(self) -> bool:+ return bool(self.cells or self.removed or self.document)+++class Document:+ """A notebook document with content-derived revisions.++ Cell source uses newline line endings. Analysis covers all cells.+ """++ def __init__(+ self,+ notebook_id: protocol.NotebookId,+ cells: Sequence[CellSource],+ app_config: Mapping[str, Any],+ *,+ policy: Policy = "autorun",+ analyzer: Analyzer | None = None,+ saved: bool = True,+ ) -> None:+ self._id = notebook_id+ self._analyzer = analyzer+ self._policy: Policy = policy+ self._cells: dict[str, protocol.Cell] = {}+ self._order: list[str] = []+ self._app_config: dict[str, Any] = {}+ self._saved_etag: protocol.Etag | None = None+ self._document: protocol.Document | None = None+ self.replace(cells, app_config)+ if saved:+ self.mark_saved()++ @classmethod+ def from_records(+ cls,+ document: protocol.Document,+ cells: Sequence[protocol.Cell],+ *,+ analyzer: Analyzer | None = None,+ ) -> Document:+ """Restore a document from its protocol records.++ Cell identities, order, and revisions must agree. Analysis is kept+ unless an analyzer is supplied. The saved revision is preserved.+ """+ document, cells = deepcopy((document, cells))+ by_id = {cell.id: cell for cell in cells}+ if len(by_id) != len(cells) or (+ len(set(document.order)) != len(document.order)+ or set(document.order) != set(by_id)+ ):+ raise ValueError(+ "document order must contain every cell exactly once"+ )+ if any(cell.notebook_id != document.id for cell in cells):+ raise ValueError("cells must belong to the document")+ restored = cls(+ document.id,+ [+ CellSource(cell.id, cell.code, cell.name, cell.config)+ for cell in (by_id[cell_id] for cell_id in document.order)+ ],+ document.app_config,+ policy=document.policy,+ analyzer=analyzer,+ saved=False,+ )+ for cell in restored:+ original = by_id[cell.id]+ if (+ cell.etag != original.etag+ or cell.code_hash != original.code_hash+ ):+ raise ValueError("cell revisions must match their content")+ if analyzer is None:+ restored._cells[cell.id] = replace(+ cell, analysis=original.analysis+ )+ current = restored._record+ if (+ current.etag != document.etag+ or current.order_etag != document.order_etag+ or current.app_config_etag != document.app_config_etag+ ):+ raise ValueError("document revisions must match its content")+ if document.saved_etag is not None:+ restored.mark_saved(document.saved_etag)+ return restored++ @property+ def notebook_id(self) -> protocol.NotebookId:+ """The notebook this document belongs to."""+ return self._id++ @property+ def _record(self) -> protocol.Document:+ assert self._document is not None+ return self._document++ def __iter__(self) -> Iterator[protocol.Cell]:+ """Iterate over cells in document order."""+ for cell_id in self._order:+ yield self._cells[cell_id]++ @property+ def order(self) -> list[str]:+ return list(self._order)++ def cell(self, cell_id: str) -> protocol.Cell | None:+ return self._cells.get(cell_id)++ def replace(+ self, cells: Sequence[CellSource], app_config: Mapping[str, Any]+ ) -> Changed:+ """Replace cells and configuration and return what changed.++ Cell IDs must be unique.+ """+ order = [source.id for source in cells]+ if len(set(order)) != len(order):+ raise ValueError("cell ids must be unique within the notebook")+ built = {source.id: self._build(source) for source in cells}+ if self._analyzer is not None:+ analyses = self._analyzer(+ {cell_id: built[cell_id].code for cell_id in order}+ )+ for cell_id in order:+ analysis = analyses.get(cell_id)+ if analysis is not None:+ built[cell_id] = replace(built[cell_id], analysis=analysis)+ changed = [+ built[cell_id]+ for cell_id in order+ if self._cells.get(cell_id) != built[cell_id]+ ]+ removed = [cell_id for cell_id in self._order if cell_id not in built]+ self._cells = built+ self._order = order+ self._app_config = dict(app_config)+ return Changed(changed, removed, self._refresh())++ def mark_saved(+ self, etag: protocol.Etag | None = None+ ) -> protocol.Document | None:+ """Record the persisted revision, which may precede the current one."""+ self._saved_etag = self._record.etag if etag is None else etag+ return self._refresh()++ def set_policy(self, policy: Policy) -> protocol.Document | None:+ self._policy = policy+ return self._refresh()++ def _build(self, source: CellSource) -> protocol.Cell:+ code = source.code.replace("\r\n", "\n").replace("\r", "\n")+ hashed = code_hash(code)+ return protocol.Cell(+ id=protocol.CellId(source.id),+ notebook_id=self._id,+ code=code,+ name=source.name,+ config=source.config,+ etag=cell_etag(hashed, source.name, source.config),+ code_hash=hashed,+ analysis=None,+ )++ def _refresh(self) -> protocol.Document | None:+ """Recompute the document and return it when it changed."""+ order = order_etag(self._order)+ app_config = app_config_etag(self._app_config)+ document = protocol.Document(+ id=self._id,+ order=tuple(protocol.CellId(c) for c in self._order),+ app_config=dict(self._app_config),+ policy=self._policy,+ etag=document_etag(+ order,+ app_config,+ [self._cells[cell_id].etag for cell_id in self._order],+ ),+ saved_etag=self._saved_etag,+ order_etag=order,+ app_config_etag=app_config,+ )+ if document == self._document:+ return None+ self._document = document+ return documentdiff --git a/marimo/_core/executions.py b/marimo/_core/executions.pyindex 547c2cdab2..cf3ca9d34f 100644--- a/marimo/_core/executions.py+++ b/marimo/_core/executions.py@@ -5,7 +5,7 @@ from __future__ import annotationsfrom copy import deepcopyfrom dataclasses import dataclass, field-from typing import Literal+from typing import TYPE_CHECKING, Literalfrom msgspec.structs import replace@@ -13,6 +13,9 @@ from marimo._core import backend as be, protocolfrom marimo._core.errors import NoRuntimefrom marimo._core.stream import utcnow+if TYPE_CHECKING:+ from collections.abc import Iterable, Mapping+@dataclass(frozen=True)class CellExecution:@@ -84,6 +87,57 @@ class Executions:self._results: dict[protocol.ExecutionId, _Result] = {}self._cells: dict[protocol.CellId, protocol.ExecutionId] = {}+ @classmethod+ def restore(+ cls,+ executions: Mapping[protocol.CellId, CellExecution],+ *,+ cells: Iterable[protocol.Cell],+ ) -> Executions:+ """Restore completed executions for cells in the document.++ Execution and output IDs must be unique. Each output must belong+ to its containing execution.+ """+ known = {cell.id for cell in cells}+ restored = cls()+ output_ids: set[protocol.ItemId] = set()+ for cell_id, retained in deepcopy(dict(executions)).items():+ execution = retained.execution+ if execution.cell_id != cell_id:+ raise ValueError(+ "results must belong to their containing cell"+ )+ if cell_id not in known:+ raise ValueError(+ f"result for cell {cell_id} not in the document"+ )+ outputs = sorted(retained.outputs, key=lambda item: item.seq)+ if execution.status != "completed":+ raise ValueError(+ "initial results must be completed executions"+ )+ if execution.outcome is None:+ raise ValueError("initial results must have an outcome")+ if execution.id in restored._results:+ raise ValueError("initial execution ids must be unique")+ if any(item.execution_id != execution.id for item in outputs):+ raise ValueError(+ "result outputs must belong to their execution"+ )+ if len({item.id for item in outputs}) != len(outputs):+ raise ValueError("result output ids must be unique")+ if output_ids.intersection(item.id for item in outputs):+ raise ValueError(+ "result output ids must be unique across cells"+ )+ output_ids.update(item.id for item in outputs)+ restored._results[execution.id] = _Result(+ execution, {item.id: item for item in outputs}+ )+ restored._cells[cell_id] = execution.id+ return restored+# ---- reads ---------------------------------------------------------def current(self, cell_id: protocol.CellId) -> CellExecution | None:@@ -160,6 +214,19 @@ class Executions:"""Stop tracking a released run."""del self._runs[run_id]+ def remove_cell(self, cell_id: protocol.CellId) -> list[Change]:+ """Remove a deleted cell's result.++ An active execution stays until its run completes.+ """+ execution_id = self._cells.get(cell_id)+ if execution_id is None:+ return []+ if self._results[execution_id].execution.status == "completed":+ return self._retire_execution(execution_id)+ self._cells.pop(cell_id)+ return []+def observe(self, msg: be.Message, runtime: protocol.Runtime | None) -> list[Change]:@@ -374,21 +441,26 @@ class Executions:result = self._results.get(execution.id)if result is None:self._results[execution.id] = _Result(execution)+ if execution.cell_id is not None:+ self._cells[execution.cell_id] = execution.idelse:result.execution = execution- if execution.cell_id is not None:- self._cells[execution.cell_id] = execution.idif execution.run_id is not None:if (tracked := self._runs.get(execution.run_id)) is not None:tracked.executions.add(execution.id)return execution- def _finish_run(self, tracked: _Run) -> list[Released]:+ def _finish_run(self, tracked: _Run) -> list[Change]:"""Release completed work that no cell retains."""+ changes: list[Change] = []for execution_id in list(tracked.executions):- if self._results[execution_id].execution.cell_id is None:+ execution = self._results[execution_id].execution+ if execution.cell_id is None:self._forget_result(execution_id)- return self._prune_run(tracked)+ elif self._cells.get(execution.cell_id) != execution_id:+ changes.extend(self._remove_execution(execution_id))+ changes.extend(self._prune_run(tracked))+ return changesdef _prune_run(self, tracked: _Run) -> list[Released]:if tracked.run.status != "completed" or tracked.executions:@@ -436,7 +508,10 @@ class Executions:def _forget_result(self, execution_id: protocol.ExecutionId) -> None:result = self._results.pop(execution_id)- if result.execution.cell_id is not None:+ if (+ result.execution.cell_id is not None+ and self._cells.get(result.execution.cell_id) == execution_id+ ):del self._cells[result.execution.cell_id]if result.execution.run_id is not None:if (diff --git a/marimo/_core/host.py b/marimo/_core/host.pyindex e8434a47bb..4a66957d33 100644--- a/marimo/_core/host.py+++ b/marimo/_core/host.py@@ -3,30 +3,39 @@from __future__ import annotations-from collections.abc import Mapping+import asyncio+import inspect+from collections.abc import Awaitable, Callable, Mappingfrom copy import deepcopyfrom dataclasses import dataclassfrom time import monotonicfrom typing import TYPE_CHECKINGfrom marimo._core import protocol-from marimo._core.backend import Backendfrom marimo._core.errors import NotFoundfrom marimo._core.notebook import Notebookfrom marimo._core.run_log import RetentionPolicy, RunLogfrom marimo._core.stream import Event, Listener, Sink, Stream, messageif TYPE_CHECKING:- from collections.abc import Callable, Collection, Iterator, Sequence+ from collections.abc import Collection, Iterator, Sequencefrom contextlib import AbstractContextManager+NotebookInitializer = Callable[+ [protocol.Notebook, Sink], Notebook | Awaitable[Notebook]+]++@dataclass-class _Entry:- """A notebook and the run history kept for it."""+class _NotebookEntry:+ """A catalog entry, its run history, and the notebook once loaded."""- notebook: Notebook+ initialize: NotebookInitializerlog: RunLog+ notebook: Notebook | None = None+ task: asyncio.Task[Notebook] | None = None+ sink: _NotebookSink | None = Noneclass _NotebookSink(Sink):@@ -35,11 +44,15 @@ class _NotebookSink(Sink):def __init__(self, stream: Stream, log: RunLog) -> None:self._stream = streamself._log = log+ # Publish initial state only after the host accepts the notebook.+ self.active = Falsedef deferred(self) -> AbstractContextManager[None]:return self._stream.deferred()def _append(self, event: Event) -> Event:+ if not self.active:+ return eventwith self._stream.deferred():removals = self._log.observe(event)recorded = self._stream.append(event)@@ -87,7 +100,7 @@ class Host:# Lookups accept wire strings; stored objects carry branded IDs.self._projects: dict[str, protocol.Project] = {}self._records: dict[str, protocol.Notebook] = {}- self._entries: dict[str, _Entry] = {}+ self._entries: dict[str, _NotebookEntry] = {}@propertydef notebooks(self) -> Mapping[str, protocol.Notebook]:@@ -110,27 +123,24 @@ class Host:def add_notebook(self,record: protocol.Notebook,- backend: Backend,+ initialize: NotebookInitializer,*,request_id: str | None = None,- ) -> Notebook:- """Register a notebook and its backend."""+ ) -> None:+ """Register a notebook with its initializer."""if record.id in self._records:raise ValueError(f"notebook {record.id} is already in the catalog")if record.project_id not in self._projects:raise ValueError(f"project {record.project_id} is not in the catalog")- log = RunLog(lambda: self.clock())- notebook = Notebook(- record.id, backend, _NotebookSink(self._stream, log)- )self._records[record.id] = deepcopy(record)- self._entries[record.id] = _Entry(notebook, log)+ self._entries[record.id] = _NotebookEntry(+ initialize, RunLog(lambda: self.clock())+ )self._stream.publish(record, notebook_id=record.id, request_id=request_id)- return notebookdef update_notebook(self, record: protocol.Notebook, *, request_id: str | None = None@@ -153,14 +163,20 @@ class Host:self, notebook_id: str, *, request_id: str | None = None) -> None:"""Remove a notebook, its runtime, attachments, and runs."""- entry = self._entries.pop(notebook_id, None)- if entry is None:+ record = self._records.pop(notebook_id, None)+ if record is None:return- record = self._records.pop(notebook_id)+ entry = self._entries.pop(notebook_id)+ if entry.task is not None:+ entry.task.cancel()+with self._stream.deferred():- entry.notebook._dispose(request_id=request_id)+ if entry.notebook is not None:+ entry.notebook._dispose(request_id=request_id)for event in entry.log.clear():self._stream.append(event)+ if entry.sink is not None:+ entry.sink.active = Falseself._stream.remove("notebook",record.id,@@ -168,13 +184,71 @@ class Host:request_id=request_id,)- def notebook(self, notebook_id: str) -> Notebook:- """Return a notebook or raise `NotFound`."""+ async def notebook(self, notebook_id: str) -> Notebook:+ """Load a notebook on first access.++ Concurrent callers share initialization. Failed loads can be retried.+ Cancelling a caller leaves shared loading intact.+ """+ entry = self._entries.get(notebook_id)+ if entry is None:+ raise NotFound(f"no notebook {notebook_id}")+ if entry.notebook is not None:+ return entry.notebook+ if entry.task is None:+ entry.task = asyncio.create_task(+ self._initialize(notebook_id, entry)+ )+ try:+ return await asyncio.shield(entry.task)+ except asyncio.CancelledError:+ if self._entries.get(notebook_id) is not entry:+ raise NotFound(f"no notebook {notebook_id}") from None+ raise++ def peek_notebook(self, notebook_id: str) -> Notebook | None:+ """Return the notebook if loaded without initializing it."""entry = self._entries.get(notebook_id)if entry is None:raise NotFound(f"no notebook {notebook_id}")return entry.notebook+ async def _initialize(+ self, notebook_id: str, entry: _NotebookEntry+ ) -> Notebook:+ try:+ sink = _NotebookSink(self._stream, entry.log)+ result = entry.initialize(+ deepcopy(self._records[notebook_id]), sink+ )+ notebook = await result if inspect.isawaitable(result) else result+ if self._entries.get(notebook_id) is not entry:+ raise NotFound(f"no notebook {notebook_id}")+ if notebook.id != notebook_id:+ raise ValueError(+ "initialized notebook must match its catalog id"+ )+ entry.notebook = notebook++ entry.sink = sink+ sink.active = True+ # The initial state joins the stream the way later changes do,+ # so the run history sees every run from its first event.+ with self._stream.deferred():+ for event in notebook._snapshot():+ assert event.kind is not None+ body = getattr(event.data, event.kind)+ sink.publish(+ body,+ notebook_id=notebook.id,+ run_id=event.run_id,+ )+ if self._entries.get(notebook_id) is not entry:+ raise NotFound(f"no notebook {notebook_id}")+ return notebook+ finally:+ entry.task = None+def run(self, notebook_id: str, run_id: str) -> protocol.Run | None:"""Return a run the host still retains, if any."""entry = self._entries.get(notebook_id)@@ -200,6 +274,8 @@ class Host:Event("notebook", message(record), notebook_id=record.id))entry = self._entries[record.id]+ if entry.notebook is None:+ continueseen: set[tuple[str, str]] = set()for event in [*entry.notebook._snapshot(),@@ -224,7 +300,11 @@ class Host:A cursor requests the events after it. An unavailable cursor returns`reset` and a snapshot."""- scope = None if notebook_id is None else self.notebook(notebook_id).id+ scope = None+ if notebook_id is not None:+ if notebook_id not in self._records:+ raise NotFound(f"no notebook {notebook_id}")+ scope = self._records[notebook_id].idready = Event("ready", id=self._stream.last_id)if cursor is None:events = self._snapshot(scope)diff --git a/marimo/_core/notebook.py b/marimo/_core/notebook.pyindex 82fad6444e..f44673fe15 100644--- a/marimo/_core/notebook.py+++ b/marimo/_core/notebook.py@@ -3,6 +3,7 @@from __future__ import annotations+from dataclasses import dataclassfrom typing import TYPE_CHECKING, Anyimport msgspec@@ -15,44 +16,74 @@ from marimo._core.ids import mintfrom marimo._core.stream import Event, Kind, kind_of, message, utcnowif TYPE_CHECKING:- from collections.abc import Callable, Sequence+ from collections.abc import Callable, Mapping, Sequence- from marimo._core.executions import Change+ from marimo._core.document import CellSource, Changed, Document+ from marimo._core.executions import CellExecution, Changefrom marimo._core.stream import Body, Sink+@dataclass(frozen=True)+class CellSnapshot:+ """A cell and its retained execution, if any."""++ cell: protocol.Cell+ execution: CellExecution | None = None+++@dataclass(frozen=True)+class NotebookSnapshot:+ """A document and its cells with their completed executions.++ Cells are in document order. Runtimes, attachments, and active work+ are excluded. Restore with `Document.from_records` and+ `Executions.restore` before constructing a notebook.+ """++ document: protocol.Document+ cells: tuple[CellSnapshot, ...]++class Notebook:- """A notebook with execution results, a runtime, and client attachments.+ """A document, its execution results, and the runtime that produces them.- Commands call the backend. Backend reports update state and reach- the sink as notebook events. Change execution state through the- notebook so each change reaches the sink.+ The document and cell results remain when the runtime stops.+ Commands call the backend and publish changes through the sink.+ Change the document and executions through the notebook so each+ change reaches the sink."""def __init__(self,- notebook_id: protocol.NotebookId,+ document: Document,+ executions: Executions,backend: be.Backend,sink: Sink,) -> None:- self._id = notebook_id- self._backend = backend- self._sink = sink+ self._document = document+ self._executions = executions+ self.backend = backend+ self.sink = sinkself._closed = Falseself._runtime: protocol.Runtime | None = Noneself._attachments: dict[str, protocol.Attachment] = {}- self._executions = Executions()self._replacement: protocol.Runtime | None = None# Correlate runtime events with the pending start, stop, or restart.self._runtime_request: str | None = None+ @property+ def document(self) -> Document:+ """The document owned by this notebook; change it through the notebook."""+ return self._document+@propertydef executions(self) -> Executions:+ """The execution results owned by this notebook."""return self._executions@propertydef id(self) -> protocol.NotebookId:- return self._id+ return self.document.notebook_id@propertydef runtime(self) -> protocol.Runtime | None:@@ -63,20 +94,56 @@ class Notebook:if self._closed:raise NotFound(f"no notebook {self.id}")+ # ---- document ------------------------------------------------------++ def replace(+ self,+ cells: Sequence[CellSource],+ app_config: Mapping[str, object],+ *,+ request_id: str | None = None,+ ) -> Changed:+ """Replace the document and publish its changes."""+ self._require_open()+ changed = self.document.replace(cells, app_config)+ self._publish_changed(changed, request_id)+ return changed++ def mark_saved(self, *, request_id: str | None = None) -> None:+ """Mark the current document revision as saved."""+ self._require_open()+ document = self.document.mark_saved()+ if document is not None:+ self._publish(document, request_id)++ def _publish_changed(+ self, changed: Changed, request_id: str | None+ ) -> None:+ with self.sink.deferred():+ for cell in changed.cells:+ self._publish(cell, request_id)+ for cell_id in changed.removed:+ self._apply(+ self.executions.remove_cell(protocol.CellId(cell_id))+ )+ self._remove("cell", cell_id, request_id)+ if changed.document is not None:+ self._publish(changed.document, request_id)+# ---- runtime -------------------------------------------------------def start(self, *, request_id: str | None = None) -> tuple[protocol.Runtime, bool]:"""Return the runtime and whether this call started it."""- with self._sink.deferred():+ with self.sink.deferred():self._require_open()if self._runtime is not None:return self._runtime, Falseruntime = self._new_runtime("starting", None, None)self._runtime_request = request_idself._set_runtime(runtime)- self._backend.start(runtime.id)+ self.backend.start(runtime.id)return runtime, Truedef stop(self, *, request_id: str | None = None) -> protocol.Runtime:@@ -85,7 +152,7 @@ class Notebook:The runtime stays until the backend reports its exit. A failed runtimeis removed immediately."""- with self._sink.deferred():+ with self.sink.deferred():self._require_open()runtime = self._require_runtime()self._runtime_request = request_id@@ -97,7 +164,7 @@ class Notebook:if runtime.status == "failed":self._end_runtime()else:- self._backend.stop(runtime.id)+ self.backend.stop(runtime.id)return terminatingdef restart(self, *, request_id: str | None = None) -> protocol.Runtime:@@ -105,7 +172,7 @@ class Notebook:The replacement starts after the old runtime exits."""- with self._sink.deferred():+ with self.sink.deferred():self._require_open()runtime = self._require_runtime()if runtime.status != "running":@@ -117,7 +184,7 @@ class Notebook:self._replacement = replacementterminating = replace(runtime, status="terminating")self._set_runtime(terminating)- self._backend.stop(runtime.id)+ self.backend.stop(runtime.id)return replacement# TODO: Remove once sessions start their runtime through `start`.@@ -129,7 +196,7 @@ class Notebook:Calls `attach` with a new runtime ID before delivering events."""- with self._sink.deferred():+ with self.sink.deferred():self._require_open()if self._runtime is not None:if self._runtime.status != "failed":@@ -166,7 +233,7 @@ class Notebook:def run(self, code: str, *, request_id: str) -> protocol.Run:"""Queue scratch code on a running, idle runtime."""- with self._sink.deferred():+ with self.sink.deferred():self._require_open()runtime = self._require_runtime()if runtime.status != "running":@@ -184,7 +251,7 @@ class Notebook:completed_at=None,)self._apply(self.executions.begin(run, request_id))- self._backend.run(run.id, code)+ self.backend.run(run.id, code)return rundef interrupt(self, run_id: str) -> protocol.Run:@@ -195,7 +262,7 @@ class Notebook:raise NotFound(f"notebook {self.id} has no run {run_id}.")if run.status == "completed":raise Conflict(f"run {run_id} has already ended.")- self._backend.interrupt(run.id)+ self.backend.interrupt(run.id)return run# ---- attachments ---------------------------------------------------@@ -273,11 +340,11 @@ class Notebook:if runtime.status == "terminating" and self._replacement is not None:replacement, self._replacement = self._replacement, Nonerequest_id = self._runtime_request- with self._sink.deferred():+ with self.sink.deferred():self._end_runtime()self._runtime_request = request_idself._set_runtime(replacement)- self._backend.start(replacement.id)+ self.backend.start(replacement.id)elif runtime.status == "terminating":self._end_runtime()else:@@ -323,7 +390,7 @@ class Notebook:def _snapshot(self) -> list[Event]:"""Return current state as events in dependency order."""- bodies: list[Body] = []+ bodies: list[Body] = [*self.document, self.document._record]if self._runtime is not None:bodies.append(self._runtime)bodies.extend(self._attachments.values())@@ -361,7 +428,7 @@ class Notebook:self._remove("runtime", runtime.id, request_id)def _publish(self, body: Body, request_id: str | None) -> None:- self._sink.publish(+ self.sink.publish(body,notebook_id=self.id,request_id=request_id,@@ -373,7 +440,7 @@ class Notebook:object_id: str,request_id: str | None,) -> None:- self._sink.remove(+ self.sink.remove(kind,object_id,notebook_id=self.id,@@ -383,16 +450,16 @@ class Notebook:def _apply(self, changes: Sequence[Change]) -> None:"""Publish changes and release completed runs."""executions = self.executions- with self._sink.deferred():+ with self.sink.deferred():for change in changes:if isinstance(change, Released):executions.release(change.run_id)- self._backend.forget(change.run_id)+ self.backend.forget(change.run_id)continuerun_id = executions.run_id_of(change)request_id = executions.request_id(run_id)if isinstance(change, Removed):- self._sink.remove(+ self.sink.remove(change.kind,change.id,notebook_id=self.id,@@ -400,7 +467,7 @@ class Notebook:request_id=request_id,)else:- self._sink.publish(+ self.sink.publish(change,notebook_id=self.id,run_id=run_id,diff --git a/marimo/_core/protocol.py b/marimo/_core/protocol.pyindex a9bd562811..2a313322b9 100644--- a/marimo/_core/protocol.py+++ b/marimo/_core/protocol.py@@ -798,7 +798,7 @@ class Document(Struct, frozen=True):order_etag: Annotated[Etag,Meta(- description="Identifies the order alone. Its text is the cell ids in order. Editing a cell does not change it."+ description="Identifies the order alone. Its text is the cell IDs in order as a JSON array, with no whitespace and strings carrying only the escapes JSON requires. Editing a cell does not change it."),]policy: Annotated[diff --git a/marimo/_core/stream.py b/marimo/_core/stream.pyindex ad7b02af6a..90adb0ea05 100644--- a/marimo/_core/stream.py+++ b/marimo/_core/stream.py@@ -28,6 +28,8 @@ Body: TypeAlias = (protocol.Host| protocol.Project| protocol.Notebook+ | protocol.Document+ | protocol.Cell| protocol.Runtime| protocol.Attachment| protocol.Run@@ -44,6 +46,8 @@ Kind: TypeAlias = Literal["host","project","notebook",+ "document",+ "cell","runtime","attachment","run",diff --git a/marimo/_server/host/analysis.py b/marimo/_server/host/analysis.pynew file mode 100644index 0000000000..dc382b33a2--- /dev/null+++ b/marimo/_server/host/analysis.py@@ -0,0 +1,110 @@+# Copyright 2026 Marimo. All rights reserved.+"""Cell definitions, references, and syntax errors.++The kernel reports errors involving multiple cells, such as cycles+and multiple definitions.+"""++from __future__ import annotations++from typing import TYPE_CHECKING++from marimo._ast.compiler import compile_cell+from marimo._core import protocol+from marimo._types.ids import CellId_t++if TYPE_CHECKING:+ from collections.abc import Mapping++ from marimo._ast.cell import CellImpl++SOURCE = "marimo"+++class Analyzer:+ """Incremental analysis for one document."""++ def __init__(self) -> None:+ self._codes: dict[str, str] = {}+ self._compiled: dict[str, CellImpl] = {}+ self._syntax: dict[str, protocol.Error] = {}++ def __call__(+ self, codes: Mapping[str, str]+ ) -> dict[str, protocol.Analysis]:+ self._update(codes)+ definers: dict[str, int] = {}+ for cell in self._compiled.values():+ for name in cell.defs:+ definers[name] = definers.get(name, 0) + 1+ result: dict[str, protocol.Analysis] = {}+ for cell_id in codes:+ compiled = self._compiled.get(cell_id)+ if compiled is None:+ result[cell_id] = protocol.Analysis(+ defs=(), refs=(), errors=(self._syntax[cell_id],)+ )+ continue+ result[cell_id] = protocol.Analysis(+ defs=tuple(sorted(compiled.defs)),+ refs=tuple(+ sorted(+ name+ for name in compiled.refs+ if definers.get(name, 0) > (name in compiled.defs)+ )+ ),+ errors=(),+ )+ return result++ def _update(self, codes: Mapping[str, str]) -> None:+ """Forget cells that are gone or changed, then compile what is new."""+ for cell_id in list(self._codes):+ if codes.get(cell_id) == self._codes[cell_id]:+ continue+ del self._codes[cell_id]+ self._syntax.pop(cell_id, None)+ self._compiled.pop(cell_id, None)+ for cell_id, code in codes.items():+ if cell_id in self._codes:+ continue+ try:+ self._compiled[cell_id] = compile_cell(code, CellId_t(cell_id))+ except (SyntaxError, ValueError) as error:+ self._syntax[cell_id] = _syntax_error(code, error)+ self._codes[cell_id] = code+++def analyze(codes: Mapping[str, str]) -> dict[str, protocol.Analysis]:+ """Analyze a document once."""+ return Analyzer()(codes)+++def _syntax_error(code: str, e: Exception) -> protocol.Error:+ where = None+ if isinstance(e, SyntaxError) and e.lineno is not None:+ line = e.lineno - 1+ character = _utf16(code, line, (e.offset or 1) - 1)+ where = protocol.Range(+ start=protocol.Position(line=line, character=character),+ end=protocol.Position(line=line, character=character),+ )+ message = e.msg if isinstance(e, SyntaxError) else str(e)+ return protocol.Error(+ kind="invalid-syntax",+ message=message,+ source=SOURCE,+ severity="error",+ range=where,+ name=None,+ traceback=None,+ related=(),+ )+++def _utf16(code: str, line: int, column: int) -> int:+ """Convert a source column to UTF-16 code units."""+ lines = code.split("\n")+ text = lines[line] if line < len(lines) else ""+ return len(text[:column].encode("utf-16-le")) // 2diff --git a/marimo/_server/host/api.py b/marimo/_server/host/api.pyindex 09145c94ca..62c1392031 100644--- a/marimo/_server/host/api.py+++ b/marimo/_server/host/api.py@@ -155,8 +155,10 @@ def _context(request: Request) -> HostContext:return context # type: ignore[no-any-return]-def _notebook(request: Request) -> Notebook:- return _context(request).bridge.host.notebook(request.path_params["id"])+async def _notebook(request: Request) -> Notebook:+ return await _context(request).bridge.host.notebook(+ request.path_params["id"]+ )def _record(request: Request) -> protocol.Notebook:@@ -366,7 +368,7 @@ async def _decode(request: Request, kind: type[_Body]) -> _Body:async def _events(request: Request) -> Response:"""Stream catalog snapshots and updates.- `Last-Event-ID` resumes from a cursor; `types` filters event kinds.+ `Last-Event-ID` resumes from a cursor. `types` filters event kinds."""context = _context(request)cursor = _cursor(request)@@ -384,9 +386,11 @@ async def _notebook_events(request: Request) -> Response:"""Stream notebook events, attaching the client until disconnect."""context = _context(request)try:- notebook = _notebook(request)+ notebook = await _notebook(request)except NotFound as e:return problem(404, "not-found", str(e))+ except Conflict as e:+ return problem(409, "conflict", str(e))cursor = _cursor(request)if isinstance(cursor, Response):return cursor@@ -571,10 +575,10 @@ async def _update_notebook(request: Request) -> Response:@_mutation("notebook.delete")async def _delete_notebook(request: Request) -> Response:- """Delete the notebook and file; return 409 while a runtime exists."""+ """Delete the notebook and its file if it has no runtime."""context = _context(request)key = request.headers["Idempotency-Key"]- await context.bridge.delete(_notebook(request).id, request_id=key)+ await context.bridge.delete(_record(request).id, request_id=key)return _reply(204, None)@@ -612,9 +616,9 @@ def _open_quietly(browser: str, url: str) -> None:@_mutation("runtime.start")async def _start_runtime(request: Request) -> Response:- """Start a runtime: 202 if created, 200 if already present."""+ """Start a runtime and return 202, or 200 if it already exists."""key = request.headers["Idempotency-Key"]- notebook = _notebook(request)+ notebook = await _notebook(request)await _decode(request, protocol.StartRuntimeRequest)runtime, created = notebook.start(request_id=key)return _reply(202 if created else 200, runtime)@@ -624,7 +628,7 @@ async def _start_runtime(request: Request) -> Response:async def _stop_runtime(request: Request) -> Response:"""Request shutdown and return 202 with the runtime marked terminating."""key = request.headers["Idempotency-Key"]- notebook = _notebook(request)+ notebook = await _notebook(request)runtime = notebook.stop(request_id=key)return _reply(202, runtime)@@ -633,7 +637,7 @@ async def _stop_runtime(request: Request) -> Response:async def _restart_runtime(request: Request) -> Response:"""Return 202 with the replacement runtime in its starting state."""key = request.headers["Idempotency-Key"]- notebook = _notebook(request)+ notebook = await _notebook(request)runtime = notebook.restart(request_id=key)return _reply(202, runtime)@@ -643,9 +647,9 @@ async def _restart_runtime(request: Request) -> Response:@_mutation("runtime.run")async def _run(request: Request) -> Response:- """Queue a run and return 202; stream results through notebook events."""+ """Queue a run and return 202. Results arrive through notebook events."""key = request.headers["Idempotency-Key"]- notebook = _notebook(request)+ notebook = await _notebook(request)body = await _decode(request, protocol.RunRequest)if body.code is msgspec.UNSET or body.cells is not msgspec.UNSET:return problem(@@ -657,8 +661,8 @@ async def _run(request: Request) -> Response:@_mutation("runtime.run")async def _interrupt(request: Request) -> Response:- """Request a run interruption: 202 if active, 409 if completed."""- notebook = _notebook(request)+ """Interrupt an active run and return 202, or 409 if it has completed."""+ notebook = await _notebook(request)run_id = request.path_params["run_id"]try:interrupted = notebook.interrupt(run_id)diff --git a/marimo/_server/host/bridge.py b/marimo/_server/host/bridge.pyindex b8904b1355..1c801e5e0d 100644--- a/marimo/_server/host/bridge.py+++ b/marimo/_server/host/bridge.py@@ -4,14 +4,19 @@from __future__ import annotationsimport asyncio-from typing import TYPE_CHECKING+from typing import TYPE_CHECKING, Anyfrom marimo import _loggers+from marimo._config.manager import ScriptConfigReaderfrom marimo._core import protocol+from marimo._core.document import CellSource, Documentfrom marimo._core.errors import Conflict, NotFound+from marimo._core.executions import Executionsfrom marimo._core.host import Host+from marimo._core.notebook import Notebookfrom marimo._runtime.commands import RenameNotebookCommandfrom marimo._server.host import OPERATIONS+from marimo._server.host.analysis import Analyzerfrom marimo._server.host.backend import SessionBackendfrom marimo._server.host.index import WorkspaceIndexfrom marimo._session.events import SessionEventListener@@ -20,35 +25,46 @@ from marimo._session.notebook.storage import rename_no_replaceif TYPE_CHECKING:from pathlib import Path+ from marimo._ast.cell import CellConfig+ from marimo._config.manager import MarimoConfigManagerfrom marimo._core.backend import Message- from marimo._core.stream import Event+ from marimo._core.document import Policy+ from marimo._core.stream import Event, Sinkfrom marimo._server.session_manager import SessionManager+ from marimo._session.notebook import AppFileManagerfrom marimo._session.session import SessionLOGGER = _loggers.marimo_logger()+# TODO: Remove once sessions consume host-owned notebooks.class SessionBridge(SessionEventListener):"""Connect a host's notebook catalog to a session manager."""- def __init__(self, manager: SessionManager) -> None:+ def __init__(+ self,+ manager: SessionManager,+ config_manager: MarimoConfigManager | None = None,+ ) -> None:self._manager = manager+ self._config_manager = config_managerself._files_lock = asyncio.Lock()+ self._adopting: dict[protocol.NotebookId, Session] = {}self.host = Host(operations=OPERATIONS)self._backends: dict[protocol.NotebookId, SessionBackend] = {}self.index = WorkspaceIndex(- self.host, manager.workspace, self._make_backend+ self.host, manager.workspace, self._initialize_notebook)self._unsubscribe = self.host.subscribe(self._forget_backend, types={"notebook"})- def open(self) -> None:+ async def open(self) -> None:"""Index notebooks, adopt sessions, and subscribe to session events."""self.index.refresh()- for session in list(self._manager.sessions.values()):- self._adopt(session)self._manager.event_bus.subscribe(self)+ for session in list(self._manager.sessions.values()):+ await self._adopt(session)def close(self) -> None:self._manager.event_bus.unsubscribe(self)@@ -59,6 +75,80 @@ class SessionBridge(SessionEventListener):async with self._files_lock:await self.index.refresh_async()+ async def _initialize_notebook(+ self, record: protocol.Notebook, sink: Sink+ ) -> Notebook:+ """Read the document and construct its notebook."""+ async with self._files_lock:+ file = self.index.file_of(record.id)+ loaded = None if file is None else await self._load(file)+ session = self._adopting.get(record.id)+ if session is None:+ for candidate in self._manager.sessions.values():+ candidate_record = self.index.notebook_for(+ candidate.app_file_manager.path+ )+ if (+ candidate_record is not None+ and candidate_record.id == record.id+ ):+ session = candidate+ break+ if session is not None:+ cells, app_config = _from_session(session)+ else:+ if loaded is None:+ raise Conflict("The notebook document could not be loaded")+ cells, app_config = loaded+ document = Document(+ record.id,+ cells,+ app_config,+ policy=self._policy(file, session),+ analyzer=Analyzer(),+ saved=session is None,+ )+ if session is not None and loaded is not None:+ document.mark_saved(Document(record.id, *loaded)._record.etag)+ backend = self._make_backend(record.id)+ return Notebook(document, Executions(), backend, sink)++ async def _load(+ self, file: Path+ ) -> tuple[list[CellSource], dict[str, Any]] | None:+ """Read a notebook file, or return `None` if it cannot be loaded."""+ try:+ return await asyncio.to_thread(self._read, str(file))+ except Exception as e:+ LOGGER.warning("Could not load %s: %s", file, e)+ return None++ def _read(self, path: str) -> tuple[list[CellSource], dict[str, Any]]:+ from marimo._server.app_defaults import AppDefaults+ from marimo._session.notebook import AppFileManager++ defaults = (+ None+ if self._config_manager is None+ else AppDefaults.from_config_manager(self._config_manager)+ )+ return _from_file_manager(AppFileManager(path, defaults=defaults))++ def _policy(self, file: Path | None, session: Session | None) -> Policy:+ config_manager = (+ session.config_manager+ if session is not None+ else self._config_manager+ )+ if config_manager is None:+ return "autorun"+ if session is None:+ config_manager = config_manager.with_partial(+ ScriptConfigReader(None if file is None else str(file))+ )+ policy = config_manager.get_config()["runtime"]["on_cell_change"]+ return "lazy" if policy == "lazy" else "autorun"+def _project_path(self, path: Path) -> Path:root = self.index.rootif root is None:@@ -107,7 +197,7 @@ class SessionBridge(SessionEventListener):) -> protocol.Notebook:"""Update a notebook's file and label, preserving its runtime."""async with self._files_lock:- self.host.notebook(notebook_id)+ self.host.peek_notebook(notebook_id)if target is not None:await self._move(notebook_id, target, request_id=request_id)if name is not None:@@ -119,8 +209,10 @@ class SessionBridge(SessionEventListener):) -> None:"""Remove a notebook without a runtime and its backing file."""async with self._files_lock:- notebook = self.host.notebook(notebook_id)- if notebook.runtime is not None:+ notebook = self.host.peek_notebook(notebook_id)+ if notebook_id in self._adopting or (+ notebook is not None and notebook.runtime is not None+ ):raise Conflict("The notebook has a runtime")file = self.index.file_of(notebook_id)if file is not None:@@ -184,11 +276,12 @@ class SessionBridge(SessionEventListener):def observe(message: Message) -> None:try:- notebook = self.host.notebook(notebook_id)+ notebook = self.host.peek_notebook(notebook_id)except NotFound:# Sessions can report shutdown after their catalog removal.return- notebook.observe(message)+ if notebook is not None:+ notebook.observe(message)backend = SessionBackend(notebook_id,@@ -203,7 +296,7 @@ class SessionBridge(SessionEventListener):if event.name == "notebook.removed" and event.notebook_id is not None:self._backends.pop(event.notebook_id, None)- def _adopt(self, session: Session) -> None:+ async def _adopt(self, session: Session) -> None:path = session.app_file_manager.pathnotebook = self.index.notebook_for(path)if notebook is None and path is not None:@@ -211,13 +304,17 @@ class SessionBridge(SessionEventListener):if notebook is None:LOGGER.debug("Not publishing session for %s", path)return+ if self._adopting.setdefault(notebook.id, session) is not session:+ return+ try:+ loaded = await self.host.notebook(notebook.id)+ finally:+ self._adopting.pop(notebook.id, None)backend = self._backends[notebook.id]if backend.session is not None:returntry:- self.host.notebook(notebook.id).adopt(- lambda runtime_id: backend.adopt(runtime_id, session)- )+ loaded.adopt(lambda runtime_id: backend.adopt(runtime_id, session))except Conflict:LOGGER.debug("Not publishing a second session for %s", path)return@@ -225,7 +322,7 @@ class SessionBridge(SessionEventListener):# Session eventsasync def on_session_created(self, session: Session) -> None:- self._adopt(session)+ await self._adopt(session)async def on_session_notebook_renamed(self, session: Session, old_path: str | None@@ -236,6 +333,33 @@ class SessionBridge(SessionEventListener):returnif notebook is None:# Add notebooks to the catalog when first saved.- self._adopt(session)+ await self._adopt(session)returnself.index.moved(notebook.id, path)+++def _from_session(session: Session) -> tuple[list[CellSource], dict[str, Any]]:+ cells = [+ CellSource(cell.id, cell.code, cell.name, _config(cell.config))+ for cell in session.document.cells+ ]+ return cells, session.app_file_manager.app.config.asdict_difference()+++def _from_file_manager(+ manager: AppFileManager,+) -> tuple[list[CellSource], dict[str, Any]]:+ cells = [+ CellSource(data.cell_id, data.code, data.name, _config(data.config))+ for data in manager.app.cell_manager.cell_data()+ ]+ return cells, manager.app.config.asdict_difference()+++def _config(config: CellConfig) -> protocol.CellConfig:+ return protocol.CellConfig(+ column=config.column,+ disabled=config.disabled,+ hide_code=config.hide_code,+ expand_output=config.expand_output,+ )diff --git a/marimo/_server/host/index.py b/marimo/_server/host/index.pyindex e6e5b0bed7..a36282f687 100644--- a/marimo/_server/host/index.py+++ b/marimo/_server/host/index.py@@ -7,7 +7,6 @@ Notebook IDs persist across rescans and recorded file moves.from __future__ import annotationsimport asyncio-from collections.abc import Callablefrom datetime import datetime, timezonefrom pathlib import Pathfrom typing import TYPE_CHECKING@@ -20,15 +19,12 @@ from marimo._server.host import OPERATIONSfrom marimo._server.workspace import flatten_filesif TYPE_CHECKING:- from marimo._core.backend import Backend- from marimo._core.host import Host+ from marimo._core.host import Host, NotebookInitializerfrom marimo._server.models.files import FileInfofrom marimo._server.workspace import NotebookWorkspace_TRUNCATED = "The scan stopped at its depth, file count, or time limit"-MakeBackend = Callable[[protocol.NotebookId], "Backend"]-class WorkspaceIndex:"""A host project and its indexed notebook files."""@@ -37,11 +33,11 @@ class WorkspaceIndex:self,host: Host,workspace: NotebookWorkspace,- make_backend: MakeBackend,+ initialize: NotebookInitializer,) -> None:self._host = host+ self._initialize = initializeself._workspace = workspace- self._make_backend = make_backendself._root = _root_of(workspace)self.project_id = mint(protocol.ProjectId, "proj")self._ids: dict[Path, protocol.NotebookId] = {}@@ -96,7 +92,8 @@ class WorkspaceIndex:continueif notebook.id in seen or self._exists(notebook):continue- if self._host.notebook(notebook.id).runtime is not None:+ loaded = self._host.peek_notebook(notebook.id)+ if loaded is not None and loaded.runtime is not None:self._host.update_notebook(replace(notebook, path=None, updated_at=None))@@ -215,8 +212,9 @@ class WorkspaceIndex:if notebook_id in self._host.notebooks:self._host.update_notebook(record, request_id=request_id)else:- backend = self._make_backend(notebook_id)- self._host.add_notebook(record, backend, request_id=request_id)+ self._host.add_notebook(+ record, self._initialize, request_id=request_id+ )return recorddef _exists(self, notebook: protocol.Notebook) -> bool:diff --git a/marimo/_server/host/lifespan.py b/marimo/_server/host/lifespan.pyindex 008667ba3a..93ad3cf930 100644--- a/marimo/_server/host/lifespan.py+++ b/marimo/_server/host/lifespan.py@@ -31,8 +31,8 @@ async def host(app: Starlette) -> AsyncIterator[None]:yieldreturn- bridge = SessionBridge(state.session_manager)- bridge.open()+ bridge = SessionBridge(state.session_manager, state.config_manager)+ await bridge.open()token = secrets.token_urlsafe(32)server = state.server.configurl = host_url(server.host, server.port, state.base_url)diff --git a/marimo/_server/host/translate.py b/marimo/_server/host/translate.pyindex f878736999..16c5f0caff 100644--- a/marimo/_server/host/translate.py+++ b/marimo/_server/host/translate.py@@ -3,13 +3,13 @@from __future__ import annotations-import hashlibimport htmlimport jsonimport refrom dataclasses import dataclass, fieldfrom marimo._core import backend as be, protocol+from marimo._core.document import code_hashfrom marimo._messaging.cell_output import CellChannelfrom marimo._messaging.errors import (Error,@@ -134,7 +134,7 @@ class RunTranslator:Noneif execution.cell_id == SCRATCH_CELL_IDelse execution.cell_id,- hashlib.sha256(code.encode()).hexdigest(),+ code_hash(code),code if execution.cell_id == SCRATCH_CELL_ID else None,caused_by=parent.id if parent is not None else None,),diff --git a/protocols/host/conformance/contract.py b/protocols/host/conformance/contract.pyindex f4b98878e4..28a1bce3c3 100644--- a/protocols/host/conformance/contract.py+++ b/protocols/host/conformance/contract.py@@ -212,7 +212,11 @@ def document_state(for key in ("column", "disabled", "hide_code", "expand_output"))assert cell["etag"] == etag("\n".join(parts))- assert document["order_etag"] == etag("\n".join(document["order"]))+ assert document["order_etag"] == etag(+ json.dumps(+ document["order"], separators=(",", ":"), ensure_ascii=False+ )+ )canonical = json.dumps(document["app_config"],sort_keys=True,diff --git a/protocols/host/fixtures/edit-response.json b/protocols/host/fixtures/edit-response.jsonindex 89fed4614c..97c14f559e 100644--- a/protocols/host/fixtures/edit-response.json+++ b/protocols/host/fixtures/edit-response.json@@ -11,9 +11,9 @@"app_title": "Forecasts"},"policy": "autorun",- "etag": "82eabd9627d6bdf4",- "saved_etag": "0129d119bfb96bf9",- "order_etag": "389ebf709589e5d6",+ "etag": "949c0dd20bc77042",+ "saved_etag": "e59d9c2af02f5814",+ "order_etag": "162e15055422ed71","app_config_etag": "1d79ec53fdad1a23"},"cells": {diff --git a/protocols/host/fixtures/edits.sse b/protocols/host/fixtures/edits.sseindex 3b1beb6fbf..771fc655b7 100644--- a/protocols/host/fixtures/edits.sse+++ b/protocols/host/fixtures/edits.sse@@ -12,9 +12,9 @@ data: {"id":"k7f2","request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2id: 113event: document-data: {"document":{"id":"n1","order":["c1","c2","c3"],"app_config":{"width":"full","app_title":"Forecasts"},"policy":"autorun","etag":"82eabd9627d6bdf4","saved_etag":"0129d119bfb96bf9","order_etag":"389ebf709589e5d6","app_config_etag":"1d79ec53fdad1a23"},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}+data: {"document":{"id":"n1","order":["c1","c2","c3"],"app_config":{"width":"full","app_title":"Forecasts"},"policy":"autorun","etag":"949c0dd20bc77042","saved_etag":"e59d9c2af02f5814","order_etag":"162e15055422ed71","app_config_etag":"1d79ec53fdad1a23"},"request_id":"9b1c6d2e-0f3a-4b5c-8d7e-1f2a3b4c5d6e","time":"2026-10-01T09:21:00Z"}id: 114event: document-data: {"document":{"id":"n1","order":["c1","c2","c3"],"app_config":{"width":"full","app_title":"Forecasts"},"policy":"autorun","etag":"82eabd9627d6bdf4","saved_etag":"82eabd9627d6bdf4","order_etag":"389ebf709589e5d6","app_config_etag":"1d79ec53fdad1a23"},"request_id":"save-9b1c6d2e","time":"2026-10-01T09:21:02Z"}+data: {"document":{"id":"n1","order":["c1","c2","c3"],"app_config":{"width":"full","app_title":"Forecasts"},"policy":"autorun","etag":"949c0dd20bc77042","saved_etag":"949c0dd20bc77042","order_etag":"162e15055422ed71","app_config_etag":"1d79ec53fdad1a23"},"request_id":"save-9b1c6d2e","time":"2026-10-01T09:21:02Z"}diff --git a/protocols/host/fixtures/notebook-events.sse b/protocols/host/fixtures/notebook-events.sseindex f7b2812ce5..16ab8c787a 100644--- a/protocols/host/fixtures/notebook-events.sse+++ b/protocols/host/fixtures/notebook-events.sse@@ -11,7 +11,7 @@ event: celldata: {"cell":{"id":"k7f2","notebook_id":"n1","code":"y = x * 2","name":"_","config":{"column":null,"disabled":false,"hide_code":true,"expand_output":false},"etag":"f199b5f48ae0aabb","code_hash":"db2b9ee97e1ecf4c","analysis":{"defs":["y"],"refs":["x"],"errors":[]}}}event: document-data: {"document":{"id":"n1","order":["c1","c3","k7f2"],"app_config":{"width":"full"},"policy":"autorun","etag":"0129d119bfb96bf9","saved_etag":"0129d119bfb96bf9","order_etag":"b205774f616b44e3","app_config_etag":"283513048dfeb45b"}}+data: {"document":{"id":"n1","order":["c1","c3","k7f2"],"app_config":{"width":"full"},"policy":"autorun","etag":"e59d9c2af02f5814","saved_etag":"e59d9c2af02f5814","order_etag":"b9c412c2d7d63161","app_config_etag":"283513048dfeb45b"}}event: runtimedata: {"runtime":{"id":"r1","notebook_id":"n1","status":"running","message":null,"marimo_version":"0.25.0","started_at":"2026-10-01T09:14:02Z"}}diff --git a/protocols/host/fixtures/problems/edit-conflict.json b/protocols/host/fixtures/problems/edit-conflict.jsonindex 1f4c3e8e36..d73bd124f3 100644--- a/protocols/host/fixtures/problems/edit-conflict.json+++ b/protocols/host/fixtures/problems/edit-conflict.json@@ -38,9 +38,9 @@"app_title": "Forecasts"},"policy": "autorun",- "etag": "82eabd9627d6bdf4",- "saved_etag": "0129d119bfb96bf9",- "order_etag": "389ebf709589e5d6",+ "etag": "949c0dd20bc77042",+ "saved_etag": "e59d9c2af02f5814",+ "order_etag": "162e15055422ed71","app_config_etag": "1d79ec53fdad1a23"}}diff --git a/protocols/host/openapi.yaml b/protocols/host/openapi.yamlindex d19c2e47db..ef1b779b78 100644--- a/protocols/host/openapi.yaml+++ b/protocols/host/openapi.yaml@@ -1368,7 +1368,7 @@ components:description: Identifies the document as last written to the host's store, computed the same way over that state. Equal to `etag` when every accepted change has been persisted. Null when nothing has been persisted, which is the case for a scratch copy.order_etag:$ref: '#/components/schemas/Etag'- description: Identifies the order alone. Its text is the cell ids in order. Editing a cell does not change it.+ description: Identifies the order alone. Its text is the cell IDs in order as a JSON array, with no whitespace and strings carrying only the escapes JSON requires. Editing a cell does not change it.app_config_etag:$ref: '#/components/schemas/Etag'description: Identifies the app config alone. Its text is the app config as canonical JSON, with keys sorted by code point, no whitespace, and strings carrying only the escapes JSON requires.diff --git a/tests/_core/conftest.py b/tests/_core/conftest.pyindex 79b686ec1d..5c871002bd 100644--- a/tests/_core/conftest.py+++ b/tests/_core/conftest.py@@ -3,13 +3,17 @@from __future__ import annotations+from copy import deepcopy+import pytestfrom marimo._core import backend as be, protocol+from marimo._core.document import Analyzer, Document, code_hash+from marimo._core.executions import CellExecution, Executionsfrom marimo._core.host import Host-from marimo._core.notebook import Notebook+from marimo._core.notebook import CellSnapshot, Notebook, NotebookSnapshotfrom marimo._core.run_log import RetentionPolicy-from marimo._core.stream import Event+from marimo._core.stream import Event, Sink, StreamOPERATIONS = ["notebook.create", "runtime.start", "runtime.run"]@@ -66,6 +70,93 @@ def record()+def make_notebook(+ record: protocol.Notebook,+ sink: Sink,+ backend: ScriptedBackend | None = None,+ *,+ document: Document | None = None,+) -> Notebook:+ return Notebook(+ document or Document(record.id, [], {}),+ Executions(),+ backend or ScriptedBackend(),+ sink,+ )+++def snapshot_of(+ document: Document,+ executions: dict[str, CellExecution] | None = None,+) -> NotebookSnapshot:+ """A snapshot of the document with executions retained by cell id."""+ return NotebookSnapshot(+ document._record,+ tuple(+ CellSnapshot(cell, (executions or {}).get(cell.id))+ for cell in document+ ),+ )+++def capture(notebook: Notebook) -> NotebookSnapshot:+ """The snapshot a host would prepare from the notebook's state."""+ return deepcopy(+ NotebookSnapshot(+ notebook.document._record,+ tuple(+ CellSnapshot(cell, notebook.executions.current(cell.id))+ for cell in notebook.document+ ),+ )+ )+++def restore(+ snapshot: NotebookSnapshot,+ backend: ScriptedBackend | None = None,+ *,+ analyzer: Analyzer | None = None,+ sink: Sink | None = None,+) -> Notebook:+ """Build a notebook from a snapshot, one core at a time."""+ document = Document.from_records(+ snapshot.document,+ [entry.cell for entry in snapshot.cells],+ analyzer=analyzer,+ )+ executions = Executions.restore(+ {+ entry.cell.id: entry.execution+ for entry in snapshot.cells+ if entry.execution is not None+ },+ cells=document,+ )+ return Notebook(+ document,+ executions,+ backend or ScriptedBackend(),+ sink if sink is not None else Stream(history=0),+ )+++async def add_notebook(+ host: Host,+ record: protocol.Notebook,+ backend: ScriptedBackend,+ *,+ document: Document | None = None,+) -> Notebook:+ host.add_notebook(+ record,+ lambda current, sink: make_notebook(+ current, sink, backend, document=document+ ),+ )+ return await host.notebook(record.id)++@pytest.fixturedef host() -> Host:return Host(operations=OPERATIONS)@@ -77,9 +168,9 @@ def backend() -> ScriptedBackend:@pytest.fixture-def notebook(host: Host, backend: ScriptedBackend) -> Notebook:+async def notebook(host: Host, backend: ScriptedBackend) -> Notebook:host.update_project(project())- return host.add_notebook(record(), backend)+ return await add_notebook(host, record(), backend)@pytest.fixture@@ -105,7 +196,7 @@ class Clock:return self.now-def host_at(clock: Clock, history: int = 1000) -> tuple[Host, Notebook]:+async def host_at(clock: Clock, history: int = 1000) -> tuple[Host, Notebook]:host = Host(operations=[],history=history,@@ -113,7 +204,7 @@ def host_at(clock: Clock, history: int = 1000) -> tuple[Host, Notebook]:retention=RetentionPolicy(ephemeral_seconds=10),)host.update_project(project())- notebook = host.add_notebook(record(), ScriptedBackend())+ notebook = await add_notebook(host, record(), ScriptedBackend())notebook.adopt(lambda _: None)notebook.observe(be.Running(runtime_id_of(notebook)))return host, notebook@@ -161,3 +252,38 @@ def fold(events: list[Event], initial: dict | None = None) -> dict:body = getattr(event.data, event.kind)state[event.kind, body.id] = bodyreturn state+++def retained_execution(+ cell_id: str | None = "c1", run_id: str | None = None+) -> CellExecution:+ """A completed execution with one console item, as a store retains it."""+ execution_id = protocol.ExecutionId("restored")+ return CellExecution(+ protocol.Execution(+ id=execution_id,+ run_id=None if run_id is None else protocol.RunId(run_id),+ runtime_id=None,+ caused_by=None,+ cell_id=None if cell_id is None else protocol.CellId(cell_id),+ code="42" if cell_id is None else None,+ code_hash=code_hash("42"),+ bindings=(),+ status="completed",+ outcome=protocol.ValueOutcome(+ protocol.DisplayData(mimetype="text/plain", data="42")+ ),+ stale=False if cell_id is not None else None,+ started_at=None,+ completed_at=None,+ ),+ (+ protocol.Console(+ execution_id,+ protocol.ItemId("restored-output"),+ "stdout",+ 0,+ "hello",+ ),+ ),+ )diff --git a/tests/_core/test_executions.py b/tests/_core/test_executions.pyindex ab6c9a0611..f30d162532 100644--- a/tests/_core/test_executions.py+++ b/tests/_core/test_executions.py@@ -4,11 +4,20 @@from __future__ import annotationsimport pytest+from msgspec.structs import replacefrom marimo._core import backend as be, protocol+from marimo._core.document import CellSource, Documentfrom marimo._core.errors import NoRuntime-from marimo._core.executions import Change, Executions, Released, Removed+from marimo._core.executions import (+ CellExecution,+ Change,+ Executions,+ Released,+ Removed,+)from marimo._core.stream import kind_of, utcnow+from tests._core.conftest import retained_executionNOTEBOOK = protocol.NotebookId("n1")RUNTIME = protocol.Runtime(@@ -233,6 +242,92 @@ def test_planning_does_not_scan_unrelated_cells(assert sum(isinstance(c, protocol.Execution) for c in changes) == 1000+def test_removing_a_cell_drops_its_result_or_disowns_active_work() -> None:+ executions = Executions()+ executions.begin(run("r1"), "request")+ executions.observe(planned("r1", ("e1", "a"), ("e2", "b")), RUNTIME)+ complete(executions, "e1")+ executions.observe(+ be.Status(protocol.ExecutionId("e2"), "running"), RUNTIME+ )+ assert describe(executions.remove_cell(protocol.CellId("a"))) == [+ "execution.removed e1"+ ]+ # Active work stays tracked, but no longer belongs to a cell.+ assert executions.remove_cell(protocol.CellId("b")) == []+ assert executions.remove_cell(protocol.CellId("never")) == []+ assert executions.current(protocol.CellId("b")) is None+ complete(executions, "e2")+ done = executions.observe(+ be.Done(protocol.RunId("r1"), "succeeded"), RUNTIME+ )+ assert describe(done) == ["run r1", "execution.removed e2", "released r1"]+++def test_restored_executions_are_current_until_replaced() -> None:+ document = Document(NOTEBOOK, [CellSource("c1", "42")], {})+ retained = retained_execution(run_id="old-run")+ executions = Executions.restore(+ {protocol.CellId("c1"): retained}, cells=document+ )+ assert executions.current(protocol.CellId("c1")) == retained+ assert describe(executions._records()) == [+ "execution restored",+ "console restored-output",+ ]+ executions.begin(run("r1"), "request")+ changes = executions.observe(planned("r1", ("e1", "c1")), RUNTIME)+ assert describe(changes) == [+ "console.removed restored-output",+ "execution.removed restored",+ "execution e1",+ ]+ assert executions.current(protocol.CellId("c1")) is None+++ ("invalid", "message"),+ [+ ("scratch", "containing cell"),+ ("other-cell", "containing cell"),+ ("missing-cell", "not in the document"),+ ("unfinished", "completed"),+ ("no-outcome", "outcome"),+ ("output-owner", "belong to their execution"),+ ("duplicate-output", "unique"),+ ],+)+def test_restore_rejects_inconsistent_executions(+ invalid: str, message: str+) -> None:+ document = Document(NOTEBOOK, [CellSource("c1", "42")], {})+ retained = retained_execution()+ execution, outputs = retained.execution, retained.outputs+ key = protocol.CellId("c1")+ if invalid == "scratch":+ retained = retained_execution(cell_id=None, run_id="previous-run")+ elif invalid == "other-cell":+ retained = CellExecution(+ replace(execution, cell_id=protocol.CellId("c2")), outputs+ )+ elif invalid == "missing-cell":+ key = protocol.CellId("missing")+ retained = CellExecution(replace(execution, cell_id=key), outputs)+ elif invalid == "unfinished":+ retained = CellExecution(replace(execution, status="running"), outputs)+ elif invalid == "no-outcome":+ retained = CellExecution(replace(execution, outcome=None), outputs)+ elif invalid == "output-owner":+ retained = CellExecution(+ execution,+ (replace(outputs[0], execution_id=protocol.ExecutionId("other")),),+ )+ else:+ retained = CellExecution(execution, outputs * 2)+ with pytest.raises(ValueError, match=message):+ Executions.restore({key: retained}, cells=document)++def test_current_result_keeps_its_outputs_as_the_execution_changes() -> None:executions = Executions()cell_id = protocol.CellId("a")diff --git a/tests/_core/test_host.py b/tests/_core/test_host.pyindex 4633f4d8f0..ab99ae03ba 100644--- a/tests/_core/test_host.py+++ b/tests/_core/test_host.py@@ -3,6 +3,7 @@from __future__ import annotations+import asynciofrom typing import TYPE_CHECKINGimport pytest@@ -12,13 +13,15 @@ from msgspec.structs import replacefrom marimo._core import backend as be, protocolfrom marimo._core.errors import NotFoundfrom marimo._core.host import Host-from marimo._core.stream import Event+from marimo._core.stream import Event, Sinkfrom tests._core.conftest import (Clock,ScriptedBackend,+ add_notebook,finish,fold,host_at,+ make_notebook,names,plan,project,@@ -94,9 +97,9 @@ def test_replacing_a_cell_result_updates_history_before_delivery(assert snapshots == [{("run", replacement.id), ("execution", "new")}]-def test_catalog_snapshot_and_replay_exclude_runs(host: Host) -> None:+async def test_catalog_snapshot_and_replay_exclude_runs(host: Host) -> None:host.update_project(project())- notebook = host.add_notebook(record(), ScriptedBackend())+ notebook = await add_notebook(host, record(), ScriptedBackend())notebook.start()notebook.observe(be.Running(runtime_id_of(notebook)))run = notebook.run("1", request_id="r1")@@ -126,10 +129,10 @@ def test_catalog_snapshot_and_replay_exclude_runs(host: Host) -> None:assert names(host.events(cursor)) == ["attachment", "ready"]-def test_a_notebook_stream_sees_only_its_notebook(host: Host) -> None:+async def test_a_notebook_stream_sees_only_its_notebook(host: Host) -> None:host.update_project(project())- first = host.add_notebook(record("n1", "a.py"), ScriptedBackend())- second = host.add_notebook(record("n2", "b.py"), ScriptedBackend())+ first = await add_notebook(host, record("n1", "a.py"), ScriptedBackend())+ second = await add_notebook(host, record("n2", "b.py"), ScriptedBackend())first.start()first.observe(be.Running(runtime_id_of(first)))run = first.run("1", request_id="r1")@@ -144,6 +147,7 @@ def test_a_notebook_stream_sees_only_its_notebook(host: Host) -> None:events = host.events(notebook_id="n1")assert names(events) == ["notebook",+ "document","runtime","run","execution",@@ -155,6 +159,7 @@ def test_a_notebook_stream_sees_only_its_notebook(host: Host) -> None:live = host.events(0, notebook_id="n1")assert names(live) == ["notebook",+ "document","runtime","runtime","run",@@ -167,10 +172,10 @@ def test_a_notebook_stream_sees_only_its_notebook(host: Host) -> None:host.events(notebook_id="n3")-def test_resume_replays_or_resets() -> None:+async def test_resume_replays_or_resets() -> None:small = Host(operations=[], history=2)small.update_project(project())- small.add_notebook(record(), ScriptedBackend())+ await add_notebook(small, record(), ScriptedBackend())cursor = small.events()[-1].idassert cursor is not None@@ -183,9 +188,9 @@ def test_resume_replays_or_resets() -> None:assert names(small.events(10**6))[0] == "reset"-def test_types_filter_keeps_ready_and_reset(host: Host) -> None:+async def test_types_filter_keeps_ready_and_reset(host: Host) -> None:host.update_project(project())- host.add_notebook(record(), ScriptedBackend())+ await add_notebook(host, record(), ScriptedBackend())assert names(host.events(types={"notebook"})) == ["notebook", "ready"]assert names(host.events(10**6, types={"notebook"})) == ["reset",@@ -194,9 +199,9 @@ def test_types_filter_keeps_ready_and_reset(host: Host) -> None:]-def test_subscribe_filters_the_live_stream(host: Host) -> None:+async def test_subscribe_filters_the_live_stream(host: Host) -> None:host.update_project(project())- notebook = host.add_notebook(record(), ScriptedBackend())+ notebook = await add_notebook(host, record(), ScriptedBackend())catalog: list[Event] = []mine: list[Event] = []runtimes: list[Event] = []@@ -215,9 +220,11 @@ def test_subscribe_filters_the_live_stream(host: Host) -> None:assert names(runtimes) == ["runtime", "runtime"]-def test_removing_a_notebook_removes_what_it_owns_first(host: Host) -> None:+async def test_removing_a_notebook_removes_what_it_owns_first(+ host: Host,+) -> None:host.update_project(project())- notebook = host.add_notebook(record(), ScriptedBackend())+ notebook = await add_notebook(host, record(), ScriptedBackend())notebook.start()notebook.observe(be.Running(runtime_id_of(notebook)))notebook.attach()@@ -237,14 +244,14 @@ def test_removing_a_notebook_removes_what_it_owns_first(host: Host) -> None:assert getattr(log[-1].data, "request_id", None) == "req-del"assert "n1" not in host.notebookswith pytest.raises(NotFound):- host.notebook(notebook.id)+ (await host.notebook(notebook.id))host.remove_notebook("n1") # Repeated removal is a no-op.-def test_updating_a_notebook_publishes_only_changes(host: Host) -> None:+async def test_updating_a_notebook_publishes_only_changes(host: Host) -> None:host.update_project(project())backend = ScriptedBackend()- notebook = host.add_notebook(record(), backend)+ notebook = await add_notebook(host, record(), backend)notebook.start()notebook.observe(be.Running(runtime_id_of(notebook)))run = notebook.run("1", request_id="run")@@ -259,7 +266,7 @@ def test_updating_a_notebook_publishes_only_changes(host: Host) -> None:host.update_notebook(moved, request_id="req-mv")assert host.notebooks[notebook.id] == moved- assert host.notebook("n1") is notebook+ assert (await host.notebook("n1")) is notebookassert notebook.runtime is runtimeassert backend.calls == []assert host.events(notebook_id="n1", types={"run"})[@@ -322,16 +329,18 @@ def test_removed_notebook_handles_cannot_be_reused(assert notebook.runtime is None-def test_catalog_requires_the_project(host: Host) -> None:+async def test_catalog_requires_the_project(host: Host) -> None:with pytest.raises(ValueError, match="project"):- host.add_notebook(record(), ScriptedBackend())+ await add_notebook(host, record(), ScriptedBackend())host.update_project(project())- host.add_notebook(record(), ScriptedBackend())+ await add_notebook(host, record(), ScriptedBackend())with pytest.raises(ValueError, match="already"):- host.add_notebook(record(), ScriptedBackend())+ await add_notebook(host, record(), ScriptedBackend())-def test_catalog_updates_do_not_share_mutable_records(host: Host) -> None:+async def test_catalog_updates_do_not_share_mutable_records(+ host: Host,+) -> None:source = project()host.update_project(source)with pytest.raises(AttributeError):@@ -351,7 +360,7 @@ def test_catalog_updates_do_not_share_mutable_records(host: Host) -> None:]original = record()- host.add_notebook(original, ScriptedBackend())+ await add_notebook(host, original, ScriptedBackend())with pytest.raises(AttributeError):original.name = "caller mutation"original = replace(original, name="caller mutation", operations=())@@ -368,12 +377,121 @@ def test_catalog_updates_do_not_share_mutable_records(host: Host) -> None:)+async def test_initializer_receives_current_record_and_runs_once(+ host: Host,+) -> None:+ host.update_project(project())+ calls = []++ def initialize(current: protocol.Notebook, sink: Sink) -> Notebook:+ calls.append(current)+ return make_notebook(current, sink)++ host.add_notebook(record(), initialize)+ moved = replace(record(), path="renamed.py", name="renamed")+ host.update_notebook(moved)+ assert host.peek_notebook("n1") is None+ assert names(host.events()) == ["host", "project", "notebook", "ready"]+ assert calls == []++ notebook = await host.notebook("n1")+ assert calls == [moved]+ assert await host.notebook("n1") is notebook+ host.update_notebook(replace(moved, name="Another name"))+ assert await host.notebook("n1") is notebook+ assert calls == [moved]+++async def test_concurrent_callers_share_initialization_despite_cancellation(+ host: Host,+) -> None:+ host.update_project(project())+ entered = asyncio.Event()+ release = asyncio.Event()+ calls = []++ async def initialize(current: protocol.Notebook, sink: Sink) -> Notebook:+ calls.append(current)+ entered.set()+ await release.wait()+ return make_notebook(current, sink)++ host.add_notebook(record(), initialize)+ first = asyncio.create_task(host.notebook("n1"))+ await entered.wait()+ second = asyncio.create_task(host.notebook("n1"))+ first.cancel()+ with pytest.raises(asyncio.CancelledError):+ await first+ release.set()+ notebook = await second+ assert calls == [record()]+ assert await host.notebook("n1") is notebook+++async def test_initialization_failure_can_be_retried(host: Host) -> None:+ host.update_project(project())+ attempts = 0++ def initialize(current: protocol.Notebook, sink: Sink) -> Notebook:+ nonlocal attempts+ attempts += 1+ if attempts == 1:+ raise OSError("unreadable")+ return make_notebook(current, sink)++ host.add_notebook(record(), initialize)+ with pytest.raises(OSError, match="unreadable"):+ await host.notebook("n1")+ assert host.peek_notebook("n1") is None+ assert names(host.events(notebook_id="n1")) == ["notebook", "ready"]+ notebook = await host.notebook("n1")+ assert await host.notebook("n1") is notebook+ assert attempts == 2+++async def test_removed_entry_cannot_be_resurrected_by_its_initializer(+ host: Host,+) -> None:+ host.update_project(project())+ entered = asyncio.Event()+ release = asyncio.Event()++ async def initialize(current: protocol.Notebook, sink: Sink) -> Notebook:+ entered.set()+ try:+ await release.wait()+ except asyncio.CancelledError:+ pass # Even a loader that finishes after cancellation cannot register.+ return make_notebook(current, sink)++ host.add_notebook(record(), initialize)+ pending = asyncio.create_task(host.notebook("n1"))+ await entered.wait()+ host.remove_notebook("n1")+ host.add_notebook(record(), make_notebook)+ with pytest.raises(NotFound):+ await pending+ assert host.peek_notebook("n1") is None+ assert (await host.notebook("n1")).id == "n1"+++async def test_initializer_cannot_return_another_notebook(host: Host) -> None:+ host.update_project(project())+ host.add_notebook(+ record(), lambda _, sink: make_notebook(record("n2"), sink)+ )+ with pytest.raises(ValueError, match="catalog id"):+ await host.notebook("n1")+ assert host.peek_notebook("n1") is None++@pytest.mark.parametrize("history", [2, 1000])-def test_expiration_converges_for_live_replay_and_snapshot(+async def test_expiration_converges_for_live_replay_and_snapshot(history: int,) -> None:clock = Clock()- host, notebook = host_at(clock, history)+ host, notebook = await host_at(clock, history)run = notebook.run("code", request_id="request")execution = plan(notebook, run, "e")item = protocol.Console(@@ -436,11 +554,11 @@ def test_expiration_converges_for_live_replay_and_snapshot(assert live == []-def test_cell_results_outlive_ephemeral_members_and_old_runs_are_removed() -> (+async def test_cell_results_outlive_ephemeral_members_and_old_runs_are_removed() -> (None):clock = Clock()- host, notebook = host_at(clock)+ host, notebook = await host_at(clock)run = notebook.run("code", request_id="first")ephemeral = plan(notebook, run, "scratch")cell = plan(notebook, run, "cell", "a")@@ -465,8 +583,10 @@ def test_cell_results_outlive_ephemeral_members_and_old_runs_are_removed() -> (assert set(state) == {("run", replacement.id), ("execution", current)}-def test_run_survives_until_its_last_cell_execution_is_replaced() -> None:- host, notebook = host_at(Clock())+async def test_run_survives_until_its_last_cell_execution_is_replaced() -> (+ None+):+ host, notebook = await host_at(Clock())original = notebook.run("code", request_id="original")first = plan(notebook, original, "first", "a")second = plan(notebook, original, "second", "b")@@ -499,11 +619,11 @@ def test_run_survives_until_its_last_cell_execution_is_replaced() -> None:]-def test_stopping_starts_expiry_for_active_work_without_extending_old_results() -> (+async def test_stopping_starts_expiry_for_active_work_without_extending_old_results() -> (None):clock = Clock()- host, notebook = host_at(clock)+ host, notebook = await host_at(clock)done = notebook.run("code", request_id="done")execution = plan(notebook, done, "done")finish(notebook, execution)@@ -523,9 +643,11 @@ def test_stopping_starts_expiry_for_active_work_without_extending_old_results()assert fold(host.events(notebook_id=notebook.id)) == {}-def test_repeated_expiration_releases_runs_and_request_correlations() -> None:+async def test_repeated_expiration_releases_runs_and_request_correlations() -> (+ None+):clock = Clock()- host, notebook = host_at(clock, history=2)+ host, notebook = await host_at(clock, history=2)for index in range(100):run = notebook.run("code", request_id=f"request-{index}")execution = plan(notebook, run, str(index))@@ -535,14 +657,14 @@ def test_repeated_expiration_releases_runs_and_request_correlations() -> None:host.expire()assert fold(host.events(notebook_id=notebook.id)) == {}assert (- len({call[1] for call in notebook._backend.calls if call[0] == "run"})+ len({call[1] for call in notebook.backend.calls if call[0] == "run"})== 100)-def test_removal_listeners_can_read_snapshots() -> None:+async def test_removal_listeners_can_read_snapshots() -> None:clock = Clock()- host, notebook = host_at(clock)+ host, notebook = await host_at(clock)run = notebook.run("code", request_id="request")execution = plan(notebook, run, "execution")notebook.observe(@@ -564,11 +686,11 @@ def test_removal_listeners_can_read_snapshots() -> None:assert [set(state) for state in snapshots] == [set(), set(), set()]-def test_expiration_does_not_scan_unrelated_outputs(+async def test_expiration_does_not_scan_unrelated_outputs(monkeypatch: pytest.MonkeyPatch,) -> None:clock = Clock()- host, notebook = host_at(clock, history=2)+ host, notebook = await host_at(clock, history=2)run = notebook.run("code", request_id="request")for index in range(1000):execution = plan(notebook, run, str(index))@@ -597,9 +719,9 @@ def test_expiration_does_not_scan_unrelated_outputs(assert fold(host.events(notebook_id=notebook.id)) == {}-def test_completed_scratch_runs_belong_to_the_host() -> None:+async def test_completed_scratch_runs_belong_to_the_host() -> None:clock = Clock()- host, notebook = host_at(clock)+ host, notebook = await host_at(clock)run = notebook.run("code", request_id="request")execution = plan(notebook, run, "scratch")notebook.observe(@@ -622,10 +744,10 @@ def test_completed_scratch_runs_belong_to_the_host() -> None:("execution", execution),("console", "out"),}- assert notebook._backend.calls.count(("forget", run.id)) == 1+ assert notebook.backend.calls.count(("forget", run.id)) == 1with pytest.raises(NotFound):notebook.interrupt(run.id)clock.now = 10host.expire()assert fold(host.events(notebook_id=notebook.id)) == {}- assert notebook._backend.calls.count(("forget", run.id)) == 1+ assert notebook.backend.calls.count(("forget", run.id)) == 1diff --git a/tests/_core/test_notebook.py b/tests/_core/test_notebook.pyindex 4d9ae64c85..f041f29179 100644--- a/tests/_core/test_notebook.py+++ b/tests/_core/test_notebook.py@@ -3,6 +3,8 @@from __future__ import annotations+from copy import deepcopy+import msgspecimport pytestfrom dirty_equals import IsDatetime@@ -11,11 +13,15 @@ from msgspec import UNSETfrom msgspec.structs import replacefrom marimo._core import backend as be+from marimo._core.document import CellSource, Documentfrom marimo._core.errors import Conflict, NoRuntime, NotFound+from marimo._core.executions import CellExecutionfrom marimo._core.host import Hostfrom marimo._core.notebook import Notebookfrom marimo._core.protocol import (+ Analysis,AttachmentMessage,+ CellId,Console,ConsoleMessage,Custom,@@ -43,13 +49,19 @@ from marimo._core.stream import Eventfrom tests._core.conftest import (Clock,ScriptedBackend,+ capture,finish,fold,host_at,names,plan,+ project,+ record,request_ids,+ restore,+ retained_execution,runtime_id_of,+ snapshot_of,)@@ -215,6 +227,7 @@ class TestStop:assert isinstance(interrupted.execution.outcome, InterruptedOutcome)assert names(host.events(notebook_id=notebook.id)) == ["notebook",+ "document","run","execution","console",@@ -261,6 +274,7 @@ class TestStop:assert request_ids(log) == ["stop", "stop"]assert names(host.events(notebook_id=notebook.id)) == ["notebook",+ "document","run","execution","console",@@ -401,6 +415,7 @@ class TestAdoption:assert notebook.runtime.marimo_version == "0.26.0"assert names(host.events(notebook_id=notebook.id)) == ["notebook",+ "document","runtime","run","execution",@@ -1028,11 +1043,11 @@ def _attachment_ids(notebook: Notebook) -> set[str]:@pytest.mark.parametrize("cleanup", ["expire", "replace", "clear"])-def test_outputs_follow_their_execution_through_updates_and_removal(+async def test_outputs_follow_their_execution_through_updates_and_removal(cleanup: str,) -> None:clock = Clock()- host, notebook = host_at(clock)+ host, notebook = await host_at(clock)run = notebook.run("code", request_id="request")first = plan(notebook, run, "first", "a" if cleanup != "expire" else None)second = plan(@@ -1117,3 +1132,201 @@ def test_outputs_follow_their_execution_through_updates_and_removal(for event, state in zip(live, snapshots, strict=True)if event.name.endswith(".removed"))++[email protected]("run_id", [None, "previous-run"])+async def test_initial_results_are_published_and_replaced_by_live_execution(+ run_id: str | None,+) -> None:+ retained = retained_execution(run_id=run_id)+ snapshot = snapshot_of(+ Document(record().id, [CellSource("c1", "42")], {}),+ {"c1": retained},+ )+ host = Host(operations=[])+ host.update_project(project())+ host.add_notebook(record(), lambda _, sink: restore(snapshot, sink=sink))+ live: list[Event] = []+ host.subscribe(live.append, notebook_id=record().id)+ notebook = await host.notebook(record().id)+ assert notebook.runtime is None+ expected = {+ ("execution", retained.execution.id): retained.execution,+ ("console", retained.outputs[0].id): retained.outputs[0],+ }+ assert fold(live) == fold(host.events(notebook_id=notebook.id)) == expected+ assert names(live) == ["cell", "document", "execution", "console"]++ notebook.start()+ notebook.observe(be.Running(runtime_id_of(notebook)))+ run = notebook.run("42", request_id="run")+ execution_id = plan(notebook, run, "new", cell="c1")+ state = fold(host.events(notebook_id=notebook.id))+ assert set(state) == {("run", run.id), ("execution", execution_id)}+ assert fold(live) == state+++async def test_current_cell_results_can_seed_another_notebook() -> None:+ _, notebook = await host_at(Clock())+ notebook.replace([CellSource("c1", "code")], {})+ run = notebook.run("code", request_id="request")+ execution = plan(notebook, run, "cell", "c1")+ notebook.observe(+ be.Produced(Console(execution, ItemId("out"), "stdout", 0, "x"))+ )+ finish(notebook, execution)+ notebook.observe(be.Done(run.id, "succeeded"))+ snapshot = capture(notebook)+ restored = restore(snapshot)+ assert capture(restored) == snapshot+ assert fold(restored._snapshot()) == {+ key: value+ for key, value in fold(notebook._snapshot()).items()+ if key[0] != "run"+ }++[email protected]("saved", [False, True])+def test_snapshot_round_trip_preserves_revisions_outputs_and_analysis(+ saved: bool,+) -> None:+ document = Document(+ record().id,+ [CellSource("c1", "42")],+ {"width": "full"},+ policy="lazy",+ saved=saved,+ analyzer=lambda _: {"c1": Analysis(defs=(), refs=(), errors=())},+ )+ # The output belongs to the previous source, and the saved revision can+ # precede the current one. Neither is rewritten during restoration.+ document.replace([CellSource("c1", "43")], {"width": "full"})+ seed = retained_execution(run_id="historical-run")+ retained = CellExecution(+ seed.execution,+ (+ *seed.outputs,+ Display(+ execution_id=seed.execution.id,+ id=ItemId("display"),+ seq=1,+ mimetype="application/json",+ data='{"values": [1, 2]}',+ ),+ replace(seed.outputs[0], id=ItemId("last"), seq=2),+ ),+ )+ snapshot = snapshot_of(document, {"c1": retained})+ original = deepcopy(snapshot)+ backend = ScriptedBackend()+ notebook = restore(snapshot, backend)+ assert capture(notebook) == original+ assert capture(restore(capture(notebook), backend)) == original+ assert backend.calls == []+ outputs = [+ e for e in notebook._snapshot() if e.kind in ("console", "display")+ ]+ assert [getattr(e.data, e.kind).seq for e in outputs] == [0, 1, 2]+ # Restoration copies its input, and capture returns detached data.+ snapshot.document.app_config["width"] = "medium"+ capture(notebook).document.app_config["width"] = "columns"+ assert capture(notebook) == original+++async def test_edits_preserve_results_and_deletion_removes_them() -> None:+ retained = retained_execution()+ snapshot = snapshot_of(+ Document(record().id, [CellSource("c1", "42")], {}),+ {"c1": retained},+ )+ host = Host(operations=[])+ host.update_project(project())+ host.add_notebook(record(), lambda _, sink: restore(snapshot, sink=sink))+ notebook = await host.notebook(record().id)+ notebook.replace([CellSource("c1", "43")], {})+ assert notebook.executions.current(CellId("c1")) == retained+ assert (+ next(iter(notebook.document)).code_hash != retained.execution.code_hash+ )+ live: list[Event] = []+ host.subscribe(live.append, notebook_id=notebook.id)+ notebook.replace([], {})+ assert capture(notebook).cells == ()+ assert fold(host.events(notebook_id=notebook.id)) == {}+ assert names(live) == [+ "console.removed",+ "execution.removed",+ "cell.removed",+ "document",+ ]+++async def test_snapshot_excludes_live_work_and_cleans_up_deleted_active_cells() -> (+ None+):+ _, notebook = await host_at(Clock())+ notebook.replace([CellSource("c1", "code")], {})+ notebook.attach()+ run = notebook.run("code", request_id="request")+ execution = plan(notebook, run, "active", "c1")+ notebook.observe(+ be.Produced(Console(execution, ItemId("out"), "stdout", 0, "x"))+ )+ snapshot = capture(notebook)+ assert snapshot.cells[0].execution is None+ restored = restore(snapshot)+ assert names(restored._snapshot()) == ["cell", "document"]+ notebook.replace([], {})+ finish(notebook, execution)+ notebook.observe(be.Done(run.id, "succeeded"))+ assert capture(notebook).cells == ()+ assert fold(notebook._snapshot()) == {}+++async def test_source_edits_keep_live_results_until_the_cell_is_deleted() -> (+ None+):+ host, notebook = await host_at(Clock())+ notebook.replace([CellSource("c1", "42")], {})+ run = notebook.run("42", request_id="run")+ execution = plan(notebook, run, "result", "c1")+ notebook.observe(+ be.Produced(Console(execution, ItemId("out"), "stdout", 0, "hello"))+ )+ finish(notebook, execution)+ notebook.observe(be.Done(run.id, "succeeded"))+ retained = notebook.executions._records()++ notebook.replace([CellSource("c1", "43")], {})+ assert notebook.executions._records() == retained++ live: list[Event] = []+ host.subscribe(live.append, notebook_id=notebook.id)+ notebook.replace([], {})+ assert list(notebook.document) == []+ assert fold(host.events(notebook_id=notebook.id)) == {}+ assert names(live) == [+ "console.removed",+ "execution.removed",+ "run.removed",+ "cell.removed",+ "document",+ ]+++async def test_deleting_an_active_cell_releases_its_result_when_the_run_ends() -> (+ None+):+ host, notebook = await host_at(Clock())+ notebook.replace([CellSource("c1", "42")], {})+ run = notebook.run("42", request_id="run")+ execution = plan(notebook, run, "result", "c1")+ notebook.replace([], {})+ notebook.observe(+ be.Produced(Console(execution, ItemId("out"), "stdout", 0, "hello"))+ )+ finish(notebook, execution)+ notebook.observe(be.Done(run.id, "succeeded"))+ assert list(notebook.document) == []+ assert fold(notebook._snapshot()) == {}+ assert fold(host.events(notebook_id=notebook.id)) == {}diff --git a/tests/_core/test_notebook_document.py b/tests/_core/test_notebook_document.pynew file mode 100644index 0000000000..c47702f5c1--- /dev/null+++ b/tests/_core/test_notebook_document.py@@ -0,0 +1,339 @@+# Copyright 2026 Marimo. All rights reserved.+"""The document's etags, change reporting, and publication order."""++from __future__ import annotations++from typing import TYPE_CHECKING++import pytest+from msgspec.structs import replace++from marimo._core import protocol+from marimo._core.document import (+ CellSource,+ Document,+ app_config_etag,+ cell_etag,+ code_hash,+ document_etag,+ order_etag,+)+from marimo._core.host import Host+from marimo._core.notebook import Notebook+from marimo._core.stream import Event+from tests._core.conftest import make_notebook, names, project, record++if TYPE_CHECKING:+ from collections.abc import Mapping++NOTEBOOK = protocol.NotebookId("n1")+HIDDEN = protocol.CellConfig(+ column=None, disabled=False, hide_code=True, expand_output=False+)+++def fixture_cells() -> list[CellSource]:+ """The cells in pair's `notebook-events.sse` fixture."""+ return [+ CellSource("c1", "import marimo as mo"),+ CellSource("c3", "x = 21"),+ CellSource("k7f2", "y = x * 2", config=HIDDEN),+ ]+++def defs_only(codes: Mapping[str, str]) -> dict[str, protocol.Analysis]:+ """An analyzer that reports an error on every cell defining `x`."""+ out = {}+ definers = [cell_id for cell_id, code in codes.items() if "x =" in code]+ for cell_id, code in codes.items():+ errors = []+ if cell_id in definers and len(definers) > 1:+ errors.append(+ protocol.Error(+ kind="multiple-definitions",+ message="x is defined twice",+ source="marimo",+ severity="error",+ range=None,+ name=None,+ traceback=None,+ related=[],+ )+ )+ out[cell_id] = protocol.Analysis(+ defs=[code.split(" =")[0]] if " =" in code else [],+ refs=[],+ errors=errors,+ )+ return out+++class TestEtags:+ def test_reordering_cell_ids_with_newlines_changes_the_revision(+ self,+ ) -> None:+ cells = [CellSource("a", "x = 1"), CellSource("a\na", "x = 1")]+ document = Document(NOTEBOOK, cells, {})+ before = document._record++ document.replace(list(reversed(cells)), {})++ assert [cell.id for cell in document] == ["a\na", "a"]+ assert document._record.order_etag != before.order_etag+ assert document._record.etag != before.etag+ assert document._record.saved_etag == before.etag++ def test_match_the_values_pinned_in_the_fixtures(self) -> None:+ document = Document(NOTEBOOK, fixture_cells(), {"width": "full"})++ c1, c3, k7f2 = document+ assert (c3.code_hash, c3.etag) == (+ "0f71456db2ea83f4",+ "5cf78587dcf22d8d",+ )+ assert (k7f2.code_hash, k7f2.etag) == (+ "db2b9ee97e1ecf4c",+ "f199b5f48ae0aabb",+ )+ assert c1.etag == "48d6363150d6281c"+ assert document._record.order_etag == "b9c412c2d7d63161"+ assert document._record.app_config_etag == "283513048dfeb45b"+ assert document._record.etag == "e59d9c2af02f5814"+ assert document._record.saved_etag == "e59d9c2af02f5814"++ def test_are_derived_from_their_parts(self) -> None:+ hashed = code_hash("x = 21")+ assert cell_etag(hashed, "_", HIDDEN) != cell_etag(+ hashed,+ "_",+ protocol.CellConfig(+ column=None,+ disabled=False,+ hide_code=False,+ expand_output=False,+ ),+ )+ assert cell_etag(hashed, "named", HIDDEN) != cell_etag(+ hashed, "_", HIDDEN+ )+ assert order_etag(["a", "b"]) != order_etag(["b", "a"])+ assert app_config_etag({"b": 1, "a": 2}) == app_config_etag(+ {"a": 2, "b": 1}+ )+ assert document_etag(+ order_etag(["a"]), app_config_etag({}), [hashed]+ ) != (document_etag(order_etag(["a"]), app_config_etag({}), []))++ def test_normalizes_line_endings_before_hashing(self) -> None:+ document = Document(NOTEBOOK, [CellSource("a", "x = 1\r\ny = 2")], {})+ (cell,) = document+ assert cell.code == "x = 1\ny = 2"+ assert cell.code_hash == code_hash("x = 1\ny = 2")+++class TestReplace:+ def test_reports_new_changed_and_removed_cells(self) -> None:+ document = Document(NOTEBOOK, fixture_cells(), {"width": "full"})+ before = document._record++ changed = document.replace(+ [+ CellSource("c1", "import marimo as mo"),+ CellSource("new", "z = 3"),+ CellSource("k7f2", "y = x * 3", config=HIDDEN),+ ],+ {"width": "full"},+ )++ assert [cell.id for cell in changed.cells] == ["new", "k7f2"]+ assert changed.removed == ["c3"]+ assert changed.document is not None+ assert changed.document.order == ("c1", "new", "k7f2")+ assert changed.document.order_etag != before.order_etag+ assert changed.document.app_config_etag == before.app_config_etag+ assert changed.document.saved_etag == before.etag++ def test_a_change_that_changes_nothing_reports_nothing(self) -> None:+ document = Document(NOTEBOOK, fixture_cells(), {"width": "full"})++ assert not document.replace(fixture_cells(), {"width": "full"})++ def test_an_app_config_change_moves_only_its_etag(self) -> None:+ document = Document(NOTEBOOK, fixture_cells(), {})+ before = document._record++ changed = document.replace(fixture_cells(), {"width": "full"})++ assert changed.cells == []+ assert changed.removed == []+ assert changed.document is not None+ assert changed.document.order_etag == before.order_etag+ assert changed.document.app_config_etag != before.app_config_etag+ assert changed.document.etag != before.etag++ def test_rejects_duplicate_ids(self) -> None:+ with pytest.raises(ValueError, match="unique"):+ Document(+ NOTEBOOK, [CellSource("a", "1"), CellSource("a", "2")], {}+ )++ def test_marks_saved_state_separately(self) -> None:+ document = Document(NOTEBOOK, fixture_cells(), {}, saved=False)+ assert document._record.saved_etag is None++ document.replace([CellSource("c1", "1")], {})+ saved = document.mark_saved()++ assert saved is not None+ assert saved.saved_etag == saved.etag+ assert document.mark_saved() is None++ # A store may hold a revision other than the live one.+ other = Document(NOTEBOOK, fixture_cells(), {}, saved=False)+ behind = other.mark_saved(saved.etag)+ assert behind is not None+ assert behind.saved_etag == saved.etag != behind.etag+++class TestAnalysis:+ def test_reruns_over_the_whole_document(self) -> None:+ document = Document(+ NOTEBOOK,+ [CellSource("a", "x = 1"), CellSource("b", "y = 2")],+ {},+ analyzer=defs_only,+ )+ a, _ = document+ assert a.analysis == protocol.Analysis(defs=["x"], refs=[], errors=[])++ changed = document.replace(+ [CellSource("a", "x = 1"), CellSource("b", "x = 2")], {}+ )++ # Both cells re-emit: b because its code changed, a because its+ # analysis gained an error while its etag stayed put.+ assert [cell.id for cell in changed.cells] == ["a", "b"]+ new_a = changed.cells[0]+ assert new_a.etag == a.etag+ assert new_a.analysis is not None+ assert [e.kind for e in new_a.analysis.errors] == [+ "multiple-definitions"+ ]++ def test_is_null_without_an_analyzer(self) -> None:+ document = Document(NOTEBOOK, fixture_cells(), {})+ assert all(cell.analysis is None for cell in document)+++class TestFromRecords:+ def test_preserves_imported_analysis_and_saved_revision(self) -> None:+ source = Document(+ NOTEBOOK,+ fixture_cells(),+ {"width": "full"},+ policy="lazy",+ analyzer=lambda codes: {+ cell_id: protocol.Analysis(defs=(), refs=(), errors=())+ for cell_id in codes+ },+ )+ # The saved revision precedes the current one; both survive.+ source.replace([CellSource("c1", "import marimo")], {"width": "full"})+ restored = Document.from_records(source._record, list(source))+ assert restored._record == source._record+ assert list(restored) == list(source)+ assert next(iter(restored)).analysis is not None++ @pytest.mark.parametrize(+ "invalid", ["order", "notebook-id", "cell-etag", "document-etag"]+ )+ def test_rejects_inconsistent_records(self, invalid: str) -> None:+ source = Document(NOTEBOOK, fixture_cells(), {})+ document, cells = source._record, list(source)+ if invalid == "order":+ document = replace(document, order=())+ elif invalid == "notebook-id":+ cells[0] = replace(+ cells[0], notebook_id=protocol.NotebookId("other")+ )+ elif invalid == "cell-etag":+ cells[0] = replace(cells[0], code="different source")+ else:+ document = replace(document, app_config={"width": "full"})+ with pytest.raises(ValueError):+ Document.from_records(document, cells)++ def test_analyzer_is_injected_for_restoration_and_later_edits(+ self,+ ) -> None:+ observed: list[dict[str, str]] = []++ def analyze(codes: Mapping[str, str]) -> dict[str, protocol.Analysis]:+ observed.append(dict(codes))+ return {+ cell_id: protocol.Analysis(defs=(), refs=(), errors=())+ for cell_id in codes+ }++ source = Document(NOTEBOOK, [CellSource("c1", "42")], {})+ document = Document.from_records(+ source._record, list(source), analyzer=analyze+ )+ document.replace([CellSource("c1", "43")], {})+ assert observed == [{"c1": "42"}, {"c1": "43"}]+ assert next(iter(document)).analysis is not None+++class TestNotebook:+ async def test_initialization_publishes_cells_then_the_document(+ self, host: Host, log: list[Event]+ ) -> None:+ host.update_project(project())+ host.add_notebook(+ record(),+ lambda record, sink: make_notebook(+ record,+ sink,+ document=Document(+ NOTEBOOK, fixture_cells(), {"width": "full"}+ ),+ ),+ )+ log.clear()+ await host.notebook(NOTEBOOK)++ assert names(log) == ["cell", "cell", "cell", "document"]+ snapshot = host.events(notebook_id="n1")+ assert names(snapshot) == [+ "notebook",+ "cell",+ "cell",+ "cell",+ "document",+ "ready",+ ]+ assert names(host.events(notebook_id="n1", types={"document"})) == [+ "document",+ "ready",+ ]+ # The catalog does not carry the document.+ assert "cell" not in names(host.events())++ def test_replace_publishes_what_changed(+ self, notebook: Notebook, log: list[Event]+ ) -> None:+ notebook.replace(fixture_cells(), {})+ log.clear()++ notebook.replace(+ [+ CellSource("c1", "import marimo as mo"),+ CellSource("c3", "x = 22"),+ ],+ {},+ request_id="edit-1",+ )++ assert names(log) == ["cell", "cell.removed", "document"]+ assert all(e.data.request_id == "edit-1" for e in log) # type: ignore[union-attr]+ assert log[1].data.id == "k7f2" # type: ignore[union-attr]diff --git a/tests/_core/test_protocol.py b/tests/_core/test_protocol.pyindex d3bb582005..d8f4c6fe4d 100644--- a/tests/_core/test_protocol.py+++ b/tests/_core/test_protocol.py@@ -99,7 +99,7 @@ def assert_content_hashes(value: Any) -> None:assert value["etag"] == content_hash("\n".join(parts))if "order_etag" in value:assert value["order_etag"] == content_hash(- "\n".join(value["order"])+ canonical_json(value["order"]))assert value["app_config_etag"] == content_hash(canonical_json(value["app_config"])diff --git a/tests/_server/host/conftest.py b/tests/_server/host/conftest.pyindex d2d18198d7..cdefd250af 100644--- a/tests/_server/host/conftest.py+++ b/tests/_server/host/conftest.py@@ -32,10 +32,15 @@ class FakeSession:self.exit_info: Any = Noneself.app_file_manager = MagicMock()self.app_file_manager.path = path+ self.app_file_manager.app.config.asdict_difference.return_value = {}self.document = MagicMock()self.document.cell_ids = []self.document.cells = []self.session_view = MagicMock()+ self.config_manager = MagicMock()+ self.config_manager.get_config.return_value = {+ "runtime": {"on_cell_change": "autorun"}+ }def connect_consumer(self, consumer: SessionConsumer, *, main: booldiff --git a/tests/_server/host/test_host_analysis.py b/tests/_server/host/test_host_analysis.pynew file mode 100644index 0000000000..a6733fa25e--- /dev/null+++ b/tests/_server/host/test_host_analysis.py@@ -0,0 +1,86 @@+# Copyright 2026 Marimo. All rights reserved.+"""The host's analyzer reports each cell's names and syntax errors."""++from __future__ import annotations++import pytest++from marimo._core import protocol+from marimo._server.host.analysis import Analyzer, analyze+++def test_refs_are_names_other_cells_define() -> None:+ analyses = analyze(+ {+ "a": "import marimo as mo\nprint(len(x))",+ "b": "x = 21",+ "c": "y = x * 2",+ }+ )+ assert analyses["a"].defs == ("mo",)+ assert analyses["a"].refs == ("x",)+ assert analyses["b"] == protocol.Analysis(defs=("x",), refs=(), errors=())+ assert analyses["c"].refs == ("x",)+++def test_a_name_defined_twice_is_a_ref_for_neither_definer() -> None:+ analyses = analyze({"a": "x = 1", "b": "x = 2\ny = x", "c": "z = x"})+ assert analyses["b"].refs == ()+ assert analyses["c"].refs == ("x",)+ # Cross-cell errors come from the kernel at run time for now.+ assert all(analyses[cell_id].errors == () for cell_id in "abc")+++def test_syntax_errors_leave_the_cell_without_names() -> None:+ analyses = analyze({"a": "def (:", "b": "x = 1"})++ (error,) = analyses["a"].errors+ assert error.kind == "invalid-syntax"+ assert error.source == "marimo"+ assert error.range is not None+ assert error.range.start.line == 0+ assert analyses["a"].defs == ()+ assert analyses["a"].refs == ()+ assert analyses["b"].errors == ()+++def test_positions_count_utf16_code_units() -> None:+ analyses = analyze({"a": "s = '😀'; def (:"})++ (error,) = analyses["a"].errors+ assert error.range is not None+ # Python reports the error at `def`, code point 9. The emoji before it+ # is one code point but two UTF-16 units, so LSP sees it at 10.+ assert error.range.start.character == 10+++def test_an_analyzer_kept_between_edits_matches_a_fresh_one() -> None:+ analyzer = Analyzer()+ steps = [+ {"a": "x = 1", "b": "y = x"},+ {"a": "x = 1", "b": "y = x", "c": "x = 2"},+ {"a": "x = 1", "b": "y = x", "c": "z = y"},+ {"a": "x = 1", "b": "y = x\nw = z", "c": "z = y"},+ {"b": "y = x\nw = z", "c": "z = y"},+ {"b": "def (:", "c": "z = y"},+ ]+ for codes in steps:+ assert analyzer(codes) == analyze(codes), codes+++def test_analyzer_retries_after_an_unexpected_compiler_failure(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ analyzer = Analyzer()+ analyzer({"a": "x = 1"})+ codes = {"a": "y = 2", "b": "z = y"}++ def fail(*_args: object, **_kwargs: object) -> None:+ raise RuntimeError("compiler failed")++ with monkeypatch.context() as patch:+ patch.setattr("marimo._server.host.analysis.compile_cell", fail)+ with pytest.raises(RuntimeError, match="compiler failed"):+ analyzer(codes)++ assert analyzer(codes) == analyze(codes)diff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.pyindex 82d4a33b79..4b64c2b822 100644--- a/tests/_server/host/test_host_api.py+++ b/tests/_server/host/test_host_api.py@@ -25,7 +25,7 @@ from marimo._server.host.index import WorkspaceIndexfrom marimo._server.main import create_starlette_appfrom marimo._server.models.home import MarimoFilefrom marimo._server.workspace import FixedFilesWorkspace, SingleFileWorkspace-from tests._core.conftest import ScriptedBackend, runtime_id_of+from tests._core.conftest import ScriptedBackend, make_notebook, runtime_id_offrom tests._server.host.drive import (PORT,finished,@@ -84,17 +84,24 @@ class Harness:body=b"{}",)assert response.status == 202, response.body- self.host.notebook(self.notebook_id).observe(+ (await self.host.notebook(self.notebook_id)).observe(be.Running(- runtime_id_of(self.host.notebook(self.notebook_id)), "0.25.0"+ runtime_id_of(await self.host.notebook(self.notebook_id)),+ "0.25.0",))return self.notebook_id@pytest.fixture-def harness(tmp_path: Path, request: pytest.FixtureRequest) -> Harness:- (tmp_path / "forecasts.py").write_text("import marimo\n")+def harness(+ tmp_path: Path,+ request: pytest.FixtureRequest,+ monkeypatch: pytest.MonkeyPatch,+) -> Harness:+ (tmp_path / "forecasts.py").write_text(+ "import marimo\napp = marimo.App()\n"+ )workspace = FixedFilesWorkspace([MarimoFile(name="forecasts.py", path=str(tmp_path / "forecasts.py"))],directory=str(tmp_path),@@ -111,7 +118,10 @@ def harness(tmp_path: Path, request: pytest.FixtureRequest) -> Harness:harness.backends[notebook_id] = backendreturn backend- bridge.index = WorkspaceIndex(bridge.host, workspace, make)+ monkeypatch.setattr(bridge, "_make_backend", make)+ bridge.index = WorkspaceIndex(+ bridge.host, workspace, bridge._initialize_notebook+ )bridge.index.refresh()app.state.host_context = HostContext(bridge=bridge,@@ -341,7 +351,7 @@ async def test_an_empty_update_is_a_400_problem(harness: Harness) -> None:async def test_head_on_a_stream_is_a_405_and_attaches_nothing(harness: Harness,) -> None:- notebook = harness.host.notebook(harness.notebook_id)+ notebook = await harness.host.notebook(harness.notebook_id)before = len(notebook._attachments)response = await finished(harness.app, "HEAD", f"/notebooks/{notebook.id}/events", headers=AUTH@@ -378,7 +388,7 @@ async def test_the_catalog_stream_sends_a_snapshot_then_changes(assert "id" not in response.records[0]cursor = int(response.records[-1]["id"])- notebook = harness.host.notebook(harness.notebook_id)+ notebook = await harness.host.notebook(harness.notebook_id)notebook.start()await wait_for(response, lambda r: r.names()[-1] == "runtime")live = response.records[-1]@@ -440,7 +450,7 @@ async def test_types_and_cursors_apply_to_the_stream(harness: Harness) -> None:cursor = first.records[-1]["id"]disconnect()- harness.host.notebook(harness.notebook_id).start()+ (await harness.host.notebook(harness.notebook_id)).start()resumed, _, disconnect = request(harness.app,"GET",@@ -458,18 +468,30 @@ async def test_types_and_cursors_apply_to_the_stream(harness: Harness) -> None:async def test_a_notebook_stream_attaches_the_client(harness: Harness) -> None:- notebook = harness.host.notebook(harness.notebook_id)+ notebook = await harness.host.notebook(harness.notebook_id)response, task, disconnect = request(harness.app, "GET", f"/notebooks/{notebook.id}/events", headers=AUTH)await wait_for(response, until_ready)- assert response.names() == ["notebook", "attachment", "ready"]- assert response.records[1]["data"]["attachment"]["kind"] == "client"+ # An empty notebook loads with marimo's one default cell.+ assert response.names() == [+ "notebook",+ "cell",+ "document",+ "attachment",+ "ready",+ ]+ assert response.records[2]["data"]["document"]["order"] == [+ response.records[1]["data"]["cell"]["id"]+ ]+ assert response.records[3]["data"]["attachment"]["kind"] == "client"disconnect()await asyncio.wait_for(task, 5)assert [e.name for e in harness.host.events(notebook_id=notebook.id)] == ["notebook",+ "cell",+ "document","ready",]@@ -557,7 +579,7 @@ async def test_a_reconnect_with_one_identity_attaches_fresh(async def test_custom_events_use_their_own_sse_kind(harness: Harness,) -> None:- notebook = harness.host.notebook(harness.notebook_id)+ notebook = await harness.host.notebook(harness.notebook_id)path = f"/notebooks/{notebook.id}/events"custom, custom_task, disconnect_custom = request(harness.app, "GET", path, headers=AUTH, query="types=custom"@@ -622,19 +644,19 @@ async def test_runtime_lifecycle_over_http(harness: Harness) -> None:assert restart.status == 409assert restart.json()["type"].endswith("/conflict")- harness.host.notebook(nid).observe(- be.Running(runtime_id_of(harness.host.notebook(nid)), "0.25.0")+ (await harness.host.notebook(nid)).observe(+ be.Running(runtime_id_of(await harness.host.notebook(nid)), "0.25.0"))restart = await finished(app, "POST", path + "/restart", headers=key("k4"))assert restart.status == 202assert restart.json()["status"] == "starting"assert restart.json()["id"] != started.json()["id"]- harness.host.notebook(nid).observe(- be.Exited(runtime_id_of(harness.host.notebook(nid)))+ (await harness.host.notebook(nid)).observe(+ be.Exited(runtime_id_of(await harness.host.notebook(nid))))- harness.host.notebook(nid).observe(- be.Running(runtime_id_of(harness.host.notebook(nid)), "0.25.0")+ (await harness.host.notebook(nid)).observe(+ be.Running(runtime_id_of(await harness.host.notebook(nid)), "0.25.0"))stopped = await finished(app, "DELETE", path, headers=key("k5"))assert stopped.status == 202@@ -642,8 +664,8 @@ async def test_runtime_lifecycle_over_http(harness: Harness) -> None:assert stopped.json()["id"] != started.json()["id"]assert stopped.json()["id"] == restart.json()["id"]- harness.host.notebook(nid).observe(- be.Exited(runtime_id_of(harness.host.notebook(nid)))+ (await harness.host.notebook(nid)).observe(+ be.Exited(runtime_id_of(await harness.host.notebook(nid))))gone = await finished(app, "DELETE", path, headers=key("k6"))assert gone.status == 409@@ -652,7 +674,7 @@ async def test_runtime_lifecycle_over_http(harness: Harness) -> None:async def test_slow_restart_keeps_its_receipt(harness: Harness) -> None:nid = await harness.running()- notebook = harness.host.notebook(nid)+ notebook = await harness.host.notebook(nid)path = f"/notebooks/{nid}/runtime/restart"accepted = await finished(harness.app, "POST", path, headers=key("restart")@@ -702,7 +724,7 @@ async def test_lifecycle_receipts_expire_after_terminal_events(nid = harness.notebook_idif operation != "start":await harness.running()- notebook = harness.host.notebook(nid)+ notebook = await harness.host.notebook(nid)context = harness.app.state.host_contextlisteners = list(harness.host._stream._listeners)method = {"start": "PUT", "stop": "DELETE", "restart": "POST"}[operation]@@ -758,7 +780,7 @@ async def test_stop_settles_superseded_lifecycle_receipts(nid = harness.notebook_idif operation != "start":await harness.running()- notebook = harness.host.notebook(nid)+ notebook = await harness.host.notebook(nid)context = harness.app.state.host_contextlisteners = list(harness.host._stream._listeners)path = f"/notebooks/{nid}/runtime"@@ -811,7 +833,7 @@ async def test_synchronous_lifecycle_completion(nid = harness.notebook_idif operation != "start":await harness.running()- notebook = harness.host.notebook(nid)+ notebook = await harness.host.notebook(nid)if operation == "failed-stop":notebook.observe(be.Exited(runtime_id_of(notebook), "failed"))backend = harness.backend()@@ -875,7 +897,7 @@ async def test_noop_and_rejected_lifecycle_requests_release_their_listeners(async def test_run_filter_over_http(harness: Harness) -> None:nid = await harness.running()- notebook = harness.host.notebook(nid)+ notebook = await harness.host.notebook(nid)first = notebook.run("1", request_id="first")notebook.observe(be.Planned(@@ -923,7 +945,7 @@ async def test_interrupting_an_unstarted_run_after_shutdown()assert accepted.status == 202run_id = accepted.json()["id"]- notebook = harness.host.notebook(nid)+ notebook = await harness.host.notebook(nid)runtime_id = runtime_id_of(notebook)notebook.stop()notebook.observe(be.Exited(runtime_id))@@ -968,7 +990,7 @@ async def test_scratch_runs_over_http(harness: Harness) -> None:assert repeated.status == 202assert repeated.body == accepted.bodyassert harness.backend().calls.count(("run", run_id, "3 * 3")) == 1- notebook = harness.host.notebook(nid)+ notebook = await harness.host.notebook(nid)notebook.observe(be.Planned(run_id, (be.PlannedExecution("e1", None, "hash", "3 * 3"),)))@@ -1025,7 +1047,7 @@ async def test_request_receipts_expire_independently_of_results(harness: Harness, cell_id: str | None) -> None:nid = await harness.running()- notebook = harness.host.notebook(nid)+ notebook = await harness.host.notebook(nid)path = f"/notebooks/{nid}/runtime/runs"body = b'{"code":"42"}'accepted = await finished(@@ -1290,7 +1312,7 @@ async def test_open_selects_the_notebook_outside_the_working_directory(async def test_operations_the_host_does_not_offer_are_501(harness: Harness,) -> None:- notebook = harness.host.notebook(harness.notebook_id)+ notebook = await harness.host.notebook(harness.notebook_id)host = Host(operations=[])[project] = [e.data.project@@ -1298,7 +1320,7 @@ async def test_operations_the_host_does_not_offer_are_501(if isinstance(e.data, ProjectMessage)]host.update_project(project)- host.add_notebook(harness.host.notebooks[notebook.id], harness.backend())+ host.add_notebook(harness.host.notebooks[notebook.id], make_notebook)harness.bridge.host = hostresponse = await finished(harness.app,@@ -1380,3 +1402,121 @@ async def test_symlink_escape_has_no_filesystem_side_effects(assert [n.path for n in harness.host.notebooks.values()] == ["forecasts.py"]+++NOTEBOOK = """import marimo++__generated_with = "0.0.0"+app = marimo.App(width="full")+++def _():+ x = 21+ return (x,)++[email protected](hide_code=True)+def _(x):+ y = x * 2+ return+++if __name__ == "__main__":+ app.run()+"""+++async def test_the_notebook_stream_carries_cells_then_the_document(+ harness: Harness,+) -> None:+ (harness.root / "forecasts.py").write_text(NOTEBOOK)+ response, _, disconnect = request(+ harness.app,+ "GET",+ f"/notebooks/{harness.notebook_id}/events",+ headers=AUTH,+ )+ await wait_for(response, until_ready)+ disconnect()++ assert response.names() == [+ "notebook",+ "cell",+ "cell",+ "document",+ "attachment",+ "ready",+ ]+ first, second = (r["data"]["cell"] for r in response.records[1:3])+ document = response.records[3]["data"]["document"]+ assert first["code"] == "x = 21"+ assert first["analysis"] == {"defs": ["x"], "refs": [], "errors": []}+ assert second["code"] == "y = x * 2"+ assert second["config"]["hide_code"] is True+ assert second["analysis"]["refs"] == ["x"]+ assert document["order"] == [first["id"], second["id"]]+ assert document["app_config"] == {"width": "full"}+ assert document["policy"] == "autorun"+ assert document["saved_etag"] == document["etag"]+ assert all(+ c["notebook_id"] == harness.notebook_id for c in (first, second)+ )++ # A filtered stream is a snapshot of the document alone, and a second+ # connection reuses the loaded document.+ response, _, disconnect = request(+ harness.app,+ "GET",+ f"/notebooks/{harness.notebook_id}/events",+ headers=AUTH,+ query="types=cell,document",+ )+ await wait_for(response, until_ready)+ disconnect()+ assert response.names() == ["cell", "cell", "document", "ready"]+ assert response.records[2]["data"]["document"] == document+++async def test_an_unreadable_notebook_stays_in_the_catalog_and_can_retry(+ harness: Harness,+) -> None:+ file = harness.root / "forecasts.py"+ file.write_text("print('not a notebook')\n")+ notebook_id = harness.notebook_id++ response = await finished(+ harness.app,+ "GET",+ f"/notebooks/{notebook_id}/events",+ headers=AUTH,+ )+ assert response.status == 409+ assert harness.host.peek_notebook(notebook_id) is None+ assert notebook_id in harness.host.notebooks+ assert harness.backends == {}++ file.write_text(NOTEBOOK)+ notebook = await harness.host.notebook(notebook_id)+ assert [cell.code for cell in notebook.document] == [+ "x = 21",+ "y = x * 2",+ ]+++async def test_deleting_an_unreadable_notebook_does_not_initialize_it(+ harness: Harness,+) -> None:+ file = harness.root / "forecasts.py"+ file.write_text("print('not a notebook')\n")+ notebook_id = harness.notebook_id+ response = await finished(+ harness.app,+ "DELETE",+ f"/notebooks/{notebook_id}",+ headers=key("delete-unreadable"),+ )+ assert response.status == 204+ assert notebook_id not in harness.host.notebooks+ assert not file.exists()+ assert harness.backends == {}diff --git a/tests/_server/host/test_host_bridge.py b/tests/_server/host/test_host_bridge.pyindex ded6f6051a..7b96cbfc11 100644--- a/tests/_server/host/test_host_bridge.py+++ b/tests/_server/host/test_host_bridge.py@@ -3,10 +3,12 @@from __future__ import annotations+import asynciofrom typing import TYPE_CHECKINGimport pytest+from marimo._config.manager import MarimoConfigManagerfrom marimo._core import protocolfrom marimo._core.errors import Conflictfrom marimo._core.stream import Event@@ -24,7 +26,10 @@ from tests._server.host.conftest import FakeManager, FakeSessionif TYPE_CHECKING:from pathlib import Path+ from typing import Any+ from marimo._config.manager import UserConfigStore+ from marimo._core.document import CellSource, Policyfrom marimo._session.consumer import SessionConsumer@@ -36,6 +41,130 @@ def prepare(manager: FakeManager, root: Path, *names: str) -> None:manager.workspace = FixedFilesWorkspace(files, directory=str(root))+NOTEBOOK = """import marimo++__generated_with = "0.0.0"+app = marimo.App()++def _():+ x = 1+ return (x,)+"""+++ ("server_policy", "script_policy", "expected"),+ [+ ("autorun", None, "autorun"),+ ("lazy", None, "lazy"),+ ("autorun", "lazy", "lazy"),+ ("lazy", "autorun", "autorun"),+ ],+)+async def test_initial_policy_inherits_server_config_with_script_overrides(+ manager: FakeManager,+ tmp_path: Path,+ user_config_manager: UserConfigStore,+ server_policy: Policy,+ script_policy: Policy | None,+ expected: Policy,+) -> None:+ prepare(manager, tmp_path, "a.py")+ path = tmp_path / "a.py"+ header = (+ "# /// script\n"+ "# [tool.marimo.runtime]\n"+ f'# on_cell_change = "{script_policy}"\n'+ "# ///\n"+ if script_policy is not None+ else ""+ )+ path.write_text(header + NOTEBOOK)+ config = MarimoConfigManager(user_config_manager).with_overrides(+ {"runtime": {"on_cell_change": server_policy}}+ )+ bridge = SessionBridge(manager, config) # type: ignore[arg-type]+ await bridge.open()+ record = bridge.index.notebook_for(str(path))+ assert record is not None++ notebook = await bridge.host.notebook(record.id)++ assert notebook.document._record.policy == expected+ assert notebook.runtime is None+ assert manager.starts == []+ bridge.close()+++async def test_initial_policy_uses_the_adopted_sessions_effective_config(+ manager: FakeManager,+ tmp_path: Path,+ user_config_manager: UserConfigStore,+) -> None:+ prepare(manager, tmp_path, "a.py")+ path = tmp_path / "a.py"+ path.write_text(NOTEBOOK)+ config = MarimoConfigManager(user_config_manager).with_overrides(+ {"runtime": {"on_cell_change": "autorun"}}+ )+ session = FakeSession(str(path))+ session.config_manager = config.with_overrides(+ {"runtime": {"on_cell_change": "lazy"}}+ )+ manager.sessions["browser"] = session+ bridge = SessionBridge(manager, config) # type: ignore[arg-type]++ await bridge.open()++ record = bridge.index.notebook_for(str(path))+ assert record is not None+ notebook = await bridge.host.notebook(record.id)+ assert notebook.document._record.policy == "lazy"+ assert notebook.runtime is not None+ bridge.close()+++async def test_an_adopted_document_is_saved_as_far_as_the_file_goes(+ manager: FakeManager, tmp_path: Path+) -> None:+ from marimo._messaging.notebook import SetCode, Transaction+ from marimo._session.notebook import AppFileManager++ prepare(manager, tmp_path, "saved.py", "edited.py")+ sessions = {}+ for name in ("saved.py", "edited.py"):+ path = tmp_path / name+ path.write_text(NOTEBOOK)+ session = FakeSession(str(path))+ session.document = AppFileManager(str(path)).app.cell_manager.document+ session.app_file_manager.app.config.asdict_difference.return_value = {}+ sessions[name] = manager.sessions[name] = session+ edited = sessions["edited.py"].document+ edited.apply(+ Transaction(+ changes=(SetCode(edited.cell_ids[0], "x = 2"),), source="frontend"+ )+ )+ bridge = SessionBridge(manager) # type: ignore[arg-type]+ await bridge.open()++ documents = {}+ for name in ("saved.py", "edited.py"):+ record = bridge.index.notebook_for(str(tmp_path / name))+ assert record is not None+ document = (await bridge.host.notebook(record.id)).document+ assert document is not None+ documents[name] = document._record++ # A session showing the file as it is on disk is saved.+ assert documents["saved.py"].saved_etag == documents["saved.py"].etag+ # One with an edit the file lacks is not, and names the file's revision.+ assert documents["edited.py"].saved_etag != documents["edited.py"].etag+ assert documents["edited.py"].saved_etag == documents["saved.py"].etag+ bridge.close()++async def test_sessions_present_and_created_are_adopted(manager: FakeManager, tmp_path: Path) -> None:@@ -44,11 +173,11 @@ async def test_sessions_present_and_created_are_adopted(manager.sessions["browser-1"] = existingbridge = SessionBridge(manager) # type: ignore[arg-type]- bridge.open()+ await bridge.open()a = bridge.index.notebook_for(str(tmp_path / "a.py"))assert a is not None- runtime = bridge.host.notebook(a.id).runtime+ runtime = (await bridge.host.notebook(a.id)).runtimeassert runtime is not Noneassert runtime.status == "running"assert existing.consumers[0][1] is False@@ -57,7 +186,7 @@ async def test_sessions_present_and_created_are_adopted(await manager.event_bus.emit_session_created(created) # type: ignore[arg-type]b = bridge.index.notebook_for(str(tmp_path / "b.py"))assert b is not None- assert bridge.host.notebook(b.id).runtime is not None+ assert (await bridge.host.notebook(b.id)).runtime is not Noneunknown = FakeSession(str(tmp_path.parent / "elsewhere.py"))await manager.event_bus.emit_session_created(unknown) # type: ignore[arg-type]@@ -65,15 +194,72 @@ async def test_sessions_present_and_created_are_adopted(bridge.close()+async def test_delete_during_adoption_preserves_the_file_and_session(+ manager: FakeManager,+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ prepare(manager, tmp_path, "a.py")+ path = tmp_path / "a.py"+ path.write_text(NOTEBOOK)+ bridge = SessionBridge(manager) # type: ignore[arg-type]+ await bridge.open()+ record = bridge.index.notebook_for(str(path))+ assert record is not None+ session = FakeSession(str(path))+ started, release, deleting = (+ asyncio.Event(),+ asyncio.Event(),+ asyncio.Event(),+ )+ load = bridge._load++ async def paused_load(+ file: Path,+ ) -> tuple[list[CellSource], dict[str, Any]] | None:+ started.set()+ await release.wait()+ return await load(file)++ async def delete() -> None:+ deleting.set()+ await bridge.delete(record.id, request_id="delete")++ monkeypatch.setattr(bridge, "_load", paused_load)+ adoption = asyncio.create_task(+ manager.event_bus.emit_session_created(session) # type: ignore[arg-type]+ )+ await asyncio.wait_for(started.wait(), 5)+ deletion = asyncio.create_task(delete())+ try:+ # Queue deletion on the file lock before initialization finishes.+ await asyncio.wait_for(deleting.wait(), 5)+ release.set()+ with pytest.raises(Conflict, match="runtime"):+ await asyncio.wait_for(deletion, 5)+ await asyncio.wait_for(adoption, 5)++ notebook = await bridge.host.notebook(record.id)+ assert notebook.runtime is not None+ assert notebook.runtime.status == "running"+ assert path.read_text() == NOTEBOOK+ assert bridge._backends[record.id].session is session+ assert not session.closed+ finally:+ release.set()+ await asyncio.gather(adoption, deletion, return_exceptions=True)+ bridge.close()++async def test_a_subscriber_can_stop_an_adopted_session(manager: FakeManager, tmp_path: Path) -> None:prepare(manager, tmp_path, "a.py")bridge = SessionBridge(manager) # type: ignore[arg-type]- bridge.open()+ await bridge.open()record = bridge.index.notebook_for(str(tmp_path / "a.py"))assert record is not None- notebook = bridge.host.notebook(record.id)+ notebook = await bridge.host.notebook(record.id)session = FakeSession(str(tmp_path / "a.py"))manager.sessions["browser"] = session@@ -105,10 +291,10 @@ async def test_failed_adoption_detaches_without_closing_the_session() -> None:prepare(manager, tmp_path, "a.py")bridge = SessionBridge(manager) # type: ignore[arg-type]- bridge.open()+ await bridge.open()record = bridge.index.notebook_for(str(tmp_path / "a.py"))assert record is not None- notebook = bridge.host.notebook(record.id)+ notebook = await bridge.host.notebook(record.id)session = FakeSession(str(tmp_path / "a.py"))connect = session.connect_consumer@@ -148,7 +334,7 @@ async def test_a_rename_keeps_the_notebook_id() -> None:prepare(manager, tmp_path, "a.py")bridge = SessionBridge(manager) # type: ignore[arg-type]- bridge.open()+ await bridge.open()notebook = bridge.index.notebook_for(str(tmp_path / "a.py"))assert notebook is not None(tmp_path / "a.py").rename(tmp_path / "renamed.py")@@ -172,10 +358,10 @@ async def test_session_updates_after_catalog_removal_are_ignored(session = FakeSession(str(tmp_path / "a.py"))manager.sessions["browser"] = sessionbridge = SessionBridge(manager) # type: ignore[arg-type]- bridge.open()+ await bridge.open()record = bridge.index.notebook_for(str(tmp_path / "a.py"))assert record is not None- notebook = bridge.host.notebook(record.id)+ notebook = await bridge.host.notebook(record.id)bridge.index.forget(record.id)cursor = bridge.host.events()[-1].idassert cursor is not None@@ -202,7 +388,7 @@ async def test_removed_runs_release_backend_translation_state(bridge = SessionBridge(manager) # type: ignore[arg-type]now = 0.0bridge.host.clock = lambda: now- bridge.open()+ await bridge.open()record = bridge.index.notebook_for(str(tmp_path / "a.py"))assert record is not Nonebackend = bridge._backends[record.id]@@ -242,10 +428,10 @@ async def test_failed_session_move_preserves_the_notebook(session = FakeSession(str(source))manager.sessions["browser"] = sessionbridge = SessionBridge(manager) # type: ignore[arg-type]- bridge.open()+ await bridge.open()notebook = bridge.index.notebook_for(str(source))assert notebook is not None- runtime = bridge.host.notebook(notebook.id).runtime+ runtime = (await bridge.host.notebook(notebook.id)).runtimeasync def rename(_session_id: str, _path: str) -> tuple[bool, str | None]:return False, "The notebook is busy"@@ -256,5 +442,5 @@ async def test_failed_session_move_preserves_the_notebook(assert source.exists()assert not target.exists()assert bridge.host.notebooks[notebook.id].path == "a.py"- assert bridge.host.notebook(notebook.id).runtime is runtime+ assert (await bridge.host.notebook(notebook.id)).runtime is runtimebridge.close()diff --git a/tests/_server/host/test_host_execution.py b/tests/_server/host/test_host_execution.pyindex 9d415096b2..44f461b67c 100644--- a/tests/_server/host/test_host_execution.py+++ b/tests/_server/host/test_host_execution.py@@ -4,12 +4,12 @@from __future__ import annotationsimport asyncio-import hashlibimport jsonfrom typing import TYPE_CHECKINGimport pytest+from marimo._core.document import code_hashfrom marimo._server.host.bridge import SessionBridgefrom marimo._server.host.context import HostContextfrom marimo._server.main import create_starlette_app@@ -63,7 +63,7 @@ async def live_host(app = create_starlette_app(base_url="", enable_auth=True)get_starlette_server_state_init(session_manager=manager).apply(app.state)bridge = SessionBridge(manager)- bridge.open()+ await bridge.open()app.state.host_context = HostContext(bridge=bridge, token="execution-test", port=PORT)@@ -100,7 +100,7 @@ async def test_move_preserves_the_running_notebook() -> None:app, notebook_id, events = live_hosthost = app.state.host_context.bridge.host- runtime = host.notebook(notebook_id).runtime+ runtime = (await host.notebook(notebook_id)).runtimesource, target = tmp_path / "notebook.py", tmp_path / "moved.py"session = next(iter(app.state.session_manager.sessions.values()))cells = list(session.app_file_manager.app.cell_manager.codes())@@ -120,7 +120,7 @@ async def test_move_preserves_the_running_notebook(assert not source.exists()assert list(AppFileManager(str(target)).app.cell_manager.codes()) == cellsassert session.app_file_manager.path == str(target)- assert host.notebook(notebook_id).runtime == runtime+ assert (await host.notebook(notebook_id)).runtime == runtimeaccepted = await finished(app,@@ -709,8 +709,8 @@ async def test_a_fixed_cell_replaces_its_failed_compilation(and r["data"]["execution"]["status"] == "completed"]assert [(e["code_hash"], e["outcome"]["kind"]) for e in executions] == [- (hashlib.sha256(b"if !!!").hexdigest(), "error"),- (hashlib.sha256(b"x = 42").hexdigest(), "value"),+ (code_hash("if !!!"), "error"),+ (code_hash("x = 42"), "value"),]assert len({e["id"] for e in executions}) == 2runs = [@@ -828,9 +828,7 @@ async def test_awaited_commands_join_the_enclosing_run(assert root["outcome"]["kind"] == "value"assert "42" in root["outcome"]["display"]["data"]assert child["outcome"]["kind"] == "error"- assert (- child["code_hash"] == hashlib.sha256(child_code.encode()).hexdigest()- )+ assert child["code_hash"] == code_hash(child_code)assert all(e["run_id"] == accepted.json()["id"] for e in executions)diff --git a/tests/_server/host/test_host_index.py b/tests/_server/host/test_host_index.pyindex 936a19eeba..e653ad779b 100644--- a/tests/_server/host/test_host_index.py+++ b/tests/_server/host/test_host_index.py@@ -16,7 +16,12 @@ from marimo._core.stream import Eventfrom marimo._server.host.index import WorkspaceIndexfrom marimo._server.models.home import MarimoFilefrom marimo._server.workspace import FixedFilesWorkspace-from tests._core.conftest import ScriptedBackend, names, runtime_id_of+from tests._core.conftest import (+ ScriptedBackend,+ make_notebook,+ names,+ runtime_id_of,+)def workspace(root: Path, *names: str) -> FixedFilesWorkspace:@@ -37,7 +42,7 @@ def test_refresh_publishes_the_project_and_its_notebooks(index = WorkspaceIndex(host,workspace(tmp_path, "a.py", "sub/b.py"),- lambda _: ScriptedBackend(),+ make_notebook,)index.refresh()@@ -61,9 +66,7 @@ def test_refresh_publishes_the_project_and_its_notebooks(def test_ids_survive_a_rescan_and_a_move(tmp_path: Path) -> None:host = Host(operations=[])- index = WorkspaceIndex(- host, workspace(tmp_path, "a.py"), lambda _: ScriptedBackend()- )+ index = WorkspaceIndex(host, workspace(tmp_path, "a.py"), make_notebook)index.refresh()(notebook,) = host.notebooks.values()log: list[Event] = []@@ -84,10 +87,10 @@ def test_ids_survive_a_rescan_and_a_move(tmp_path: Path) -> None:assert index.file_of(notebook.id) == tmp_path / "b.py"-def test_a_deleted_file_leaves_the_catalog(tmp_path: Path) -> None:+async def test_a_deleted_file_leaves_the_catalog(tmp_path: Path) -> None:host = Host(operations=[])ws = workspace(tmp_path, "a.py", "b.py")- index = WorkspaceIndex(host, ws, lambda _: ScriptedBackend())+ index = WorkspaceIndex(host, ws, make_notebook)index.refresh()removed = index.notebook_for(str(tmp_path / "b.py"))assert removed is not None@@ -99,7 +102,7 @@ def test_a_deleted_file_leaves_the_catalog(tmp_path: Path) -> None:assert [n.path for n in host.notebooks.values()] == ["a.py"]with pytest.raises(NotFound):- host.notebook(removed.id)+ (await host.notebook(removed.id))(tmp_path / "b.py").write_text("import marimo\n")recreated = index.ensure(str(tmp_path / "b.py"))@@ -110,9 +113,7 @@ def test_a_deleted_file_leaves_the_catalog(tmp_path: Path) -> None:def test_ensure_admits_a_file_the_listing_missed(tmp_path: Path) -> None:host = Host(operations=[])- index = WorkspaceIndex(- host, workspace(tmp_path, "a.py"), lambda _: ScriptedBackend()- )+ index = WorkspaceIndex(host, workspace(tmp_path, "a.py"), make_notebook)index.refresh()(tmp_path / "c.py").write_text("")@@ -127,14 +128,18 @@ def test_ensure_admits_a_file_the_listing_missed(tmp_path: Path) -> None:assert admitted.id in host.notebooks-def test_deleted_file_keeps_its_runtime_until_stopped(tmp_path: Path) -> None:+async def test_deleted_file_keeps_its_runtime_until_stopped(+ tmp_path: Path,+) -> None:host = Host(operations=[])ws = workspace(tmp_path, "a.py")backend = ScriptedBackend()- index = WorkspaceIndex(host, ws, lambda _: backend)+ index = WorkspaceIndex(+ host, ws, lambda record, sink: make_notebook(record, sink, backend)+ )index.refresh()(record,) = host.notebooks.values()- notebook = host.notebook(record.id)+ notebook = await host.notebook(record.id)notebook.start()notebook.observe(be.Running(runtime_id_of(notebook)))runtime = notebook.runtimediff --git a/tests/_server/host/test_host_record.py b/tests/_server/host/test_host_record.pyindex 2b67e2bed2..42e039b85b 100644--- a/tests/_server/host/test_host_record.py+++ b/tests/_server/host/test_host_record.py@@ -21,6 +21,7 @@ from marimo._server.main import create_starlette_appfrom marimo._utils.lifespans import Lifespansfrom tests._core.conftest import (ScriptedBackend,+ add_notebook,project,record,runtime_id_of,@@ -139,7 +140,7 @@ async def test_idle_host_expires_results_and_stops_maintenance(now = 0.0host.clock = context.clock = lambda: nowhost.update_project(project())- notebook = host.add_notebook(record(), ScriptedBackend())+ notebook = await add_notebook(host, record(), ScriptedBackend())notebook.adopt(lambda _: None)notebook.observe(be.Running(runtime_id_of(notebook)))headers = {diff --git a/tests/_server/host/test_host_translate.py b/tests/_server/host/test_host_translate.pyindex d32572c8d4..1d285ecaf2 100644--- a/tests/_server/host/test_host_translate.py+++ b/tests/_server/host/test_host_translate.py@@ -3,8 +3,6 @@from __future__ import annotations-import hashlib-import pytestfrom dirty_equals import IsStrfrom inline_snapshot import snapshot@@ -17,6 +15,7 @@ from marimo._core.backend import (Produced,Status,)+from marimo._core.document import code_hashfrom marimo._core.protocol import (Console,DisplayData,@@ -91,7 +90,7 @@ def test_a_run_that_prints_and_shows_a_value() -> None:PlannedExecution(id=ExecutionId("r1-1"),cell_id=None,- code_hash=hashlib.sha256(b"3 * 3").hexdigest(),+ code_hash=code_hash("3 * 3"),code="3 * 3",caused_by=None,),